v2.0

.gitignore

@@ -1,9 +1,13 @@
+# =============================================================================
 # Python
+# =============================================================================
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
 .Python
+
+# Distribution / packaging
 build/
 develop-eggs/
 dist/
@@ -20,32 +24,96 @@ wheels/
 .installed.cfg
 *.egg
 MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
 
-# Virtual Environments
+# =============================================================================
+# Virtual environments / dependency managers
+# =============================================================================
 venv/
 env/
 .env
+.env.*
+!.env.example
 .venv/
+.python-version
+.tool-versions
+
+# =============================================================================
+# Test / type / lint caches
+# =============================================================================
+.pytest_cache/
+.cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
 
-# IDEs
+# =============================================================================
+# IDEs / editors
+# =============================================================================
 .idea/
 .vscode/
 *.swp
 *.swo
+*~
+*.iml
+.project
+.pydevproject
 
-# macOS
+# =============================================================================
+# OS noise
+# =============================================================================
 .DS_Store
 .AppleDouble
 .LSOverride
+Thumbs.db
+desktop.ini
 
-# Project Specific Outputs
-*.txt
-*.md
-!README.md
+# =============================================================================
+# Gradio / Hugging Face Spaces
+# =============================================================================
+.gradio/
+gradio_cached_examples/
+flagged/
+
+# =============================================================================
+# BibGuard outputs (generated by main.py / app.py)
+# =============================================================================
+bibguard_output/
+*_only_used.bib
 *_only_used_entry.bib
+bibliography_report.md
+latex_quality_report.md
+line_by_line_report.md
+report.html
+report.json
+# Local HTTP cache used by src/utils/http.py
+.cache/bibguard/
+**/.cache/bibguard/
+
+# =============================================================================
+# User secrets / personal config
+# Recommendation: ship `bibguard.example.yaml` and gitignore the real one
+# so API keys / personal paths don't leak. See README for details.
+# =============================================================================
+# bibguard.yaml
+config.yaml
+.bibguard.yaml
+.bibguard.yml
+secrets.yaml
+*.local.yaml
 
-# LaTeX and Bibliography (User Data)
-# Ignoring these to prevent committing personal paper content
+# =============================================================================
+# User paper data (LaTeX / BibTeX sources and build artifacts)
+# Keep README.md, requirements*.txt, and source-tree .md files.
+# =============================================================================
 *.tex
 *.bib
 *.pdf
@@ -57,6 +125,22 @@ env/
 *.synctex.gz
 *.fls
 *.fdb_latexmk
+*.toc
+*.lof
+*.lot
+*.nav
+*.snm
+*.vrb
 
-# cache
-.cache
+# Markdown / text files: ignore by default to prevent committing user paper
+# content, but keep documentation and project metadata.
+*.txt
+*.md
+!README.md
+!CHANGELOG.md
+!CONTRIBUTING.md
+!LICENSE.md
+!docs/**/*.md
+!requirements.txt
+!requirements-*.txt
+!**/requirements.txt

README.md

@@ -11,35 +11,46 @@ pinned: false
 
 # BibGuard: Bibliography & LaTeX Quality Auditor
 
-**BibGuard** is your comprehensive quality assurance tool for academic papers. It validates bibliography entries against real-world databases and checks LaTeX submission quality to catch errors before you submit.
+**BibGuard** is a comprehensive quality-assurance tool for academic papers. It validates every bibliography entry against real-world databases, checks LaTeX submission quality, flags retracted DOIs and broken URLs, and uses an LLM (optional) to verify that cited papers actually support your claims.
 
-AI coding assistants and writing tools often hallucinate plausible-sounding but non-existent references. **BibGuard** verifies the existence of every entry against multiple databases (arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, Google Scholar) and uses advanced LLMs to ensure cited papers actually support your claims.
+AI coding assistants and writing tools often hallucinate plausible-sounding but non-existent references. **BibGuard** verifies the existence of every entry against multiple databases (arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, Google Scholar) and produces a single, beautiful, self-contained HTML report you can open offline.
 
 ## 🛡 Why BibGuard?
 
--   **🚫 Stop Hallucinations**: Instantly flag citations that don't exist or have mismatched metadata
--   **📋 LaTeX Quality Checks**: Detect formatting issues, weak writing patterns, and submission compliance problems
--   **🔒 Safe & Non-Destructive**: Your original files are **never modified** - only detailed reports are generated
--   **🧠 Contextual Relevance**: Ensure cited papers actually discuss what you claim (with LLM)
--   **⚡ Efficiency Boost**: Drastically reduce time needed to manually verify hundreds of citations
+- **🚫 Stop Hallucinations**: Instantly flag citations that don't exist or have mismatched metadata
+- **🚫 Catch Retractions**: Detect references to papers that have been retracted or are under "expression of concern"
+- **🔗 Detect Broken URLs**: HEAD-check `entry.url` to find dead links before reviewers do
+- **📋 LaTeX Quality Checks**: Detect formatting issues, weak writing patterns, double-blind compliance, AI-text artifacts
+- **🔒 Safe & Non-Destructive**: Your original files are **never modified** — only reports are generated
+- **🧠 Contextual Relevance** *(optional, with LLM)*: Score each citation 1-5 and tag its role (baseline/method/dataset/counterexample/survey/motivation/other)
+- **⚡ Re-runs are fast**: SQLite-backed HTTP cache + auto-retry mean the second run on the same paper completes in seconds
 
 ## 🚀 Features
 
 ### Bibliography Validation
--   **🔍 Multi-Source Verification**: Validates metadata against arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar
--   **🤖 AI Relevance Check**: Uses LLMs to verify citations match their context (optional)
--   **📊 Preprint Detection**: Warns if >50% of references are preprints (arXiv, bioRxiv, etc.)
--   **👀 Usage Analysis**: Highlights missing citations and unused bib entries
--   **👯 Duplicate Detector**: Identifies duplicate entries with fuzzy matching
+- **🔍 Multi-Source Verification**: Validates metadata against arXiv, CrossRef, DBLP, Semantic Scholar, OpenAlex, and Google Scholar
+- **🚫 Retraction Detection**: Flags retracted/withdrawn DOIs via CrossRef's `update-to` relation
+- **🔗 URL Liveness Check**: Optional HEAD-then-GET check on every `entry.url`
+- **📊 Preprint Detection**: Warns if >50% of references are preprints, and suggests published versions when arXiv records them
+- **👀 Usage Analysis**: Highlights missing citations and unused bib entries
+- **👯 Duplicate Detection**: Identifies duplicate entries with fuzzy matching
+- **🤖 AI Relevance + Role Tagging** *(optional)*: 1-5 relevance score plus citation role classification
 
 ### LaTeX Quality Checks
--   **📐 Format Validation**: Caption placement, cross-references, citation spacing, equation punctuation
--   **✍️ Writing Quality**: Weak sentence starters, hedging language, redundant phrases
--   **🔤 Consistency**: Spelling variants (US/UK English), hyphenation, terminology
--   **🤖 AI Artifact Detection**: Conversational AI responses, placeholder text, Markdown remnants
--   **🔠 Acronym Validation**: Ensures acronyms are defined before use (smart matching)
--   **🎭 Anonymization**: Checks for identity leaks in double-blind submissions
--   **📅 Citation Age**: Flags references older than 30 years
+- **📐 Format Validation**: Caption placement, cross-references, citation spacing, equation punctuation
+- **✍️ Writing Quality**: Weak sentence starters, hedging language, redundant phrases
+- **🔤 Consistency**: Spelling variants (US/UK English), hyphenation, terminology — augmentable via project glossary
+- **🤖 AI Artifact Detection**: Conversational AI responses, placeholder text, Markdown remnants
+- **🔠 Acronym Validation**: Ensures acronyms are defined before use, with a project-glossary skip list
+- **🎭 Anonymization**: Checks for identity leaks in double-blind submissions
+- **📅 Citation Age**: Flags references older than 30 years
+- **🎓 Conference Templates**: Mandatory-section and style-package checks for ACL, EMNLP, NAACL, CVPR, ICCV, ECCV, NeurIPS, ICML, ICLR
+
+### Outputs
+- 📄 **Markdown reports** — bibliography validation + LaTeX quality issues
+- 🌐 **Self-contained HTML** — dark mode, full-text search, per-section severity filters, inline highlighting of the offending span on each LaTeX issue. Opens offline, no server required
+- 🤖 **JSON** for CI / scripts / custom dashboards
+- 🧹 **Cleaned `.bib`** containing only entries actually cited in the paper
 
 ## 📦 Installation
 
@@ -57,10 +68,9 @@ pip install -r requirements.txt
 python main.py --init
 ```
 
-This creates `config.yaml`. Edit it to set your file paths. You have two modes:
+This creates `config.yaml`. Edit it to point at your `.bib` and `.tex` files.
 
-#### Option A: Single File Mode
-Best for individual papers.
+#### Single File Mode
 ```yaml
 files:
   bib: "paper.bib"
@@ -68,141 +78,186 @@ files:
   output_dir: "bibguard_output"
 ```
 
-#### Option B: Directory Scan Mode
-Best for large projects or a collection of papers. BibGuard will recursively search for all `.tex` and `.bib` files.
+#### Directory Scan Mode
+For projects with multiple `.tex` and `.bib` files:
 ```yaml
 files:
   input_dir: "./my_project_dir"
   output_dir: "bibguard_output"
 ```
 
-### 2. Run Full Check
+### 2. Run a Check
 
 ```bash
-python main.py
+python main.py                          # full check using config.yaml / bibguard.yaml
+python main.py --quick                  # local-only checks (no network, instant)
+python main.py --format json,html       # pick output formats
+python main.py --verbose                # DEBUG logs to stderr
+python main.py --config my.yaml         # custom config path
+python main.py --list-templates         # list conference templates
 ```
 
-**Output** (in `bibguard_output/`):
-- `bibliography_report.md` - Bibliography validation results
-- `latex_quality_report.md` - Writing and formatting issues
-- `line_by_line_report.md` - All issues sorted by line number
-- `*_only_used.bib` - Clean bibliography (used entries only)
+**Default outputs** (in `bibguard_output/`):
+- `report.html` — single self-contained HTML, opens offline, dark-mode aware
+- `report.json` — full machine-readable dump (only when `json` is in `output.formats`)
+- `bibliography_report.md` — bibliography validation, with corroboration notes
+- `latex_quality_report.md` — LaTeX quality issues, errors / warnings / suggestions, full line content with the offending span bolded
+- `<bibname>_only_used.bib` — clean bibliography of cited entries only
 
 ## 🛠 Configuration
 
-Edit `config.yaml` to customize checks:
+`bibguard.yaml` (or `config.yaml`) contains the following sections:
 
 ```yaml
+files:
+  bib: "paper.bib"
+  tex: "paper.tex"
+  output_dir: "bibguard_output"
+
+network:
+  contact_email: ""           # used in polite-pool User-Agent for arXiv/CrossRef/OpenAlex
+  cache_enabled: true         # local SQLite cache for HTTP responses (~/.cache/bibguard)
+  cache_ttl_hours: 24
+  retry_total: 5              # auto-retry on 429/5xx with exponential backoff
+  retry_backoff_factor: 1.5
+
+template: ""                  # acl | emnlp | naacl | cvpr | iccv | eccv | neurips | icml | iclr
+
 bibliography:
-  check_metadata: true        # Validate against online databases (takes time)
-  check_usage: true           # Find unused/missing entries
-  check_duplicates: true      # Detect duplicate entries
-  check_preprint_ratio: true  # Warn if >50% are preprints
+  check_metadata: true        # verify against online databases (slow on first run, fast on repeats)
+  check_usage: true           # find unused entries / missing citations
+  check_duplicates: true
+  check_preprint_ratio: true  # warn if >50% of references are preprints
   check_relevance: false      # LLM-based relevance check (requires API key)
 
-submission:
-  # Format checks
-  caption: true               # Table/figure caption placement
-  reference: true             # Cross-reference integrity
-  formatting: true            # Citation spacing, blank lines
-  equation: true              # Equation punctuation, numbering
-  
-  # Writing quality
-  sentence: true              # Weak starters, hedging language
-  consistency: true           # Spelling, hyphenation, terminology
-  acronym: true               # Acronym definitions (3+ letters)
-  
-  # Submission compliance
-  ai_artifacts: true          # AI-generated text detection
-  anonymization: true         # Double-blind compliance
-  citation_quality: true      # Old citations (>30 years)
-  number: true                # Percentage formatting
+submission_extra:
+  url_liveness: false         # HEAD-check every entry.url field (slow)
+  retraction: true            # flag retracted DOIs via CrossRef
+
+submission:                   # 11 LaTeX checkers — toggle each independently
+  caption: true
+  reference: true
+  formatting: true
+  equation: true
+  ai_artifacts: true
+  sentence: true
+  consistency: true
+  acronym: true
+  number: true
+  citation_quality: true
+  anonymization: true
+
+# Project glossary feeds the consistency / acronym checkers.
+glossary:
+  preferred:
+    - "Transformer"
+    - "fine-tuning"
+  acronyms:
+    NLP: "Natural Language Processing"
+    LLM: "Large Language Model"
+
+llm:
+  backend: "gemini"           # gemini | openai | anthropic | deepseek | ollama | vllm
+  model: ""                   # leave empty for sensible default per backend
+  api_key: ""                 # PREFER env var: $GEMINI_API_KEY / $OPENAI_API_KEY / etc.
+
+output:
+  quiet: false
+  minimal_verified: false
+  formats: [markdown, html]   # any of: markdown, html, json
 ```
 
-## 🤖 LLM-Based Relevance Check
+## 🤖 LLM-Based Relevance + Role Tagging
 
-To verify citations match their context using AI:
+When `bibliography.check_relevance` is `true`, BibGuard sends each citation's surrounding context plus the cited paper's abstract to your chosen LLM. The model returns a 1-5 relevance score, an `is_relevant` boolean, a one-sentence explanation, and a **citation role**:
 
-```yaml
-bibliography:
-  check_relevance: true
+- `baseline` — cited as a comparison/baseline
+- `method` — cited paper introduces a method this one builds on
+- `dataset` — provides a dataset/benchmark used here
+- `counterexample` — cited to argue against
+- `survey` — cited as a survey/overview
+- `motivation` — cited to motivate the problem
+- `other`
 
-llm:
-  backend: "gemini"  # Options: gemini, openai, anthropic, deepseek, ollama, vllm
-  api_key: ""        # Or use environment variable (e.g., GEMINI_API_KEY)
+**Supported backends**: Gemini, OpenAI, Anthropic, DeepSeek, Ollama (local), vLLM (custom endpoint).
+
+**API keys**: read from environment variables by convention — `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`. Set them in your shell rather than committing `api_key:` to `bibguard.yaml`.
+
+## 🌐 Web UI
+
+```bash
+python app.py
 ```
 
-**Supported Backends:**
-- **Gemini** (Google): `GEMINI_API_KEY`
-- **OpenAI**: `OPENAI_API_KEY`
-- **Anthropic**: `ANTHROPIC_API_KEY`
-- **DeepSeek**: `DEEPSEEK_API_KEY` (recommended for cost/performance)
-- **Ollama**: Local models (no API key needed)
-- **vLLM**: Custom endpoint
+Opens at `http://localhost:7860`. The web UI mirrors the CLI but with a streaming status panel and three presets:
+
+- **Quick** — local checks only, no network, instant
+- **Standard** — local + retraction lookup (CrossRef)
+- **Strict** — adds multi-source metadata fetch + URL liveness (slow on first run; subsequent runs are cached)
+
+The toolbar fits in one row: file uploads, preset chips, and Run / Stop. Per-check overrides live in the **Advanced** accordion. The report renders inline as a self-contained iframe so the page stays stable while entries stream in. Downloads (HTML, Markdown bib, JSON, cleaned `.bib`, `bibguard.log`) appear in the **Downloads** accordion below.
+
+Set `BIBGUARD_CONTACT_EMAIL=you@example.com` in your shell to use a real contact in the polite-pool User-Agent.
+
+## 🪝 Pre-commit Hook
+
+To run BibGuard automatically before each commit that touches `.tex` or `.bib`:
 
-Then run:
 ```bash
-python main.py
+cd /path/to/your-paper-repo
+bash /path/to/BibGuard/scripts/install-hook.sh
 ```
 
+Skip the hook for one commit with `git commit --no-verify`.
+
 ## 📝 Understanding Reports
 
-### Bibliography Report
-Shows for each entry:
-- ✅ **Verified**: Metadata matches online databases
-- ⚠️ **Issues**: Mismatches, missing entries, duplicates
-- 📊 **Statistics**: Usage, duplicates, preprint ratio
+### Self-Contained HTML (`report.html`)
+The recommended output. Single file, no external assets, dark-mode aware. Includes:
+- Three tabs: **Bibliography** · **LaTeX Quality** · **Retractions / URLs**
+- **Per-section filter chips** — bibliography filters by Verified / Unverified / Unused; LaTeX quality filters by Errors / Warnings / Info
+- **Full-text search** across titles, authors, keys, and messages — works inside the active tab
+- **Inline span highlighting** — for LaTeX issues that come from a regex (e.g., `\cite{}` without `~`), the offending substring is wrapped in `<mark>` so you can see exactly *where* in the line to look
+- **Honest empty states** — Retractions / URL liveness panels report how many entries actually carried a `doi=` / `url=` field, so an empty result no longer looks like the check failed silently
+- Theme toggle that overrides system preference
 
-### LaTeX Quality Report
-Organized by severity:
-- 🔴 **Errors**: Critical issues (e.g., undefined references)
-- 🟡 **Warnings**: Important issues (e.g., inconsistent spelling)
-- 🔵 **Suggestions**: Style improvements (e.g., weak sentence starters)
+### Markdown Reports
+Two files for granular review and code review tooling:
+- `bibliography_report.md` — every entry with metadata-match status, including positive **corroboration notes** when a second source agreed
+- `latex_quality_report.md` — issues grouped by checker and severity, full line content with the offending span bolded
 
-### Line-by-Line Report
-All LaTeX issues sorted by line number for easy fixing.
+### JSON Output
+Machine-readable dump for CI integration. Top-level keys: `meta`, `summary`, `entries`, `submission_results`, `retractions`, `url_findings`, `duplicates`, `missing_citations`.
 
 ## 🧐 Understanding Mismatches
 
 BibGuard is strict, but false positives happen:
 
-1.  **Year Discrepancy (±1 Year)**:
-    - *Reason*: Delay between preprint (arXiv) and official publication
-    - *Action*: Verify which version you intend to cite
-
-2.  **Author List Variations**:
-    - *Reason*: Different databases handle large author lists differently
-    - *Action*: Check if primary authors match
-
-3.  **Venue Name Differences**:
-    - *Reason*: Abbreviations vs. full names (e.g., "NeurIPS" vs. "Neural Information Processing Systems")
-    - *Action*: Both are usually correct
+1. **Year Discrepancy (±1 Year)** — preprint vs. official publication. Verify which version you intend to cite.
+2. **Author List Variations** — different databases truncate large author lists differently. Check primary authors.
+3. **Venue Name Differences** — abbreviations vs. full names (e.g., "NeurIPS" vs. "Neural Information Processing Systems"). Both usually correct.
+4. **Non-Academic Sources** — blogs and documentation aren't indexed by academic databases. Verify URL and title manually.
 
-4.  **Non-Academic Sources**:
-    - *Reason*: Blogs, documentation not indexed by academic databases
-    - *Action*: Manually verify URL and title
+## 🔧 Performance Notes
 
-## 🔧 Advanced Options
-
-```bash
-python main.py --help              # Show all options
-python main.py --list-templates    # List conference templates
-python main.py --config my.yaml    # Use custom config file
-```
+- **First run** with `check_metadata: true` on ~100 entries: 1-3 minutes (rate-limited by arXiv/CrossRef).
+- **Re-runs**: seconds, thanks to the SQLite HTTP cache at `~/.cache/bibguard/http_cache.sqlite` (TTL 24h by default).
+- **Quick mode** (`python main.py --quick`) bypasses all network calls; runs in <1 second on most papers.
+- **Retraction lookup** is concurrent; ~5-10 seconds for 100 entries with cache cold.
 
 ## 🤝 Contributing
 
-Contributions welcome! Please open an issue or pull request.
+Contributions welcome. Open an issue or pull request.
 
 ## 🙏 Acknowledgments
 
-BibGuard uses multiple data sources:
-- arXiv API
-- CrossRef API
-- Semantic Scholar API
-- DBLP API
-- OpenAlex API
-- Google Scholar (via scholarly)
+BibGuard uses the following data sources:
+- [arXiv API](https://info.arxiv.org/help/api/index.html)
+- [CrossRef REST API](https://api.crossref.org)
+- [Semantic Scholar Graph API](https://api.semanticscholar.org)
+- [DBLP API](https://dblp.org/faq/How+to+use+the+dblp+search+API.html)
+- [OpenAlex API](https://docs.openalex.org)
+- Google Scholar (via scraping; rate-limited)
 
 ---
 

app.py

@@ -1,927 +1,1243 @@
 #!/usr/bin/env python3
 """
-BibGuard Gradio Web Application
+BibGuard Gradio web app — minimalist iframe layout.
 
-A web interface for checking bibliography and LaTeX quality.
+The right pane embeds the self-contained ``report.html`` produced by
+``src/report/html_report.py`` via ``<iframe srcdoc=...>``. This makes the
+generated report the single source of truth (per-section filters, full-text
+search, dark mode, inline span highlighting all live inside it) and avoids
+re-rendering the same content inside Gradio with stale styles.
 """
-import gradio as gr
+from __future__ import annotations
+
+import base64
+import logging
+import os
 import tempfile
-import shutil
+import time
 from pathlib import Path
-from typing import Optional, Tuple
-import base64
+
+import gradio as gr
 
 from src.parsers import BibParser, TexParser
-from src.fetchers import ArxivFetcher, CrossRefFetcher, SemanticScholarFetcher, OpenAlexFetcher, DBLPFetcher
+from src.fetchers import (
+    ArxivFetcher, CrossRefFetcher, SemanticScholarFetcher,
+    OpenAlexFetcher, DBLPFetcher,
+)
 from src.analyzers import MetadataComparator, UsageChecker, DuplicateDetector
 from src.report.generator import ReportGenerator, EntryReport
-from src.config.yaml_config import BibGuardConfig, FilesConfig, BibliographyConfig, SubmissionConfig, OutputConfig, WorkflowStep
-from src.config.workflow import WorkflowConfig, WorkflowStep as WFStep, get_default_workflow
+from src.config.yaml_config import (
+    BibGuardConfig, BibliographyConfig, SubmissionConfig, OutputConfig,
+)
+from src.config.workflow import get_default_workflow
 from src.checkers import CHECKER_REGISTRY
-from src.report.line_report import LineByLineReportGenerator
+from src.checkers.retraction_checker import RetractionChecker
+from src.checkers.url_checker import URLChecker
+from src.utils import http as http_layer
+from src.utils.logging_setup import setup as setup_logging, capture_run
+from src.utils.validation import validate_bib, validate_tex, format_report
 from app_helper import fetch_and_compare_with_workflow
 
+LOG_PATH = setup_logging(os.environ.get("BIBGUARD_LOG", "WARNING"))
+logger = logging.getLogger("bibguard.app")
+logger.info("BibGuard app starting (log file: %s)", LOG_PATH)
+
+# Configure HTTP layer once at import time.
+http_layer.configure(
+    contact_email=os.environ.get("BIBGUARD_CONTACT_EMAIL", ""),
+    cache_enabled=True,
+    cache_ttl_hours=24,
+    retry_total=5,
+    retry_backoff_factor=1.5,
+)
+
+
+# --------------------------------------------------------------------- presets
+
+PRESETS = {
+    "Quick": {
+        "check_metadata": False, "check_duplicates": True, "check_usage": True, "check_preprint_ratio": True,
+        "url_liveness": False, "retraction": False,
+        "submission": {"caption": True, "reference": True, "formatting": True, "equation": True,
+                       "ai_artifacts": True, "sentence": True, "consistency": True, "acronym": True,
+                       "number": True, "citation_quality": True, "anonymization": True},
+    },
+    "Standard": {
+        "check_metadata": False, "check_duplicates": True, "check_usage": True, "check_preprint_ratio": True,
+        "url_liveness": False, "retraction": True,
+        "submission": {"caption": True, "reference": True, "formatting": True, "equation": True,
+                       "ai_artifacts": True, "sentence": True, "consistency": True, "acronym": True,
+                       "number": True, "citation_quality": True, "anonymization": True},
+    },
+    "Strict": {
+        "check_metadata": True, "check_duplicates": True, "check_usage": True, "check_preprint_ratio": True,
+        "url_liveness": True, "retraction": True,
+        "submission": {"caption": True, "reference": True, "formatting": True, "equation": True,
+                       "ai_artifacts": True, "sentence": True, "consistency": True, "acronym": True,
+                       "number": True, "citation_quality": True, "anonymization": True},
+    },
+}
+
+
+# ----------------------------------------------------------------------- CSS
 
-# Custom CSS for better Markdown rendering
 CUSTOM_CSS = """
 @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
 
-* {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-}
-"""
+* { font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif; }
 
-WELCOME_HTML = """
-<div class="scrollable-report-area">
-    <div class="report-card" style="max-width: 800px; margin: 0 auto;">
-        <div class="card-header">
-            <h3 class="card-title" style="font-size: 1.5em;">👋 Welcome to BibGuard</h3>
-        </div>
-        <div class="card-content" style="line-height: 1.6; color: #374151;">
-            <p style="font-size: 1.1em; margin-bottom: 24px;">
-                Ensure your academic paper is flawless. Upload your <code>.bib</code> and <code>.tex</code> files on the left and click <strong>"Check Now"</strong>.
-            </p>
-            
-            <div style="display: grid; gap: 20px; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));">
-                <div style="background: #fefce8; padding: 16px; border-radius: 8px; border: 1px solid #fde047;">
-                    <strong style="color: #854d0e; display: block; margin-bottom: 8px;">⚠️ Metadata Check Defaults</strong> 
-                    "🔍 Metadata" is <strong>disabled by default</strong>. It verifies your entries against ArXiv/DBLP/Crossref but takes time (1-3 mins) to fetch data. Enable it if you want strict verification.
-                </div>
-                
-                <div style="background: #eff6ff; padding: 16px; border-radius: 8px; border: 1px solid #bfdbfe;">
-                    <strong style="color: #1e40af; display: block; margin-bottom: 8px;">🚀 Go Pro with Local Version</strong> 
-                    LLM-based context relevance checking (is this citation actually relevant?) is excluded here. Clone the <a href="https://github.com/thinkwee/BibGuard" target="_blank" style="color: #2563eb; text-decoration: underline; font-weight: 600;">GitHub repo</a> to use the full power with your API key.
-                </div>
-            </div>
-            
-            <h4 style="margin: 24px 0 12px 0; color: #111827; font-size: 1.1em;">📊 Understanding Your Reports</h4>
-            <div style="display: grid; gap: 12px;">
-                <div style="display: flex; gap: 12px; align-items: baseline;">
-                    <span style="background: #e0e7ff; color: #3730a3; padding: 2px 8px; border-radius: 4px; font-size: 0.9em; font-weight: 600; white-space: nowrap;">📚 Bibliography</span>
-                    <span>Validates metadata fields, detects duplicates, and checks citation counts.</span>
-                </div>
-                <div style="display: flex; gap: 12px; align-items: baseline;">
-                    <span style="background: #dcfce7; color: #166534; padding: 2px 8px; border-radius: 4px; font-size: 0.9em; font-weight: 600; white-space: nowrap;">📝 LaTeX Quality</span>
-                    <span>Syntax check, caption validation, acronym consistency, and style suggestions.</span>
-                </div>
-                <div style="display: flex; gap: 12px; align-items: baseline;">
-                    <span style="background: #f3f4f6; color: #4b5563; padding: 2px 8px; border-radius: 4px; font-size: 0.9em; font-weight: 600; white-space: nowrap;">📋 Line-by-Line</span>
-                    <span>Maps every issue found directly to the line number in your source file.</span>
-                </div>
-            </div>
-        </div>
-    </div>
-</div>
-"""
-
-CUSTOM_CSS += """
-/* Global Reset */
-body, gradio-app {
-    overflow: hidden !important; /* Prevent double scrollbars on the page */
-}
+/* Reserve space for the vertical scrollbar so expanding the Advanced
+   accordion (or anything else that adds content) doesn't shift the
+   layout horizontally. `overflow-y: scroll` on html is the universal
+   fallback for browsers without scrollbar-gutter.
+   `overflow-x: hidden` on body kills any page-width jitter coming from
+   inner elements that briefly overflow during streaming updates. */
+html { scrollbar-gutter: stable; overflow-y: scroll; overflow-x: hidden; }
+body { overflow-x: hidden; }
 
 .gradio-container {
-    max-width: none !important;
+    max-width: 1400px !important;
+    margin: 0 auto !important;
+    padding: 0 20px !important;
+    box-sizing: border-box !important;
     width: 100% !important;
-    /* height: 100vh !important;  <-- Removed to prevent iframe infinite loop */
-    padding: 0 !important;
-    margin: 0 !important;
+    overflow-x: hidden !important;
 }
 
-/* Header Styling */
-.app-header {
-    padding: 20px;
-    background: white;
+/* Header strip */
+.bg-header {
+    padding: 14px 4px 12px !important;
     border-bottom: 1px solid #e5e7eb;
+    margin-bottom: 14px;
 }
 
-/* Sidebar Styling */
-.app-sidebar {
-    height: auto !important;
-    max-height: calc(100vh - 100px) !important;
-    overflow-y: auto !important;
-    padding: 20px !important;
-    border-right: 1px solid #e5e7eb;
+/* ==================================================================
+   Top toolbar — single horizontal row with all primary controls.
+   Every primary control has the SAME explicit 56px height. The little
+   filename/info chip beneath sits in a fixed 18px slot. The columns
+   wrap that into a 78px tall toolbar that's identical across cells.
+   ================================================================== */
+.bg-toolbar {
+    margin-bottom: 14px;
+    gap: 10px !important;
+    align-items: flex-start !important;
 }
-
-/* Main Content Area */
-.app-content {
-    height: auto !important;
-    max-height: calc(100vh - 100px) !important;
-    padding: 0 !important;
+.bg-toolbar .gr-form { gap: 0 !important; }
+.bg-toolbar .gr-block { border: none !important; box-shadow: none !important; padding: 0 !important; }
+
+/* Common: any direct primary control fills column width */
+.bg-toolbar > * { width: 100% !important; }
+
+/* ---- Upload buttons ---- */
+.bg-upload-btn,
+.bg-upload-btn > .wrap,
+.bg-upload-btn > div {
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    width: 100% !important;
 }
-
-/* The Magic Scroll Container - Clean and Explicit */
-.scrollable-report-area {
-    /* Fixed height relative to viewport can cause loops in Spaces */
-    max-height: 800px !important; 
-    height: auto !important;
-    min-height: 500px !important;
-    overflow-y: auto !important;
-    padding: 24px;
-    background-color: #f9fafb;
-    border: 1px solid #e5e7eb;
-    border-radius: 8px;
-    margin-top: 10px;
+.bg-upload-btn button {
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    width: 100% !important;
+    padding: 0 14px !important;
+    font-size: 13px !important;
+    font-weight: 500 !important;
+    border-radius: 8px !important;
+    border: 1px dashed #cbd5e1 !important;
+    background: #f8fafc !important;
+    color: #334155 !important;
+    transition: border 0.15s, background 0.15s !important;
+    line-height: 1 !important;
 }
-
-/* Report Card Styling */
-.report-card {
-    background: white;
-    border-radius: 12px;
-    padding: 24px;
-    margin-bottom: 16px; /* Spacing between cards */
-    box-shadow: 0 1px 3px rgba(0,0,0,0.1);
-    border: 1px solid #e5e7eb;
-    transition: transform 0.2s, box-shadow 0.2s;
+.bg-upload-btn button:hover {
+    border-color: #2563eb !important;
+    background: #eff6ff !important;
+    color: #1e3a8a !important;
 }
 
-.report-card:hover {
-    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
-    transform: translateY(-2px);
+/* ---- Run / Stop button (same column, visibility-swapped) ---- */
+.bg-run-btn,
+.bg-run-btn > .wrap,
+.bg-run-btn > div {
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    width: 100% !important;
 }
-
-/* Card Internals */
-.card-header {
-    display: flex;
-    justify-content: space-between;
-    align-items: flex-start;
-    margin-bottom: 16px;
-    padding-bottom: 16px;
-    border-bottom: 1px solid #f3f4f6;
+.bg-run-btn button {
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    width: 100% !important;
+    font-weight: 600 !important;
+    border-radius: 8px !important;
+    font-size: 14px !important;
+    line-height: 1 !important;
+    padding: 0 16px !important;
 }
-
-.card-title {
-    font-size: 1.1em;
-    font-weight: 600;
-    color: #111827;
-    margin: 0 0 4px 0;
+.bg-stop-btn button {
+    background: #dc2626 !important;
+    color: white !important;
+    border: none !important;
 }
-
-.card-subtitle {
-    font-size: 0.9em;
-    color: #6b7280;
-    font-family: monospace;
+.bg-stop-btn button:hover { background: #b91c1c !important; }
+
+/* ---- Preset radio as horizontal pill chips ---- */
+.bg-preset,
+.bg-preset > div,
+.bg-preset > .wrap {
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    padding: 0 !important;
 }
-
-.card-content {
-    font-size: 0.95em;
-    color: #374151;
-    line-height: 1.5;
+.bg-preset > label,
+.bg-preset .label-wrap { display: none !important; }
+.bg-preset .wrap,
+.bg-preset > div > div,
+.bg-preset fieldset {
+    display: flex !important;
+    flex-direction: row !important;
+    gap: 4px !important;
+    flex-wrap: nowrap !important;
+    width: 100% !important;
+    height: 56px !important;
+    align-items: stretch !important;
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
 }
-
-/* Badges */
-.badge {
-    display: inline-flex;
-    align-items: center;
-    padding: 4px 10px;
-    border-radius: 9999px;
-    font-size: 0.8em;
-    font-weight: 500;
+.bg-preset label {
+    flex: 1 1 0 !important;
+    margin: 0 !important;
+    padding: 0 8px !important;
+    height: 56px !important;
+    min-height: 56px !important;
+    max-height: 56px !important;
+    border-radius: 8px !important;
+    font-size: 13px !important;
+    font-weight: 500 !important;
+    border: 1px solid #e5e7eb !important;
+    background: #ffffff !important;
+    cursor: pointer !important;
+    text-align: center !important;
+    display: inline-flex !important;
+    align-items: center !important;
+    justify-content: center !important;
+    line-height: 1 !important;
+    color: #475569 !important;
+    transition: background 0.15s, border 0.15s !important;
+    white-space: nowrap !important;
 }
-
-.badge-success { background-color: #dcfce7; color: #166534; }
-.badge-warning { background-color: #fef9c3; color: #854d0e; }
-.badge-error { background-color: #fee2e2; color: #991b1b; }
-.badge-info { background-color: #dbeafe; color: #1e40af; }
-.badge-neutral { background-color: #f3f4f6; color: #4b5563; }
-
-/* Stats Grid */
-.stats-container {
-    display: grid;
-    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
-    gap: 16px;
-    margin-bottom: 24px;
+.bg-preset label:hover { background: #f8fafc !important; border-color: #cbd5e1 !important; }
+.bg-preset input[type="radio"] { display: none !important; }
+.bg-preset label.selected,
+.bg-preset label:has(input:checked) {
+    background: #1e3a8a !important;
+    color: #ffffff !important;
+    border-color: #1e3a8a !important;
 }
 
-.stat-card {
-    padding: 16px;
-    border-radius: 12px;
-    color: white;
-    text-align: center;
-    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+/* ---- Caption chip beneath each toolbar control ---- */
+.bg-fname {
+    font-size: 11.5px;
+    color: #94a3b8;
+    padding: 4px 8px 0 8px;
+    line-height: 1.3;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    height: 18px;
+    box-sizing: content-box;
 }
-
-.stat-value { font-size: 1.8em; font-weight: 700; }
-.stat-label { font-size: 0.9em; opacity: 0.9; }
-
-/* Detail Grid - Flexbox for better filling */
-.detail-grid {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 12px;
-    margin-bottom: 16px;
-    width: 100%;
+.bg-fname.ok { color: #166534; font-weight: 500; }
+
+/* ==================================================================
+   Advanced settings — gr.Row with each Checkbox as its own card.
+   Trick: `display: contents` on Gradio's intermediate wrapper makes
+   it vanish from the layout tree, so the actual checkbox blocks
+   become direct flex children of .bg-row. Card style is applied to
+   each block, not the wrapper, so we get N cards per row instead of
+   one big box.
+   ================================================================== */
+.bg-row {
+    display: flex !important;
+    flex-direction: row !important;
+    gap: 10px !important;
+    align-items: stretch !important;
+    padding: 4px 0 !important;
 }
 
-.detail-item {
-    background: #f9fafb;
-    padding: 10px 12px;
-    border-radius: 8px;
-    border: 1px solid #f3f4f6;
-    
-    /* Flex sizing: grow, shrink, min-basis */
-    flex: 1 1 160px;
-    min-width: 0; /* Important for word-break to work in flex children */
-    
-    /* Layout control */
-    display: flex;
-    flex-direction: column;
-    
-    /* Height constraint to prevent one huge card from stretching the row */
-    max-height: 100px; 
-    overflow-y: auto;
+/* Flatten Gradio's intermediate `.form` / `.gr-form` wrapper so its
+   children become direct flex items of .bg-row. */
+.bg-row > .form,
+.bg-row > .gr-form {
+    display: contents !important;
+}
+/* Some Gradio versions emit a plain `<div>` wrapper instead of `.form`.
+   We can't safely `display: contents` every direct div (the spacer is
+   one), but if the wrapper has only blocks inside, contents flatten it. */
+.bg-row > div:not(.bg-row-spacer):not(.gr-block):not(.block) {
+    display: contents !important;
 }
 
-/* Custom scrollbar for detail items */
-.detail-item::-webkit-scrollbar {
-    width: 4px;
+/* Each individual checkbox block = a card */
+.bg-row .gr-block,
+.bg-row .block {
+    flex: 1 1 0 !important;
+    min-width: 0 !important;
+    background: #f8fafc !important;
+    border: 1px solid #e5e7eb !important;
+    border-radius: 8px !important;
+    padding: 8px 12px !important;
+    box-shadow: none !important;
+    transition: background 0.15s, border 0.15s !important;
 }
-.detail-item::-webkit-scrollbar-thumb {
-    background-color: #d1d5db;
-    border-radius: 4px;
+.bg-row .gr-block:hover,
+.bg-row .block:hover {
+    background: #eff6ff !important;
+    border-color: #cbd5e1 !important;
 }
-
-.detail-label {
-    font-size: 0.75em;
-    color: #6b7280;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    margin-bottom: 2px;
-    position: sticky;
-    top: 0;
-    background: #f9fafb; /* Maintain bg on scroll */
-    z-index: 1;
+.bg-row label,
+.bg-row .gr-checkbox label {
+    font-size: 13px !important;
+    font-weight: 500 !important;
+    line-height: 1.3 !important;
+    color: #334155 !important;
+    margin: 0 !important;
+    padding: 0 !important;
 }
+.bg-row .gr-info, .bg-row [class*="info"] { display: none !important; }
 
-.detail-value {
-    font-weight: 500;
-    color: #1f2937;
-    font-size: 0.9em;
-    line-height: 1.4;
-    word-break: break-word; /* Fix overflow */
-    overflow-wrap: break-word;
-}    border: 1px solid #e5e7eb;
-    transition: all 0.2s;
+/* Spacer — invisible flex item that just preserves alignment */
+.bg-row .bg-row-spacer {
+    flex: 1 1 0 !important;
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    padding: 0 !important;
+    visibility: hidden !important;
 }
 
-.report-card:hover {
-    box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+/* ==================================================================
+   Status strip — thin one-liner above the report.
+   The Gradio HTML wrapper itself is pinned to its parent column's width
+   so no inner content can change the page geometry during streaming.
+   ================================================================== */
+#bg-status-wrap,
+#bg-status-wrap > * {
+    width: 100% !important;
+    max-width: 100% !important;
+    min-width: 0 !important;
+    box-sizing: border-box !important;
+    overflow-x: hidden !important;
 }
-
-/* Card Header */
-.card-header {
+.bg-status {
+    padding: 10px 14px;
+    border-radius: 10px;
+    background: #f8fafc;
+    border: 1px solid #e2e8f0;
+    font-size: 12.5px;
+    line-height: 1.45;
+    color: #334155;
+    margin: 8px 0 12px 0;
+    max-width: 100%;
+    overflow: hidden;       /* never let inline content widen the page */
+    box-sizing: border-box;
+}
+.bg-status-row {
     display: flex;
-    justify-content: space-between;
-    align-items: flex-start;
-    margin-bottom: 12px;
-    border-bottom: 1px solid #f3f4f6;
-    padding-bottom: 12px;
+    align-items: center;
+    gap: 14px;
+    flex-wrap: nowrap;      /* one row, ellipsize the middle */
+    min-width: 0;
+    width: 100%;
 }
-
-.card-title {
-    font-size: 1.1em;
+.bg-status .bg-status-stage {
     font-weight: 600;
-    color: #1f2937;
-    margin: 0;
-}
-
-.card-subtitle {
-    font-size: 0.9em;
-    color: #6b7280;
-    margin-top: 4px;
-}
-
-/* Status Badges */
-.badge {
+    color: #1e3a8a;
     display: inline-flex;
     align-items: center;
-    padding: 4px 10px;
-    border-radius: 9999px;
-    font-size: 0.8em;
-    font-weight: 500;
+    gap: 8px;
+    flex-shrink: 0;
+    white-space: nowrap;
 }
-
-.badge-success { background-color: #dcfce7; color: #166534; }
-.badge-warning { background-color: #fef9c3; color: #854d0e; }
-.badge-error { background-color: #fee2e2; color: #991b1b; }
-.badge-info { background-color: #dbeafe; color: #1e40af; }
-.badge-neutral { background-color: #f3f4f6; color: #374151; }
-
-/* Content Styling */
-.card-content {
-    font-size: 15px;
-    color: #374151;
-    line-height: 1.6;
+.bg-status .bg-status-detail {
+    color: #475569;
+    flex: 1 1 0;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
 }
-
-.card-content code {
-    background-color: #f3f4f6;
-    padding: 2px 6px;
+.bg-status .bg-status-detail code {
+    background: #eef2ff;
+    padding: 1px 6px;
     border-radius: 4px;
-    font-family: monospace;
-    font-size: 0.9em;
-    color: #c2410c;
+    font-size: 11.5px;
+    color: #1e3a8a;
 }
-
-/* Grid for details */
-.detail-grid {
-    display: grid;
-    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+.bg-status .bg-status-meta {
+    color: #64748b;
+    font-size: 11.5px;
+    display: inline-flex;
+    flex-wrap: nowrap;
     gap: 12px;
-    margin-top: 12px;
+    flex-shrink: 0;
+    white-space: nowrap;
 }
-
-.detail-item {
-    background: #f9fafb;
-    padding: 10px;
-    border-radius: 6px;
+.bg-status.done { background: #f0fdf4; border-color: #bbf7d0; }
+.bg-status.done .bg-status-stage { color: #166534; }
+.bg-status.error { background: #fef2f2; border-color: #fecaca; }
+.bg-status.error .bg-status-stage { color: #b91c1c; }
+.bg-status .spin {
+    display: inline-block;
+    width: 10px; height: 10px;
+    border: 2px solid #cbd5e1;
+    border-top-color: #2563eb;
+    border-radius: 50%;
+    animation: bg-spin 0.9s linear infinite;
 }
+@keyframes bg-spin { to { transform: rotate(360deg); } }
 
-.detail-label {
-    font-size: 0.8em;
-    color: #6b7280;
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
+/* ==================================================================
+   Report area — full-width iframe.
+   ================================================================== */
+.bg-main { padding: 0 !important; }
+.bg-report-iframe {
+    width: 100%;
+    height: 80vh;
+    min-height: 620px;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    background: white;
+    box-shadow: 0 1px 2px rgba(0,0,0,0.04);
 }
 
-.detail-value {
-    font-weight: 500;
-    color: #111827;
+/* Empty / error placeholder (full-width, centered card) */
+.bg-empty {
+    display: flex; align-items: center; justify-content: center;
+    flex-direction: column; gap: 14px;
+    min-height: 60vh;
+    color: #6b7280; text-align: center;
+    border: 2px dashed #e5e7eb; border-radius: 12px;
+    padding: 56px 24px;
+    background: #fafafa;
 }
-
-/* Summary Stats */
-.stats-container {
-    display: grid;
-    grid-template-columns: repeat(3, 1fr);
-    gap: 16px;
-    margin-bottom: 24px;
+.bg-empty .bg-empty-icon { font-size: 56px; line-height: 1; }
+.bg-empty .bg-empty-title { font-size: 17px; font-weight: 600; color: #374151; }
+.bg-empty .bg-empty-hint { font-size: 14px; max-width: 580px; line-height: 1.6; }
+.bg-empty .bg-empty-hint code { background: #f3f4f6; padding: 1px 6px; border-radius: 4px; font-size: 13px; }
+
+/* Compact downloads section */
+.bg-downloads { gap: 6px !important; }
+.bg-downloads .gr-file { min-height: auto !important; }
+.bg-downloads .bg-file-input > label > div {
+    height: 52px !important;
+    min-height: 52px !important;
+    max-height: 52px !important;
 }
 
-.stat-card {
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-    color: white;
-    padding: 20px;
-    border-radius: 12px;
+/* Footer */
+.bg-footer {
     text-align: center;
-    box-shadow: 0 4px 6px rgba(102, 126, 234, 0.25);
+    margin-top: 18px;
+    padding-top: 12px;
+    border-top: 1px solid #f1f5f9;
+    font-size: 11.5px;
+    color: #9ca3af;
 }
-
-.stat-value {
-    font-size: 2em;
-    font-weight: 700;
-}
-
-.stat-label {
-    font-size: 0.9em;
-    opacity: 0.9;
-    margin-top: 4px;
+.bg-footer code { background: #f3f4f6; padding: 1px 5px; border-radius: 3px; font-size: 11px; }
+.bg-footer a { color: #6b7280; text-decoration: none; }
+.bg-footer a:hover { text-decoration: underline; }
+
+/* Trim accordion chrome a bit */
+.gr-accordion { border-radius: 10px !important; border: 1px solid #e5e7eb !important; }
+.gr-accordion > .label-wrap { padding: 8px 12px !important; font-size: 13px !important; }
+
+@media (prefers-color-scheme: dark) {
+    .bg-empty { background: #161b22; border-color: #2a313c; color: #9ca3af; }
+    .bg-empty .bg-empty-title { color: #e6edf3; }
+    .bg-empty .bg-empty-hint code { background: #21262d; }
+    .bg-report-iframe { background: #0d1117; border-color: #2a313c; box-shadow: none; }
+    .bg-status { background: #0f172a; border-color: #1e293b; color: #cbd5e1; }
+    .bg-status .bg-status-stage { color: #93c5fd; }
+    .bg-status .bg-status-detail { color: #94a3b8; }
+    .bg-status .bg-status-detail code { background: #1e293b; color: #93c5fd; }
+    .bg-status .bg-status-meta { color: #64748b; }
+    .bg-status.done { background: #052e1a; border-color: #14532d; }
+    .bg-status.done .bg-status-stage { color: #86efac; }
+    .bg-status.error { background: #2a0e0e; border-color: #7f1d1d; }
+    .bg-preset label { background: #161b22 !important; border-color: #2a313c !important; color: #cbd5e1 !important; }
+    .bg-preset label:hover { background: #1e293b !important; }
+    .bg-preset .selected { background: #2563eb !important; border-color: #2563eb !important; }
+    .bg-footer { border-color: #1e293b; }
 }
+"""
 
-/* Button styling */
-.primary-btn {
-    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
-    border: none !important;
-    font-weight: 600 !important;
-}
 
-/* Tab styling */
-.tab-nav button {
-    font-weight: 500 !important;
-    font-size: 15px !important;
-}
+EMPTY_PANEL_HTML = """
+<div class="bg-empty">
+    <div class="bg-empty-icon">📄</div>
+    <div class="bg-empty-title">Your interactive report appears here</div>
+    <div class="bg-empty-hint">
+        Upload a <code>.bib</code> file and a <code>.tex</code> file in the toolbar above,
+        pick a preset, then press <strong>Run check</strong>. The report renders as a
+        self-contained HTML page with per-section filters, full-text search,
+        inline span highlighting, and dark-mode support.
+    </div>
+</div>
 """
 
+EMPTY_STATUS_HTML = (
+    '<div class="bg-status">'
+    '<div class="bg-status-row">'
+    '<span class="bg-status-stage">○ Idle</span>'
+    '<span class="bg-status-detail">Upload <code>.bib</code> + <code>.tex</code> '
+    'and press <strong>Run check</strong> to begin.</span>'
+    '</div></div>'
+)
+
+
+def _placeholder(message: str, color: str = "#b91c1c") -> str:
+    """Inline error/info card shown in place of the iframe."""
+    return (
+        f'<div class="bg-empty" style="color:{color};border-color:{color}33">'
+        f'<div class="bg-empty-icon">⚠️</div>'
+        f'<div class="bg-empty-title">{message}</div>'
+        f'</div>'
+    )
+
+
+def _html_to_iframe(html: str) -> str:
+    """
+    Embed an HTML document inside ``<iframe srcdoc>``.
+
+    We escape only ``&`` and ``"`` — these are the two characters that can
+    break the attribute value or get re-decoded as entities. ``<`` and ``>``
+    must stay raw, otherwise the inner document would be HTML-encoded.
+    """
+    escaped = html.replace("&", "&amp;").replace('"', "&quot;")
+    return (
+        f'<iframe class="bg-report-iframe" srcdoc="{escaped}" '
+        f'sandbox="allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox" '
+        f'loading="lazy"></iframe>'
+    )
+
+
+def _status_html(stage: str, detail: str = "", meta: list[str] | None = None,
+                 state: str = "running") -> str:
+    """Render the live-status strip shown above the report.
+
+    Layout is a single horizontal row: [stage] [detail] [meta chips].
+    Wraps cleanly on narrow screens.
+    """
+    if state == "running":
+        stage_icon = '<span class="spin"></span>'
+    elif state == "done":
+        stage_icon = '<span>✓</span>'
+    elif state == "error":
+        stage_icon = '<span>⚠</span>'
+    else:
+        stage_icon = '<span>○</span>'
+    detail_html = f'<span class="bg-status-detail">{detail}</span>' if detail else '<span class="bg-status-detail"></span>'
+    meta_html = ""
+    if meta:
+        meta_html = (
+            '<span class="bg-status-meta">'
+            + " ".join(f"<span>{m}</span>" for m in meta)
+            + "</span>"
+        )
+    return (
+        f'<div class="bg-status {state}">'
+        f'<div class="bg-status-row">'
+        f'<span class="bg-status-stage">{stage_icon}<span>{stage}</span></span>'
+        f'{detail_html}{meta_html}'
+        f'</div></div>'
+    )
+
+
+# --------------------------------------------------------------- config glue
 
 def create_config_from_ui(
-    check_metadata: bool,
-    check_usage: bool, 
-    check_duplicates: bool,
-    check_preprint_ratio: bool,
-    caption: bool,
-    reference: bool,
-    formatting: bool,
-    equation: bool,
-    ai_artifacts: bool,
-    sentence: bool,
-    consistency: bool,
-    acronym: bool,
-    number: bool,
-    citation_quality: bool,
-    anonymization: bool
+    check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+    caption, reference, formatting, equation, ai_artifacts,
+    sentence, consistency, acronym, number, citation_quality, anonymization,
 ) -> BibGuardConfig:
-    """Create a BibGuardConfig from UI settings."""
     config = BibGuardConfig()
-    
     config.bibliography = BibliographyConfig(
         check_metadata=check_metadata,
         check_usage=check_usage,
         check_duplicates=check_duplicates,
         check_preprint_ratio=check_preprint_ratio,
-        check_relevance=False  # Disabled for web
+        check_relevance=False,  # LLM disabled in web mode
     )
-    
     config.submission = SubmissionConfig(
-        caption=caption,
-        reference=reference,
-        formatting=formatting,
-        equation=equation,
-        ai_artifacts=ai_artifacts,
-        sentence=sentence,
-        consistency=consistency,
-        acronym=acronym,
-        number=number,
-        citation_quality=citation_quality,
-        anonymization=anonymization
+        caption=caption, reference=reference, formatting=formatting, equation=equation,
+        ai_artifacts=ai_artifacts, sentence=sentence, consistency=consistency,
+        acronym=acronym, number=number, citation_quality=citation_quality,
+        anonymization=anonymization,
     )
-    
     config.output = OutputConfig(quiet=True, minimal_verified=False)
-    
     return config
 
 
-def generate_bibliography_html(report_gen: ReportGenerator, entries: list) -> str:
-    """Generate HTML content for bibliography report."""
-    html = ['<div class="scrollable-report-area">']
-    
-    # 1. Summary Stats
-    total = len(entries)
-    verified = sum(1 for e in report_gen.entries if e.comparison and e.comparison.is_match)
-    used = sum(1 for e in report_gen.entries if e.usage and e.usage.is_used)
-    
-    html.append('<div class="stats-container">')
-    html.append(f'<div class="stat-card"><div class="stat-value">{total}</div><div class="stat-label">Total Entries</div></div>')
-    html.append(f'<div class="stat-card"><div class="stat-value">{verified}</div><div class="stat-label">Verified</div></div>')
-    html.append(f'<div class="stat-card"><div class="stat-value">{used}</div><div class="stat-label">Used in Text</div></div>')
-    html.append('</div>')
-    
-    # 2. Entries
-    for report in report_gen.entries:
-        entry = report.entry
-        status_badges = []
-        
-        # Metadata Status
-        if report.comparison:
-            if report.comparison.is_match:
-                status_badges.append('<span class="badge badge-success">✓ Verified</span>')
-                if report.comparison.source:
-                    status_badges.append(f'<span class="badge badge-info">{report.comparison.source.upper()}</span>')
-            else:
-                status_badges.append('<span class="badge badge-error">⚠ Metadata Mismatch</span>')
-        else:
-             status_badges.append('<span class="badge badge-neutral">No Metadata Check</span>')
-            
-        # Usage Status
-        if report.usage:
-            if report.usage.is_used:
-                status_badges.append(f'<span class="badge badge-success">Used: {report.usage.usage_count}x</span>')
-            else:
-                status_badges.append('<span class="badge badge-warning">Unused</span>')
-        
-        # Build Card
-        html.append(f'''
-        <div class="report-card">
-            <div class="card-header">
-                <div>
-                    <h3 class="card-title">{entry.title or "No Title"}</h3>
-                    <div class="card-subtitle">{entry.key} • {entry.year} • {entry.entry_type}</div>
-                </div>
-                <div style="display: flex; gap: 8px;">
-                    {" ".join(status_badges)}
-                </div>
-            </div>
-            
-            <div class="card-content">
-                <div class="detail-grid">
-                    {
-                        (lambda e: "".join([
-                            f'<div class="detail-item"><div class="detail-label">{k}</div><div class="detail-value">{v}</div></div>'
-                            for k, v in filter(None, [
-                                ("Authors", e.author or "N/A"),
-                                ("Venue", e.journal or e.booktitle or e.publisher or "N/A"),
-                                ("DOI", e.doi) if e.doi else None,
-                                ("ArXiv", e.arxiv_id) if e.arxiv_id and not e.doi else None,
-                                ("Volume/Pages", f"{'Vol.'+e.volume if e.volume else ''} {'pp.'+e.pages if e.pages else ''}".strip()) if e.volume or e.pages else None,
-                                ("URL", f'<a href="{e.url}" target="_blank" style="text-decoration:underline;">Link</a>') if e.url else None
-                            ])
-                        ]))(entry)
-                    }
-                </div>
-        ''')
-        
-        # Add issues if any
-        issues = []
-        if report.comparison and not report.comparison.is_match:
-             # Add main message derived from match status
-             if report.comparison.issues:
-                 for issue in report.comparison.issues:
-                     issues.append(f'<div style="margin-left: 20px; font-size: 0.9em; color: #b91c1c;">• {issue}</div>')
-             else:
-                  issues.append(f'<div style="margin-left: 20px; font-size: 0.9em; color: #b91c1c;">• Verification failed</div>')
-        
-        if issues:
-            html.append('<div style="margin-top: 16px; padding-top: 12px; border-top: 1px solid #eee;">')
-            html.append("".join(issues))
-            html.append('</div>')
-            
-        html.append('</div></div>') # Close card-content and report-card
-        
-    html.append('</div>') # Close container
-    return "".join(html)
-
-def generate_latex_html(results: list) -> str:
-    """Generate HTML for LaTeX quality check."""
-    from src.checkers import CheckSeverity
-
-    html = ['<div class="scrollable-report-area">']
-    
-    # Stats
-    errors = sum(1 for r in results if r.severity == CheckSeverity.ERROR)
-    warnings = sum(1 for r in results if r.severity == CheckSeverity.WARNING)
-    infos = sum(1 for r in results if r.severity == CheckSeverity.INFO)
-    
-    html.append('<div class="stats-container">')
-    html.append(f'<div class="stat-card" style="background: linear-gradient(135deg, #ef4444 0%, #b91c1c 100%);"><div class="stat-value">{errors}</div><div class="stat-label">Errors</div></div>')
-    html.append(f'<div class="stat-card" style="background: linear-gradient(135deg, #f59e0b 0%, #d97706 100%);"><div class="stat-value">{warnings}</div><div class="stat-label">Warnings</div></div>')
-    html.append(f'<div class="stat-card" style="background: linear-gradient(135deg, #3b82f6 0%, #1d4ed8 100%);"><div class="stat-value">{infos}</div><div class="stat-label">Suggestions</div></div>')
-    html.append('</div>')
-    
-    if not results:
-        html.append('<div class="report-card"><div class="card-content" style="text-align: center; padding: 40px; color: #166534; font-size: 1.2em;">✅ No issues found in LaTeX code!</div></div>')
-    else:
-        # Group by Checker
-        results.sort(key=lambda x: x.checker_name)
-        current_checker = None
-        
-        for result in results:
-            badge_class = "badge-neutral"
-            if result.severity == CheckSeverity.ERROR: badge_class = "badge-error"
-            elif result.severity == CheckSeverity.WARNING: badge_class = "badge-warning"
-            elif result.severity == CheckSeverity.INFO: badge_class = "badge-info"
-            
-            html.append(f'''
-            <div class="report-card">
-                <div class="card-header">
-                    <div>
-                        <h3 class="card-title">{result.checker_name}</h3>
-                        <div class="card-subtitle">Line {result.line_number}</div>
-                    </div>
-                     <span class="badge {badge_class}">{result.severity.name}</span>
-                </div>
-                <div class="card-content">
-                    {result.message}
-                    {f'<div style="margin-top: 8px; background: #f3f4f6; padding: 8px; border-radius: 4px; font-family: monospace;">{result.line_content}</div>' if result.line_content else ''}
-                    {f'<div style="margin-top: 8px; color: #166534;">💡 Suggestion: {result.suggestion}</div>' if result.suggestion else ''}
-                </div>
-            </div>
-            ''')
-            
-    html.append('</div>')
-    return "".join(html)
-
-def generate_line_html(content: str, results: list) -> str:
-    """Generate HTML for Line-by-Line report."""
-    # Build a dictionary of line_number -> list of issues
-    issues_by_line = {}
-    for r in results:
-        if r.line_number not in issues_by_line:
-            issues_by_line[r.line_number] = []
-        issues_by_line[r.line_number].append(r)
-        
-    lines = content.split('\n')
-    
-    html = ['<div class="scrollable-report-area">']
-    
-    html.append('<div class="report-card"><div class="card-content">Issues are mapped to specific lines below.</div></div>')
-    
-    for i, line in enumerate(lines, 1):
-        if i in issues_by_line:
-            # Highlight this line
-            line_issues = issues_by_line[i]
-            
-            html.append(f'''
-            <div class="report-card" style="border-left: 4px solid #ef4444; padding: 12px;">
-                <div style="font-family: monospace; color: #6b7280; font-size: 0.9em; margin-bottom: 4px;">Line {i}</div>
-                <div style="font-family: monospace; background: #fee2e2; padding: 4px; border-radius: 4px; overflow-x: auto; white-space: pre;">{line}</div>
-                <div style="margin-top: 8px;">
-            ''')
-            
-            for issue in line_issues:
-                html.append(f'<div style="color: #991b1b; font-size: 0.95em; margin-top: 4px;">• {issue.message}</div>')
-                
-            html.append('</div></div>')
-            
-    html.append('</div>')
-    return "".join(html)
+def apply_preset(name: str):
+    p = PRESETS.get(name, PRESETS["Standard"])
+    sub = p["submission"]
+    return (
+        p["check_metadata"], p["check_usage"], p["check_duplicates"], p["check_preprint_ratio"],
+        sub["caption"], sub["reference"], sub["formatting"], sub["equation"],
+        sub["ai_artifacts"], sub["sentence"], sub["consistency"], sub["acronym"],
+        sub["number"], sub["citation_quality"], sub["anonymization"],
+        p["url_liveness"], p["retraction"],
+    )
 
 
+_PRESET_CAPTIONS = {
+    "Quick":    "local checks only · no network · instant",
+    "Standard": "local checks + retraction lookup (CrossRef)",
+    "Strict":   "+ URL liveness + multi-source metadata (slow)",
+}
+
+
+def _preset_caption_html(name: str) -> str:
+    text = _PRESET_CAPTIONS.get(name, "")
+    return f'<div class="bg-fname" style="text-align:center">{text}</div>'
 
 
+# ------------------------------------------------------------------ run_check
+# Streaming generator. Each yield is a 7-tuple:
+#   (iframe_html, status_html, html_path, md_path, json_path,
+#    cleaned_bib_path, log_path)
+# `capture_run` attaches a per-run DEBUG file handler so any exception or
+# warning anywhere in the pipeline is recorded with full traceback at
+# `<out_dir>/bibguard.log`, which is then downloadable. The status panel
+# surfaces warning+error counts so problems aren't invisible.
+
 def run_check(
-    bib_file,
-    tex_file,
-    check_metadata: bool,
-    check_usage: bool,
-    check_duplicates: bool,
-    check_preprint_ratio: bool,
-    caption: bool,
-    reference: bool,
-    formatting: bool,
-    equation: bool,
-    ai_artifacts: bool,
-    sentence: bool,
-    consistency: bool,
-    acronym: bool,
-    number: bool,
-    citation_quality: bool,
-    anonymization: bool,
-    progress=gr.Progress()
-) -> Tuple[str, str, str]:
-    """Run BibGuard checks and return three reports."""
-    
-    if bib_file is None or tex_file is None:
-        return (
-            "⚠️ Please upload both `.bib` and `.tex` files.",
-            "⚠️ Please upload both `.bib` and `.tex` files.",
-            "⚠️ Please upload both `.bib` and `.tex` files."
+    bib_file, tex_file,
+    check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+    caption, reference, formatting, equation, ai_artifacts,
+    sentence, consistency, acronym, number, citation_quality, anonymization,
+    url_liveness=False, retraction=True,
+):
+    """Run the full check pipeline as a streaming generator with per-run logging.
+
+    `bib_file` / `tex_file` are filesystem path strings (carried by gr.State),
+    not gr.File objects. The status panel is the single source of progress
+    feedback — no separate gr.Progress bar.
+    """
+    started = time.time()
+
+    def _elapsed() -> str:
+        return f"⏱ {int(time.time() - started)}s"
+
+    # Initial state: keep current report (None means clear).
+    if not bib_file or not tex_file:
+        yield (
+            _placeholder("Please choose both a .bib and a .tex file in the toolbar."),
+            _status_html("Waiting for files",
+                         "Pick a .bib and a .tex file from the toolbar to start.",
+                         state="error"),
+            None, None, None, None, None,
         )
-    
-    try:
-        # Create config from UI
-        config = create_config_from_ui(
-            check_metadata, check_usage, check_duplicates, check_preprint_ratio,
-            caption, reference, formatting, equation, ai_artifacts,
-            sentence, consistency, acronym, number, citation_quality, anonymization
+        return
+
+    # Allocate the artifact dir up-front so the per-run log lives next to
+    # the report files.
+    out_dir = Path(tempfile.mkdtemp(prefix="bibguard_"))
+    log_path_target = out_dir / "bibguard.log"
+
+    # Reset per-source circuit breakers so a previous run's flaky source
+    # doesn't carry over and skip valid lookups in this run.
+    http_layer.reset_breakers()
+
+    with capture_run(target_path=log_path_target) as (log_path, log_stats):
+        logger.info("=== run_check start: bib=%s tex=%s ===", bib_file, tex_file)
+        try:
+            yield from _run_check_impl(
+                bib_file, tex_file, out_dir, log_path, log_stats,
+                check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+                caption, reference, formatting, equation, ai_artifacts,
+                sentence, consistency, acronym, number, citation_quality, anonymization,
+                url_liveness, retraction, started, _elapsed,
+            )
+        except Exception as e:
+            logger.exception("run_check crashed (entry-level guard)")
+            yield (
+                _placeholder(f"Unhandled error: {e}"),
+                _status_html("Failed", f"{e} — see <code>bibguard.log</code> for the full traceback.",
+                             state="error"),
+                None, None, None, None, str(log_path),
+            )
+        finally:
+            logger.info("=== run_check end: warnings=%d errors=%d ===",
+                        log_stats.warnings, log_stats.errors)
+
+
+def _run_check_impl(
+    bib_file, tex_file, out_dir, log_path, log_stats,
+    check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+    caption, reference, formatting, equation, ai_artifacts,
+    sentence, consistency, acronym, number, citation_quality, anonymization,
+    url_liveness, retraction, started, _elapsed,
+):
+    """Inner pipeline. Wrapped in `capture_run` by `run_check`.
+
+    Every yield is a 7-tuple ending with the log path so the user can
+    download `bibguard.log` even from intermediate updates.
+    """
+    log_path_str = str(log_path)
+
+    bib_path = Path(bib_file)
+    tex_path = Path(tex_file)
+    logger.info("Inputs: bib=%s tex=%s out_dir=%s", bib_path, tex_path, out_dir)
+
+    def _meta_with_logs(extra: list[str]) -> list[str]:
+        out = list(extra)
+        if log_stats.warnings or log_stats.errors:
+            out.append(f"⚠ {log_stats.warnings}w / {log_stats.errors}e logged")
+        return out
+
+    yield (
+        gr.update(),
+        _status_html("Validating files",
+                     f"Reading <code>{bib_path.name}</code> and <code>{tex_path.name}</code>",
+                     meta=_meta_with_logs([_elapsed()])),
+        None, None, None, None, log_path_str,
+    )
+
+    # Pre-flight content validation
+    bib_rep = validate_bib(bib_path)
+    tex_rep = validate_tex(tex_path)
+    msg = "\n".join(filter(None, [
+        format_report(bib_rep, bib_path.name),
+        format_report(tex_rep, tex_path.name),
+    ]))
+    if not bib_rep.ok or not tex_rep.ok:
+        logger.error("File validation failed:\n%s", msg)
+        block = (
+            f'<div class="bg-empty" style="color:#b91c1c;border-color:#b91c1c33">'
+            f'<div class="bg-empty-icon">⚠️</div>'
+            f'<div class="bg-empty-title">File validation failed</div>'
+            f'<pre style="white-space:pre-wrap;font-size:13px;color:#7f1d1d;'
+            f'background:#fef2f2;padding:12px;border-radius:6px;max-width:540px">{msg}</pre>'
+            f'</div>'
         )
-        
-        # Get file paths from uploaded files
-        bib_path = bib_file.name
-        tex_path = tex_file.name
-        
-        # Read tex content for checkers
-        tex_content = Path(tex_path).read_text(encoding='utf-8', errors='replace')
-        
-        # Parse files
-        bib_parser = BibParser()
-        entries = bib_parser.parse_file(bib_path)
-        
-        tex_parser = TexParser()
-        tex_parser.parse_file(tex_path)
-        
-        bib_config = config.bibliography
-        
-        # Initialize components
-        arxiv_fetcher = None
-        crossref_fetcher = None
-        semantic_scholar_fetcher = None
-        openalex_fetcher = None
-        dblp_fetcher = None
-        comparator = None
-        usage_checker = None
-        duplicate_detector = None
-        
-        if bib_config.check_metadata:
-            arxiv_fetcher = ArxivFetcher()
-            semantic_scholar_fetcher = SemanticScholarFetcher()
-            openalex_fetcher = OpenAlexFetcher()
-            dblp_fetcher = DBLPFetcher()
-            crossref_fetcher = CrossRefFetcher()
-            comparator = MetadataComparator()
-        
-        if bib_config.check_usage:
-            usage_checker = UsageChecker(tex_parser)
-        
-        if bib_config.check_duplicates:
-            duplicate_detector = DuplicateDetector()
-        
-        # Initialize report generator
-        report_gen = ReportGenerator(
-            minimal_verified=False,
-            check_preprint_ratio=bib_config.check_preprint_ratio,
-            preprint_warning_threshold=bib_config.preprint_warning_threshold
+        yield (
+            block,
+            _status_html("File validation failed", msg.replace("\n", "<br>"),
+                         state="error"),
+            None, None, None, None, log_path_str,
         )
-        report_gen.set_metadata([bib_file.name], [tex_file.name])
-        
-        # Run submission quality checks
-        progress(0.2, desc="Running LaTeX quality checks...")
-        submission_results = []
-        enabled_checkers = config.submission.get_enabled_checkers()
-        
-        for checker_name in enabled_checkers:
-            if checker_name in CHECKER_REGISTRY:
-                checker = CHECKER_REGISTRY[checker_name]()
+        return
+    elif msg:
+        logger.info("Validation warnings:\n%s", msg)
+
+    config = create_config_from_ui(
+        check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+        caption, reference, formatting, equation, ai_artifacts,
+        sentence, consistency, acronym, number, citation_quality, anonymization,
+    )
+
+    yield (
+        gr.update(),
+        _status_html("Parsing", "Loading bibliography and LaTeX source",
+                     meta=_meta_with_logs([_elapsed()])),
+        None, None, None, None, log_path_str,
+    )
+
+    tex_content = tex_path.read_text(encoding='utf-8', errors='replace')
+    bib_parser = BibParser()
+    entries = bib_parser.parse_file(str(bib_path))
+    tex_parser = TexParser()
+    tex_parser.parse_file(str(tex_path))
+    logger.info("Parsed %d bib entries from %s", len(entries), bib_path.name)
+
+    bib_config = config.bibliography
+
+    # Init components
+    arxiv_fetcher = crossref_fetcher = ss_fetcher = oa_fetcher = dblp_fetcher = None
+    comparator = usage_checker = duplicate_detector = None
+
+    if bib_config.check_metadata:
+        arxiv_fetcher = ArxivFetcher()
+        ss_fetcher = SemanticScholarFetcher()
+        oa_fetcher = OpenAlexFetcher()
+        dblp_fetcher = DBLPFetcher()
+        crossref_fetcher = CrossRefFetcher()
+        comparator = MetadataComparator()
+    if bib_config.check_usage:
+        usage_checker = UsageChecker(tex_parser)
+    if bib_config.check_duplicates:
+        duplicate_detector = DuplicateDetector()
+
+    report_gen = ReportGenerator(
+        minimal_verified=False,
+        check_preprint_ratio=bib_config.check_preprint_ratio,
+        preprint_warning_threshold=bib_config.preprint_warning_threshold,
+    )
+    report_gen.set_metadata([str(bib_path)], [str(tex_path)])
+
+    # Submission quality checks
+    yield (
+        gr.update(),
+        _status_html("LaTeX quality checks",
+                     f"Running {len(config.submission.get_enabled_checkers())} checkers on the LaTeX source",
+                     meta=_meta_with_logs([f"📚 {len(entries)} bib entries", _elapsed()])),
+        None, None, None, None, log_path_str,
+    )
+    submission_results = []
+    for name in config.submission.get_enabled_checkers():
+        if name in CHECKER_REGISTRY:
+            try:
+                checker = CHECKER_REGISTRY[name]()
                 results = checker.check(tex_content, {})
                 for r in results:
-                    r.file_path = tex_file.name
+                    r.file_path = str(tex_path)
                 submission_results.extend(results)
-        
-        report_gen.set_submission_results(submission_results, None)
-        
-        # Check for duplicates
-        if bib_config.check_duplicates and duplicate_detector:
-            duplicate_groups = duplicate_detector.find_duplicates(entries)
-            report_gen.set_duplicate_groups(duplicate_groups)
-        
-        # Check missing citations
-        if bib_config.check_usage and usage_checker:
-            missing = usage_checker.get_missing_entries(entries)
-            report_gen.set_missing_citations(missing)
-        
-        # Build workflow
-        workflow_config = get_default_workflow()
-        
-        # Process entries
-        progress(0.3, desc="Processing bibliography entries...")
-        total_entries = len(entries)
-        
-        for i, entry in enumerate(entries):
-            progress(0.3 + 0.5 * (i / total_entries), desc=f"Checking: {entry.key}")
-            
-            # Check usage
-            usage_result = None
+            except Exception:
+                logger.exception("Checker %s crashed", name)
+    report_gen.set_submission_results(submission_results, None)
+
+    if bib_config.check_duplicates and duplicate_detector:
+        try:
+            report_gen.set_duplicate_groups(duplicate_detector.find_duplicates(entries))
+        except Exception:
+            logger.exception("Duplicate detection crashed")
+    if bib_config.check_usage and usage_checker:
+        try:
+            report_gen.set_missing_citations(usage_checker.get_missing_entries(entries))
+        except Exception:
+            logger.exception("Missing-citation lookup crashed")
+
+    # Per-entry workflow
+    total = max(1, len(entries))
+    workflow_config = get_default_workflow()
+    verified_count = 0
+    flagged_count = 0
+    not_found_count = 0
+    last_yield = time.time()
+
+    def _identifier_chip(entry) -> str:
+        """Tiny inline hint about which IDs we have for this entry."""
+        bits = []
+        if entry.doi: bits.append("DOI")
+        if entry.has_arxiv: bits.append("arXiv")
+        if entry.title and not bits: bits.append("title")
+        elif entry.title: bits.append("title")
+        return " + ".join(bits) if bits else "no identifiers"
+
+    def _outcome_label(cmp) -> str:
+        if cmp is None:
+            return ""
+        if cmp.source == "unable":
+            return "<span style='color:#b45309'>? no metadata</span>"
+        if cmp.is_match:
+            return f"<span style='color:#166534'>✓ verified by {cmp.source}</span>"
+        return f"<span style='color:#b45309'>⚠ flagged ({cmp.source})</span>"
+
+    for i, entry in enumerate(entries):
+        # ── Pre-fetch status: announce identifier set BEFORE the network roundtrip
+        # so the user sees what's being attempted, not just the entry name.
+        if bib_config.check_metadata and comparator:
+            now = time.time()
+            if now - last_yield > 0.4 or i == 0:
+                ids = _identifier_chip(entry)
+                detail = f"<code>{entry.key}</code> · querying via <strong>{ids}</strong>"
+                if entry.title:
+                    short = entry.title[:70] + ("…" if len(entry.title) > 70 else "")
+                    detail += f" — <span style='color:#64748b'>{short}</span>"
+                yield (
+                    gr.update(),
+                    _status_html(
+                        f"Verifying entry {i + 1}/{total}",
+                        detail,
+                        meta=_meta_with_logs([
+                            f"📚 {total} total",
+                            f"✓ {verified_count}",
+                            f"⚠ {flagged_count}",
+                            f"? {not_found_count}",
+                            _elapsed(),
+                        ]),
+                    ),
+                    None, None, None, None, log_path_str,
+                )
+                last_yield = now
+
+        usage_result = None
+        comparison_result = None
+        try:
             if usage_checker:
                 usage_result = usage_checker.check_usage(entry)
-            
-            # Fetch and compare metadata
-            comparison_result = None
+        except Exception:
+            logger.exception("Usage check crashed for entry=%s", entry.key)
+        try:
             if bib_config.check_metadata and comparator:
                 comparison_result = fetch_and_compare_with_workflow(
                     entry, workflow_config, arxiv_fetcher, crossref_fetcher,
-                    semantic_scholar_fetcher, openalex_fetcher, dblp_fetcher, comparator
+                    ss_fetcher, oa_fetcher, dblp_fetcher, comparator,
                 )
-            
-            # Create entry report
-            entry_report = EntryReport(
-                entry=entry,
-                comparison=comparison_result,
-                usage=usage_result,
-                evaluations=[]
+                if comparison_result is None or comparison_result.source == "unable":
+                    not_found_count += 1
+                elif comparison_result.is_match:
+                    verified_count += 1
+                else:
+                    flagged_count += 1
+        except Exception:
+            logger.exception("Metadata fetch crashed for entry=%s", entry.key)
+        report_gen.add_entry_report(EntryReport(
+            entry=entry, comparison=comparison_result,
+            usage=usage_result, evaluations=[],
+        ))
+
+        # ── Post-fetch status: show outcome inline so the user can watch
+        # results stream in (verified / flagged / not found).
+        now = time.time()
+        if now - last_yield > 0.4 or i == total - 1:
+            outcome = _outcome_label(comparison_result)
+            detail_parts = [f"<code>{entry.key}</code>"]
+            if outcome:
+                detail_parts.append(outcome)
+            if entry.title:
+                short = entry.title[:70] + ("…" if len(entry.title) > 70 else "")
+                detail_parts.append(f"<span style='color:#64748b'>{short}</span>")
+            detail = " · ".join(detail_parts)
+            meta = _meta_with_logs([
+                f"📚 {i + 1}/{total}",
+                f"✓ {verified_count}",
+                f"⚠ {flagged_count}",
+                f"? {not_found_count}",
+                _elapsed(),
+            ])
+            yield (
+                gr.update(),
+                _status_html(f"Bibliography {i + 1}/{total}", detail, meta=meta),
+                None, None, None, None, log_path_str,
             )
-            report_gen.add_entry_report(entry_report)
-        
-        progress(0.85, desc="Generating structured reports...")
-        
-        # Generate Bibliography HTML Report
-        bib_report = generate_bibliography_html(report_gen, entries)
-        
-        # Generate LaTeX Quality HTML Report
-        latex_report = generate_latex_html(submission_results)
-        
-        # Generate Line-by-Line HTML Report
-        line_report = ""
-        if submission_results:
-            line_report = generate_line_html(tex_content, submission_results)
-        else:
-             line_report = '<div class="report-container"><div class="report-card"><div class="card-content">No issues to display line-by-line.</div></div></div>'
-        
-        progress(1.0, desc="Done!")
-        
-        return bib_report, latex_report, line_report
-        
-    except Exception as e:
-        error_msg = f"❌ Error: {str(e)}"
-        import traceback
-        error_msg += f"\n\n```\n{traceback.format_exc()}\n```"
-        return error_msg, error_msg, error_msg
+            last_yield = now
+
+    if retraction:
+        try:
+            doi_count = sum(1 for e in entries if getattr(e, "doi", ""))
+            yield (
+                gr.update(),
+                _status_html("Retraction lookups",
+                             f"Querying CrossRef for {doi_count} DOI(s)",
+                             meta=_meta_with_logs([_elapsed()])),
+                None, None, None, None, log_path_str,
+            )
+            report_gen.set_retraction_findings(RetractionChecker().check_entries(entries))
+        except Exception:
+            logger.exception("Retraction lookup crashed")
+
+    if url_liveness:
+        try:
+            url_count = sum(1 for e in entries if getattr(e, "url", ""))
+            yield (
+                gr.update(),
+                _status_html("URL liveness",
+                             f"HEAD-checking {url_count} URL(s) in parallel",
+                             meta=_meta_with_logs([_elapsed()])),
+                None, None, None, None, log_path_str,
+            )
+            report_gen.set_url_findings(URLChecker().check_entries(entries))
+        except Exception:
+            logger.exception("URL liveness crashed")
+
+    # Save artifacts
+    yield (
+        gr.update(),
+        _status_html("Building report",
+                     "Rendering self-contained HTML, JSON, and Markdown",
+                     meta=_meta_with_logs([_elapsed()])),
+        None, None, None, None, log_path_str,
+    )
+    html_path = out_dir / "report.html"
+    md_path = out_dir / "bibliography_report.md"
+    json_path = out_dir / "report.json"
+    cleaned_bib_path: Path | None = None
 
+    try:
+        report_gen.save_html(str(html_path))
+        report_gen.save_bibliography_report(str(md_path))
+        report_gen.save_json(str(json_path))
+        if usage_checker:
+            used_keys = {er.entry.key for er in report_gen.entries if er.usage and er.usage.is_used}
+            if used_keys:
+                cleaned_bib_path = out_dir / f"{bib_path.stem}_only_used.bib"
+                bib_parser.filter_file(str(bib_path), str(cleaned_bib_path), used_keys)
+    except Exception:
+        logger.exception("Artifact generation failed")
 
+    # Embed report.html as iframe srcdoc
+    if html_path.exists():
+        iframe_html = _html_to_iframe(html_path.read_text(encoding='utf-8'))
+    else:
+        iframe_html = _placeholder("Report generation failed — see bibguard.log.")
+
+    meta = _meta_with_logs([
+        f"📚 {len(entries)} entries",
+        f"✓ {verified_count} verified",
+        f"⚠ {flagged_count} flagged",
+        _elapsed(),
+    ])
+    state = "done"
+    summary = "Report ready. Use the right pane to filter, search, and copy fixes."
+    if log_stats.errors > 0:
+        state = "error"
+        summary = (f"Done with {log_stats.errors} error(s) and {log_stats.warnings} warning(s) "
+                   "logged — see <code>bibguard.log</code> for full tracebacks.")
+    elif log_stats.warnings > 0:
+        summary = (f"Report ready ({log_stats.warnings} warnings logged — see "
+                   "<code>bibguard.log</code>).")
+
+    yield (
+        iframe_html,
+        _status_html("Done", summary, meta=meta, state=state),
+        str(html_path) if html_path.exists() else None,
+        str(md_path) if md_path.exists() else None,
+        str(json_path) if json_path.exists() else None,
+        str(cleaned_bib_path) if (cleaned_bib_path and cleaned_bib_path.exists()) else None,
+        log_path_str,
+    )
+
+
+# --------------------------------------------------------------------- layout
 
-def create_app():
-    """Create and configure the Gradio app."""
-    
-    # Load icon as base64
-    icon_html = ""
+def create_app() -> gr.Blocks:
+    # Inline app icon as a base64 data URL — works regardless of cwd.
+    icon_html = '<span style="font-size:28px">🛡️</span>'
     try:
-        icon_path = Path("assets/icon-192.png")
+        icon_path = Path(__file__).parent / "assets" / "icon-192.png"
         if icon_path.exists():
             with open(icon_path, "rb") as f:
-                encoding = base64.b64encode(f.read()).decode()
-            icon_html = f'<img src="data:image/png;base64,{encoding}" style="width: 48px; height: 48px; border-radius: 8px;" alt="BibGuard">'
-        else:
-            icon_html = '<span style="font-size: 48px;">📚</span>'
-    except Exception:
-        icon_html = '<span style="font-size: 48px;">📚</span>'
-
-    with gr.Blocks(title="BibGuard - Bibliography & LaTeX Quality Checker") as app:
-        
-        # Header with icon
-        with gr.Row(elem_classes=["app-header"]):
-            gr.HTML(f"""
-            <div style="display: flex; align-items: center; gap: 12px; margin-bottom: 16px;">
-                {icon_html}
-                <div>
-                    <h1 style="margin: 0; font-size: 1.8em;">BibGuard</h1>
-                    <p style="margin: 0; color: #666; font-size: 14px;">Bibliography & LaTeX Quality Checker</p>
-                </div>
-            </div>
-            """)
-        
-        with gr.Row(elem_classes=["app-body"]):
-            # Left column: Upload & Settings
-            with gr.Column(scale=1, min_width=280, elem_classes=["app-sidebar"]):
-                gr.Markdown("### 📁 Upload Files")
-                
-                bib_file = gr.File(
-                    label="Bibliography (.bib)",
-                    file_types=[".bib"],
-                    file_count="single"
+                b64 = base64.b64encode(f.read()).decode()
+            icon_html = (
+                f'<img src="data:image/png;base64,{b64}" '
+                f'style="width:32px;height:32px;border-radius:6px" alt="BibGuard">'
+            )
+    except Exception as e:
+        logger.debug("Icon load failed; using emoji fallback: %s", e, exc_info=True)
+
+    with gr.Blocks(
+        title="BibGuard — Bibliography & LaTeX Quality Auditor",
+    ) as app:
+
+        gr.HTML(f"""
+        <div class="bg-header" style="display:flex;align-items:center;gap:10px">
+            {icon_html}
+            <strong style="font-size:18px">BibGuard</strong>
+            <span style="color:#6b7280;font-size:13px">— Bibliography & LaTeX quality auditor</span>
+            <span style="flex:1"></span>
+            <a href="https://github.com/thinkwee/BibGuard" target="_blank"
+               style="color:#6b7280;text-decoration:none;font-size:13px">GitHub ↗</a>
+        </div>
+        """)
+
+        # ───────────────────────── Top toolbar ─────────────────────────
+        # All primary controls on a single horizontal row, every primary
+        # widget pinned to 56px height. gr.UploadButton replaces gr.File
+        # because the latter's drop-zone doesn't shrink to a toolbar.
+        with gr.Row(elem_classes=["bg-toolbar"]):
+            with gr.Column(scale=2, min_width=200):
+                bib_btn = gr.UploadButton(
+                    "📚 Choose .bib file",
+                    file_types=[".bib"], file_count="single",
+                    elem_classes=["bg-upload-btn"],
+                )
+                bib_status = gr.HTML('<div class="bg-fname">no file selected</div>')
+            with gr.Column(scale=2, min_width=200):
+                tex_btn = gr.UploadButton(
+                    "📄 Choose .tex file",
+                    file_types=[".tex"], file_count="single",
+                    elem_classes=["bg-upload-btn"],
                 )
-                
-                tex_file = gr.File(
-                    label="LaTeX Source (.tex)", 
-                    file_types=[".tex"],
-                    file_count="single"
+                tex_status = gr.HTML('<div class="bg-fname">no file selected</div>')
+            with gr.Column(scale=3, min_width=280):
+                preset = gr.Radio(
+                    choices=list(PRESETS.keys()),
+                    value="Standard",
+                    show_label=False,
+                    elem_classes=["bg-preset"],
                 )
-                
-                # Check options in grid layout
-                gr.Markdown("#### ⚙️ Options")
-                
-                with gr.Row():
-                    check_metadata = gr.Checkbox(label="🔍 Metadata", value=False)
-                    check_usage = gr.Checkbox(label="📊 Usage", value=True)
-                
-                with gr.Row():
-                    check_duplicates = gr.Checkbox(label="👯 Duplicates", value=True)
-                    check_preprint_ratio = gr.Checkbox(label="📄 Preprints", value=True)
-                
-                with gr.Row():
-                    caption = gr.Checkbox(label="🖼️ Captions", value=True)
-                    reference = gr.Checkbox(label="🔗 References", value=True)
-                
-                with gr.Row():
-                    formatting = gr.Checkbox(label="✨ Formatting", value=True)
-                    equation = gr.Checkbox(label="🔢 Equations", value=True)
-                
-                with gr.Row():
-                    ai_artifacts = gr.Checkbox(label="🤖 AI Artifacts", value=True)
-                    sentence = gr.Checkbox(label="📝 Sentences", value=True)
-                
-                with gr.Row():
-                    consistency = gr.Checkbox(label="🔄 Consistency", value=True)
-                    acronym = gr.Checkbox(label="🔤 Acronyms", value=True)
-                
-                with gr.Row():
-                    number = gr.Checkbox(label="🔢 Numbers", value=True)
-                    citation_quality = gr.Checkbox(label="📚 Citations", value=True)
-                
-                with gr.Row():
-                    anonymization = gr.Checkbox(label="🎭 Anonymization", value=True)
-                
-                run_btn = gr.Button("🔍 Check Now", variant="primary", size="lg")
-                
-                gr.HTML("""
-                <div style="text-align: center; margin-top: 16px;">
-                <a href="https://github.com/thinkwee/BibGuard" target="_blank" style="text-decoration: none; color: #666; display: inline-flex; align-items: center; gap: 6px;">
-                <svg height="20" width="20" viewBox="0 0 16 16"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>
-                GitHub
-                </a>
-                <p style="margin: 8px 0 0 0; color: #999; font-size: 12px;">Developed with ❤️ for researchers</p>
-                </div>
-                """)
-            
-            # Right column: Reports
-            with gr.Column(scale=4, elem_classes=["app-content"]):
-                with gr.Tabs():
-                    with gr.Tab("📚 Bibliography Report"):
-                        bib_report = gr.HTML(
-                            value=WELCOME_HTML,
-                            elem_classes=["report-panel"]
-                        )
-                    
-                    with gr.Tab("📝 LaTeX Quality"):
-                        latex_report = gr.HTML(
-                            value=WELCOME_HTML,
-                            elem_classes=["report-panel"]
-                        )
-                    
-                    with gr.Tab("📋 Line-by-Line"):
-                        line_report = gr.HTML(
-                            value=WELCOME_HTML,
-                            elem_classes=["report-panel"]
-                        )
-        
-        # Event handling
-        run_btn.click(
+                preset_caption = gr.HTML(
+                    _preset_caption_html("Standard"),
+                )
+            with gr.Column(scale=1, min_width=140):
+                run_btn = gr.Button("▶  Run check", variant="primary",
+                                    elem_classes=["bg-run-btn"])
+                stop_btn = gr.Button("◼  Stop", variant="stop",
+                                     elem_classes=["bg-run-btn", "bg-stop-btn"],
+                                     visible=False)
+                gr.HTML('<div class="bg-fname" style="text-align:center">&nbsp;</div>')
+
+        # Holds the selected file paths (strings). Updated by the UploadButton
+        # callbacks below so run_check sees plain paths regardless of how the
+        # user picked the files.
+        bib_path_state = gr.State(value=None)
+        tex_path_state = gr.State(value=None)
+
+        # Advanced fine-grained toggles. Default closed — most users just
+        # pick a preset and go. Each tab is composed of gr.Row blocks of
+        # exactly 4 cells so columns line up vertically. Short rows are
+        # padded with invisible spacer HTML.
+        def _spacer():
+            return gr.HTML('<div class="bg-row-spacer">&nbsp;</div>',
+                           elem_classes=["bg-row-spacer"])
+
+        with gr.Accordion("⚙️  Advanced settings", open=False):
+            with gr.Tabs():
+                with gr.TabItem("Bibliography"):
+                    with gr.Row(elem_classes=["bg-row"]):
+                        check_metadata = gr.Checkbox(label="Metadata verify", value=False)
+                        check_usage = gr.Checkbox(label="Usage", value=True)
+                        check_duplicates = gr.Checkbox(label="Duplicates", value=True)
+                        check_preprint_ratio = gr.Checkbox(label="Preprints", value=True)
+                    with gr.Row(elem_classes=["bg-row"]):
+                        retraction = gr.Checkbox(label="Retractions", value=True)
+                        url_liveness = gr.Checkbox(label="URL liveness", value=False)
+                        _spacer()
+                        _spacer()
+
+                with gr.TabItem("LaTeX format"):
+                    with gr.Row(elem_classes=["bg-row"]):
+                        caption = gr.Checkbox(label="Captions", value=True)
+                        reference = gr.Checkbox(label="References", value=True)
+                        formatting = gr.Checkbox(label="Formatting", value=True)
+                        equation = gr.Checkbox(label="Equations", value=True)
+
+                with gr.TabItem("Writing"):
+                    with gr.Row(elem_classes=["bg-row"]):
+                        ai_artifacts = gr.Checkbox(label="AI artifacts", value=True)
+                        sentence = gr.Checkbox(label="Sentences", value=True)
+                        consistency = gr.Checkbox(label="Consistency", value=True)
+                        acronym = gr.Checkbox(label="Acronyms", value=True)
+                    with gr.Row(elem_classes=["bg-row"]):
+                        number = gr.Checkbox(label="Numbers", value=True)
+                        citation_quality = gr.Checkbox(label="Citations", value=True)
+                        anonymization = gr.Checkbox(label="Anonymization", value=True)
+                        _spacer()
+
+        # ───────────────────────── Status strip ─────────────────────────
+        status_panel = gr.HTML(value=EMPTY_STATUS_HTML, elem_id="bg-status-wrap")
+
+        # ───────────────────────── Report (full width) ───────────────────
+        with gr.Row(elem_classes=["bg-main"]):
+            report_panel = gr.HTML(value=EMPTY_PANEL_HTML)
+
+        # ───────────────────────── Downloads ────────────────────────────
+        with gr.Accordion("📥 Downloads", open=False):
+            with gr.Row(elem_classes=["bg-downloads"]):
+                download_html = gr.File(label="report.html (offline)",
+                                        interactive=False, elem_classes=["bg-file-input"])
+                download_md = gr.File(label="bibliography_report.md",
+                                      interactive=False, elem_classes=["bg-file-input"])
+                download_json = gr.File(label="report.json",
+                                        interactive=False, elem_classes=["bg-file-input"])
+                download_bib = gr.File(label="cleaned .bib",
+                                       interactive=False, elem_classes=["bg-file-input"])
+                download_log = gr.File(label="bibguard.log",
+                                       interactive=False, elem_classes=["bg-file-input"])
+
+        gr.HTML(
+            '<div class="bg-footer">'
+            'Set <code>$BIBGUARD_CONTACT_EMAIL</code> for the polite-pool User-Agent · '
+            f'persistent log at <code>{LOG_PATH}</code> · '
+            'set <code>BIBGUARD_DEBUG=1</code> for verbose console output.'
+            '</div>'
+        )
+
+        preset.change(
+            fn=apply_preset,
+            inputs=[preset],
+            outputs=[
+                check_metadata, check_usage, check_duplicates, check_preprint_ratio,
+                caption, reference, formatting, equation,
+                ai_artifacts, sentence, consistency, acronym,
+                number, citation_quality, anonymization,
+                url_liveness, retraction,
+            ],
+        )
+        preset.change(
+            fn=_preset_caption_html,
+            inputs=[preset],
+            outputs=[preset_caption],
+        )
+
+        # ---- Upload-button callbacks: store path in state + update chip ----
+
+        def _on_bib_upload(f):
+            if f is None:
+                return None, '<div class="bg-fname">no file selected</div>'
+            path = getattr(f, "name", str(f))
+            return path, f'<div class="bg-fname ok">📚 {Path(path).name}</div>'
+
+        def _on_tex_upload(f):
+            if f is None:
+                return None, '<div class="bg-fname">no file selected</div>'
+            path = getattr(f, "name", str(f))
+            return path, f'<div class="bg-fname ok">📄 {Path(path).name}</div>'
+
+        bib_btn.upload(_on_bib_upload, inputs=[bib_btn], outputs=[bib_path_state, bib_status])
+        tex_btn.upload(_on_tex_upload, inputs=[tex_btn], outputs=[tex_path_state, tex_status])
+
+        # Run pipeline:
+        #   1. Toggle visibility: hide Run, show Stop.
+        #   2. Stream run_check yields into report + status + downloads.
+        #   3. After completion, swap buttons back.
+        # Stop button cancels the streaming task via Gradio's `cancels=`.
+        def _show_stop():
+            return gr.update(visible=False), gr.update(visible=True)
+
+        def _show_run():
+            return gr.update(visible=True), gr.update(visible=False)
+
+        run_event = run_btn.click(
+            fn=_show_stop, inputs=None, outputs=[run_btn, stop_btn],
+        ).then(
             fn=run_check,
             inputs=[
-                bib_file, tex_file,
+                bib_path_state, tex_path_state,
                 check_metadata, check_usage, check_duplicates, check_preprint_ratio,
                 caption, reference, formatting, equation, ai_artifacts,
-                sentence, consistency, acronym, number, citation_quality, anonymization
+                sentence, consistency, acronym, number, citation_quality, anonymization,
+                url_liveness, retraction,
             ],
-            outputs=[bib_report, latex_report, line_report]
+            outputs=[report_panel, status_panel,
+                     download_html, download_md, download_json, download_bib, download_log],
+        ).then(
+            fn=_show_run, inputs=None, outputs=[run_btn, stop_btn],
+        )
+
+        stop_btn.click(
+            fn=lambda: (
+                gr.update(visible=True),
+                gr.update(visible=False),
+                _status_html("Cancelled",
+                             "Run interrupted by user. Partial results discarded.",
+                             state="error"),
+            ),
+            inputs=None,
+            outputs=[run_btn, stop_btn, status_panel],
+            cancels=[run_event],
         )
-    
+
     return app
 
 
-# Create the app
 app = create_app()
 
+
 if __name__ == "__main__":
+    _favicon = Path(__file__).parent / "assets" / "icon-192.png"
     app.launch(
-        favicon_path="assets/icon-192.png",
+        favicon_path=str(_favicon) if _favicon.exists() else None,
         show_error=True,
         css=CUSTOM_CSS,
-        theme=gr.themes.Soft()
+        theme=gr.themes.Soft(),
     )

app_helper.py

@@ -1,98 +1,307 @@
+"""
+Per-entry metadata verification: parallel multi-source lookup with corroboration.
+
+Strategy (in order):
+  1. **Identifier lookups, in parallel**:
+        - DOI → CrossRef, Semantic Scholar, OpenAlex
+        - arXiv ID → arXiv, Semantic Scholar
+     If the bib entry has either, this stage usually returns 2-3 independent
+     hits within a few hundred ms. Identifier lookups are far more reliable
+     than title search because the identifier is unique.
+
+  2. **Title searches across sources, in parallel** (always run as corroboration,
+     even if identifiers were found): Semantic Scholar, OpenAlex, DBLP, CrossRef,
+     arXiv. Each source returns top-K candidates; we keep the candidate whose
+     title most closely matches the bib title.
+
+  3. **Score & corroborate**:
+        - Pick the result with the highest per-source confidence.
+        - If ≥2 sources independently report the same title (sim ≥ 0.95) we
+          mark `is_match=True` even when individual confidences are middling
+          — multi-source agreement is the single strongest signal.
+        - Tightened thresholds: title sim ≥ 0.88 + year diff ≤ 1 (or year empty)
+          to declare a single-source match. Single-source matches that disagree
+          with corroborating sources are downgraded.
+
+The function still returns a single ComparisonResult so the rest of the
+pipeline doesn't change. Extra evidence (sources tried, agreement count) is
+stuffed into the `issues` field as informational notes when relevant.
+"""
+from __future__ import annotations
+
+import concurrent.futures as cf
+import logging
+from typing import List, Optional, Tuple
+
+from src.utils.normalizer import TextNormalizer
+
+logger = logging.getLogger(__name__)
+
+# Year tolerance for "match" (preprint vs published often differ by 1y).
+_YEAR_TOL = 1
+# Title similarity required for single-source match.
+_TITLE_MATCH_TIGHT = 0.88
+# Title similarity required to count as "corroborating" another source.
+_TITLE_AGREE = 0.95
+
+
+def _title_sim(a: str, b: str) -> float:
+    if not a or not b:
+        return 0.0
+    a_n = TextNormalizer.normalize_for_comparison(a)
+    b_n = TextNormalizer.normalize_for_comparison(b)
+    if not a_n or not b_n:
+        return 0.0
+    jacc = TextNormalizer.similarity_ratio(a_n, b_n)
+    if max(len(a_n), len(b_n)) < 200:
+        lev = TextNormalizer.levenshtein_similarity(a_n, b_n)
+        return max(jacc, lev)
+    return jacc
+
+
+def _year_close(y1: str, y2: str) -> bool:
+    """True if years are missing on either side or within ±1."""
+    y1, y2 = (y1 or "").strip(), (y2 or "").strip()
+    if not y1 or not y2:
+        return True
+    try:
+        return abs(int(y1[:4]) - int(y2[:4])) <= _YEAR_TOL
+    except ValueError:
+        return False
+
+
+def _pick_best_candidate(bib_title: str, candidates: list) -> Tuple[Optional[object], float]:
+    """Pick the candidate whose title most closely matches `bib_title`."""
+    best, best_sim = None, 0.0
+    for c in candidates:
+        sim = _title_sim(bib_title, getattr(c, "title", "") or "")
+        if sim > best_sim:
+            best, best_sim = c, sim
+    return best, best_sim
+
+
 def fetch_and_compare_with_workflow(
-    entry, workflow_steps, arxiv_fetcher, crossref_fetcher,
-    semantic_scholar_fetcher, openalex_fetcher, dblp_fetcher, comparator
+    entry,
+    workflow_steps,  # accepted for API compat; ignored — strategy is fixed
+    arxiv_fetcher,
+    crossref_fetcher,
+    semantic_scholar_fetcher,
+    openalex_fetcher,
+    dblp_fetcher,
+    comparator,
 ):
-    """Fetch metadata from online sources using the configured workflow."""
-    from src.utils.normalizer import TextNormalizer
-    
-    best_result = None
-    
-    # If no steps provided, use default order
-    if not workflow_steps:
-        # Create a default list of steps if needed, or simply handle logic here
-        pass
-
-    # Simplified workflow execution: Run through enabled steps
-    # We manualy iterate through sources in a preferred order if workflow is not fully configured
-    # Or iterate through the steps list.
-    
-    # Since extracting WorkflowConfig logic is complex, let's just implement a robust 
-    # default search strategy here which is what the user likely wants.
-    
-    results = []
-    
-    # 1. DBLP (High quality for CS)
-    if dblp_fetcher and entry.title:
-        try:
-            dblp_result = dblp_fetcher.search_by_title(entry.title)
-            if dblp_result:
-                res = comparator.compare_with_dblp(entry, dblp_result)
-                if res.is_match: return res
-                results.append(res)
-        except Exception: pass
-
-    # 2. Semantic Scholar (Comprehensive)
-    if semantic_scholar_fetcher and entry.title:
-        try:
-            ss_result = None
-            if entry.doi:
-                ss_result = semantic_scholar_fetcher.fetch_by_doi(entry.doi)
-            if not ss_result:
-                ss_result = semantic_scholar_fetcher.search_by_title(entry.title)
-            
-            if ss_result:
-                res = comparator.compare_with_semantic_scholar(entry, ss_result)
-                if res.is_match: return res
-                results.append(res)
-        except Exception: pass
-
-    # 3. OpenAlex
-    if openalex_fetcher and entry.title:
-        try:
-            oa_result = None
-            if entry.doi:
-                oa_result = openalex_fetcher.fetch_by_doi(entry.doi)
-            if not oa_result:
-                oa_result = openalex_fetcher.search_by_title(entry.title)
-                
-            if oa_result:
-                res = comparator.compare_with_openalex(entry, oa_result)
-                if res.is_match: return res
-                results.append(res)
-        except Exception: pass
-        
-    # 4. CrossRef (Official metadata)
-    if crossref_fetcher and entry.doi:
-        try:
-            crossref_result = crossref_fetcher.search_by_doi(entry.doi)
-            if crossref_result:
-                res = comparator.compare_with_crossref(entry, crossref_result)
-                if res.is_match: return res
-                results.append(res)
-        except Exception: pass
-        
-    # 5. ArXiv
-    if arxiv_fetcher:
-        try:
-            arxiv_meta = None
-            if entry.has_arxiv:
-                arxiv_meta = arxiv_fetcher.fetch_by_id(entry.arxiv_id)
-            elif entry.title:
-                # Search by title
-                search_results = arxiv_fetcher.search_by_title(entry.title, max_results=1)
-                if search_results:
-                    arxiv_meta = search_results[0]
-            
-            if arxiv_meta:
-                res = comparator.compare_with_arxiv(entry, arxiv_meta)
-                if res.is_match: return res
-                results.append(res)
-        except Exception: pass
-    
-    # Return the best result (highest confidence) if no perfect match found
-    if results:
-        results.sort(key=lambda x: x.confidence, reverse=True)
-        return results[0]
-        
-    # If absolutely nothing found, return None or an 'Unable' result
-    return comparator.create_unable_result(entry, "No metadata found in any source")
+    """Look up `entry` across all available sources in parallel and return a single ComparisonResult."""
+    has_doi = bool(getattr(entry, "doi", "") or "")
+    has_arxiv = bool(getattr(entry, "has_arxiv", False))
+    has_title = bool(getattr(entry, "title", "") or "")
+
+    if not (has_doi or has_arxiv or has_title):
+        return comparator.create_unable_result(entry, "Entry has no DOI, arXiv ID, or title to look up")
+
+    # ------------------------------------------------------------------ stage 1
+    # Tasks are tuples of (source_name, callable returning ComparisonResult or None).
+    tasks: list[tuple[str, callable]] = []
+
+    # Identifier-based lookups (high precision).
+    if has_doi and crossref_fetcher:
+        def _t_cr_doi(e=entry):
+            r = crossref_fetcher.search_by_doi(e.doi)
+            return comparator.compare_with_crossref(e, r) if r else None
+        tasks.append(("crossref(doi)", _t_cr_doi))
+
+    if has_doi and semantic_scholar_fetcher:
+        def _t_s2_doi(e=entry):
+            r = semantic_scholar_fetcher.fetch_by_doi(e.doi)
+            return comparator.compare_with_semantic_scholar(e, r) if r else None
+        tasks.append(("s2(doi)", _t_s2_doi))
+
+    if has_doi and openalex_fetcher:
+        def _t_oa_doi(e=entry):
+            r = openalex_fetcher.fetch_by_doi(e.doi)
+            return comparator.compare_with_openalex(e, r) if r else None
+        tasks.append(("openalex(doi)", _t_oa_doi))
+
+    if has_arxiv and arxiv_fetcher:
+        def _t_arxiv_id(e=entry):
+            r = arxiv_fetcher.fetch_by_id(e.arxiv_id)
+            return comparator.compare_with_arxiv(e, r) if r else None
+        tasks.append(("arxiv(id)", _t_arxiv_id))
+
+    if has_arxiv and semantic_scholar_fetcher and not has_doi:
+        # If we already queried S2 by DOI we don't double-bill.
+        def _t_s2_arxiv(e=entry):
+            r = semantic_scholar_fetcher.fetch_by_arxiv_id(e.arxiv_id)
+            return comparator.compare_with_semantic_scholar(e, r) if r else None
+        tasks.append(("s2(arxiv)", _t_s2_arxiv))
+
+    # Title-based lookups (always run as corroboration if title available).
+    if has_title:
+        if semantic_scholar_fetcher and not has_doi and not has_arxiv:
+            def _t_s2_title(e=entry):
+                cands = semantic_scholar_fetcher.search_by_title_multi(e.title, max_results=5)
+                best, _ = _pick_best_candidate(e.title, cands)
+                return comparator.compare_with_semantic_scholar(e, best) if best else None
+            tasks.append(("s2(title)", _t_s2_title))
+
+        if openalex_fetcher and not has_doi:
+            def _t_oa_title(e=entry):
+                cands = openalex_fetcher.search_by_title_multi(e.title, max_results=5)
+                best, _ = _pick_best_candidate(e.title, cands)
+                return comparator.compare_with_openalex(e, best) if best else None
+            tasks.append(("openalex(title)", _t_oa_title))
+
+        if dblp_fetcher:
+            def _t_dblp_title(e=entry):
+                cands = dblp_fetcher.search_by_title_multi(e.title, max_results=5)
+                best, _ = _pick_best_candidate(e.title, cands)
+                return comparator.compare_with_dblp(e, best) if best else None
+            tasks.append(("dblp(title)", _t_dblp_title))
+
+        if crossref_fetcher and not has_doi:
+            def _t_cr_title(e=entry):
+                cands = crossref_fetcher.search_by_title_multi(e.title, max_results=5)
+                best, _ = _pick_best_candidate(e.title, cands)
+                return comparator.compare_with_crossref(e, best) if best else None
+            tasks.append(("crossref(title)", _t_cr_title))
+
+        if arxiv_fetcher and not has_arxiv:
+            def _t_arxiv_title(e=entry):
+                cands = arxiv_fetcher.search_by_title(e.title, max_results=5)
+                best, _ = _pick_best_candidate(e.title, cands)
+                return comparator.compare_with_arxiv(e, best) if best else None
+            tasks.append(("arxiv(title)", _t_arxiv_title))
+
+    if not tasks:
+        return comparator.create_unable_result(entry, "No fetchers configured")
+
+    # Run in parallel with EARLY EXIT.
+    #
+    # Strategy:
+    #   - Submit every task to a pool.
+    #   - Drain `as_completed` with a SHORT poll deadline.
+    #   - Stop early as soon as we have one high-confidence match (≥0.85)
+    #     plus at least one corroborating result whose title aligns.
+    #   - Hard ceiling: 18s total wall-clock per entry. Whatever finished
+    #     by then is what we use; the rest is cancelled so we don't pay
+    #     the slowest-source penalty (a 80s-rate-limited S2 retry, e.g.).
+    results: list = []
+    sources_tried: list[str] = []
+    entry_key = getattr(entry, "key", "<unknown>")
+    deadline = __import__("time").monotonic() + 18.0
+    HIGH_CONF = 0.85
+
+    def _have_corroborated(rs: list) -> bool:
+        if not rs:
+            return False
+        rs_sorted = sorted(rs, key=lambda r: r.confidence, reverse=True)
+        primary = rs_sorted[0]
+        if primary.confidence < HIGH_CONF:
+            return False
+        for other in rs_sorted[1:]:
+            if other.fetched_title and _title_sim(primary.fetched_title,
+                                                  other.fetched_title) >= _TITLE_AGREE:
+                return True
+        return False
+
+    pool = cf.ThreadPoolExecutor(max_workers=min(8, len(tasks)))
+    future_to_name = {pool.submit(fn): name for name, fn in tasks}
+    try:
+        pending = set(future_to_name)
+        while pending:
+            remaining = deadline - __import__("time").monotonic()
+            if remaining <= 0:
+                logger.debug("Entry=%s: 18s deadline reached, %d sources still pending",
+                             entry_key, len(pending))
+                break
+            done, pending = cf.wait(pending, timeout=min(remaining, 2.0),
+                                    return_when=cf.FIRST_COMPLETED)
+            for fut in done:
+                name = future_to_name[fut]
+                sources_tried.append(name)
+                try:
+                    r = fut.result(timeout=0)
+                except Exception as e:
+                    logger.warning(
+                        "Lookup failed for entry=%s source=%s: %s",
+                        entry_key, name, e, exc_info=True,
+                    )
+                    continue
+                if r is not None:
+                    results.append(r)
+            if _have_corroborated(results):
+                logger.debug("Entry=%s: corroborated early after %d sources", entry_key, len(results))
+                break
+    finally:
+        # Cancel anything still in the queue; threads already running can't
+        # be killed, but they'll finish quietly without blocking us.
+        for fut in future_to_name:
+            if not fut.done():
+                fut.cancel()
+        pool.shutdown(wait=False, cancel_futures=True)
+
+    if not results:
+        return comparator.create_unable_result(
+            entry,
+            f"Tried {len(tasks)} sources ({', '.join(sources_tried) or 'none'}) — no metadata returned"
+        )
+
+    # ------------------------------------------------------------------ stage 2: pick + corroborate
+    # Sort by confidence; pick top.
+    results.sort(key=lambda r: r.confidence, reverse=True)
+    primary = results[0]
+
+    # Count corroborating sources that report a title within sim ≥ _TITLE_AGREE
+    # of the primary's fetched_title.
+    primary_title = primary.fetched_title
+    agree_count = 0
+    distinct_sources = set()
+    for r in results:
+        if r is primary:
+            continue
+        if not r.fetched_title:
+            continue
+        if _title_sim(primary_title, r.fetched_title) >= _TITLE_AGREE:
+            agree_count += 1
+            distinct_sources.add(r.source)
+
+    # ------------------------------------------------------------------ stage 3: refine match decision
+    # Tighten / loosen `is_match` based on corroboration + year tolerance.
+    title_ok_tight = primary.title_similarity >= _TITLE_MATCH_TIGHT
+    year_ok_loose = _year_close(primary.bib_year, primary.fetched_year)
+
+    if agree_count >= 1 and title_ok_tight:
+        primary.is_match = True
+    elif title_ok_tight and primary.author_match and year_ok_loose:
+        primary.is_match = True
+    elif primary.is_match and not (title_ok_tight and year_ok_loose):
+        # Original heuristic said match but our stricter rule disagrees.
+        primary.is_match = False
+        if not any("stricter check" in i.lower() for i in primary.issues):
+            primary.issues.append(
+                "Marked unverified by stricter check (title/year tolerance not met)."
+            )
+
+    # Boost / annotate confidence with corroboration signal.
+    if agree_count >= 1:
+        # Each corroborating source bumps confidence toward 1.0.
+        bonus = min(0.25, 0.1 + 0.05 * agree_count)
+        primary.confidence = min(1.0, primary.confidence + bonus)
+        # Positive note — goes to `notes`, NOT `issues`. Otherwise verified
+        # entries would display a misleading "1 issue(s)" badge.
+        primary.notes.append(
+            f"Corroborated by {agree_count} other source(s): {', '.join(sorted(distinct_sources))}."
+        )
+
+    # Year-only mismatch with otherwise solid match: drop the hard issue
+    # and record a soft note instead (preprint/published year difference).
+    if (primary.title_match and primary.author_match and not primary.year_match
+            and year_ok_loose and primary.bib_year and primary.fetched_year):
+        primary.issues = [
+            i for i in primary.issues if not i.startswith("Year mismatch")
+        ]
+        primary.notes.append(
+            f"Year differs by ≤1 ({primary.bib_year} vs {primary.fetched_year}) — "
+            "likely preprint/published difference, treated as match."
+        )
+
+    return primary

bibguard.yaml

@@ -27,6 +27,23 @@ files:
   output_dir: "test"
 
 
+# ==============================================================================
+# 🌐 Network / Politeness
+# ==============================================================================
+network:
+  # Real email used in User-Agent for arXiv/CrossRef/OpenAlex polite-pool requests.
+  # arXiv's robots policy asks for a real contact. Strongly recommended to fill in.
+  contact_email: ""
+
+  # Cache HTTP responses to a local SQLite DB. Same `entry.key` won't re-hit network
+  # within the TTL window. Hugely speeds up re-runs.
+  cache_enabled: true
+  cache_ttl_hours: 24
+
+  # Auto-retry on 429/5xx with exponential backoff.
+  retry_total: 5
+  retry_backoff_factor: 1.5
+
 # ==============================================================================
 # 🎓 Conference Template
 # ==============================================================================
@@ -59,7 +76,7 @@ bibliography:
   
   # Relevance Assessment - Use LLM to evaluate if citations match their context
   # Requires LLM configuration (see llm section below). Disabled by default due to API costs.
-  check_relevance: false
+  check_relevance: true
 
 # ==============================================================================
 # 📋 Submission Quality Checks
@@ -125,6 +142,21 @@ submission:
   # Detects GitHub links, acknowledgments, self-citations that may reveal author identity
   anonymization: true
 
+# ==============================================================================
+# 🌐 Network-Bound Bibliography Checks
+# ==============================================================================
+# These run only when explicitly enabled. Both operate solely on bib entries
+# that carry the relevant field (no DOI ⇒ retraction skipped, no url= ⇒
+# liveness skipped). The web UI's "Strict" preset turns both on.
+submission_extra:
+  # URL Liveness - HEAD-then-GET every entry.url to find dead links.
+  # Slow on large bibs (one HTTP roundtrip per URL); off by default.
+  url_liveness: false
+
+  # Retractions - Look up every entry.doi against CrossRef's update-to relation
+  # to flag retracted, withdrawn, or "expression of concern" papers.
+  retraction: true
+
 # ==============================================================================
 # 🔍 Metadata Check Workflow
 # ==============================================================================
@@ -133,7 +165,7 @@ submission:
 # Set enabled: false to skip a particular source.
 workflow:
   - name: arxiv_id
-    enabled: true
+    enabled: false
     description: "Lookup by arXiv ID (fastest, most reliable for preprints)"
     
   - name: crossref_doi  
@@ -153,7 +185,7 @@ workflow:
     description: "OpenAlex API (broad coverage across disciplines)"
     
   - name: arxiv_title
-    enabled: true
+    enabled: false
     description: "Search arXiv by title (fallback when ID unavailable)"
     
   - name: crossref_title
@@ -171,17 +203,18 @@ llm:
   # Backend provider: ollama, vllm, gemini, openai, anthropic, deepseek
   # Each backend requires different setup (API keys, local installation, etc.)
   backend: "gemini"
-  
+
   # Model name (leave empty to use backend default)
-  # Examples: "gpt-4", "claude-3-opus", "gemini-pro", "llama3"
+  # Examples: "gpt-4o-mini", "claude-haiku-4-5-20251001", "gemini-2.5-flash", "llama3"
   model: ""
   
   # API endpoint (leave empty to use backend default)
   # Only needed for self-hosted models (vllm, ollama) or custom endpoints
   endpoint: ""
   
-  # API key (recommended to use environment variables instead)
-  # Set GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. in your environment
+  # API key (RECOMMENDED: leave empty and use environment variables instead)
+  # Set GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, etc.
+  # in your shell. BibGuard will read from $<BACKEND>_API_KEY automatically.
   api_key: ""
 
 # ==============================================================================

main.py

@@ -7,8 +7,12 @@ Usage:
     python main.py --config my.yaml   # Use specified config file
     python main.py --init             # Create default config file
     python main.py --list-templates   # List available templates
+    python main.py --quick            # Skip network-bound metadata/relevance/url checks
+    python main.py --format json,html,markdown
+    python main.py --verbose          # DEBUG-level logs to stderr
 """
 import argparse
+import logging
 import sys
 from pathlib import Path
 from typing import Optional, List
@@ -19,10 +23,17 @@ from src.analyzers import MetadataComparator, UsageChecker, LLMEvaluator, Duplic
 from src.analyzers.llm_evaluator import LLMBackend
 from src.report.generator import ReportGenerator, EntryReport
 from src.utils.progress import ProgressDisplay
+from src.utils.logging_setup import setup as setup_logging
+from src.utils import http as http_layer
+from src.utils.validation import validate_bib, validate_tex, format_report
 from src.config.yaml_config import BibGuardConfig, load_config, find_config_file, create_default_config
 from src.config.workflow import WorkflowConfig, WorkflowStep as WFStep, get_default_workflow
 from src.templates.base_template import get_template, get_all_templates
 from src.checkers import CHECKER_REGISTRY, CheckResult, CheckSeverity
+from src.checkers.retraction_checker import RetractionChecker
+from src.checkers.url_checker import URLChecker
+
+logger = logging.getLogger("bibguard")
 
 
 def main():
@@ -52,8 +63,24 @@ Usage Examples:
         action="store_true",
         help="List all available conference templates"
     )
-    
+    parser.add_argument(
+        "--quick",
+        action="store_true",
+        help="Skip network-bound checks (metadata, retraction, URL liveness, LLM)",
+    )
+    parser.add_argument(
+        "--format",
+        default=None,
+        help="Comma-separated list of output formats (markdown, html, json). Defaults to config.",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Verbose (DEBUG) logging to stderr",
+    )
+
     args = parser.parse_args()
+    setup_logging("DEBUG" if args.verbose else None)
     
     # Handle --init
     if args.init:
@@ -95,25 +122,43 @@ Usage Examples:
         print(f"Error: Failed to parse config file: {e}")
         sys.exit(1)
     
+    # CLI overrides
+    if args.quick:
+        config.bibliography.check_metadata = False
+        config.bibliography.check_relevance = False
+        config.submission_extra.url_liveness = False
+        config.submission_extra.retraction = False
+    if args.format:
+        config.output.formats = [s.strip() for s in args.format.split(",") if s.strip()]
+
+    # Configure shared HTTP layer (retry + cache + UA)
+    http_layer.configure(
+        contact_email=config.network.contact_email,
+        cache_enabled=config.network.cache_enabled,
+        cache_ttl_hours=config.network.cache_ttl_hours,
+        retry_total=config.network.retry_total,
+        retry_backoff_factor=config.network.retry_backoff_factor,
+    )
+
     # Validate required fields
     mode_dir = bool(config.files.input_dir)
-    
+
     if mode_dir:
         input_dir = config.input_dir_path
         if not input_dir.exists() or not input_dir.is_dir():
             print(f"Error: Input directory does not exist or is not a directory: {input_dir}")
             sys.exit(1)
-            
+
         tex_files = list(input_dir.rglob("*.tex"))
         bib_files = list(input_dir.rglob("*.bib"))
-        
+
         if not tex_files:
             print(f"Error: No .tex files found in {input_dir}")
             sys.exit(1)
         if not bib_files:
             print(f"Error: No .bib files found in {input_dir}")
             sys.exit(1)
-            
+
         config._tex_files = tex_files
         config._bib_files = bib_files
     else:
@@ -123,7 +168,7 @@ Usage Examples:
         if not config.files.tex:
             print("Error: tex file path not specified in config")
             sys.exit(1)
-        
+
         # Validate files exist
         if not config.bib_path.exists():
             print(f"Error: Bib file does not exist: {config.bib_path}")
@@ -131,10 +176,29 @@ Usage Examples:
         if not config.tex_path.exists():
             print(f"Error: TeX file does not exist: {config.tex_path}")
             sys.exit(1)
-        
+
         config._tex_files = [config.tex_path]
         config._bib_files = [config.bib_path]
-    
+
+    # Pre-flight content validation (R6)
+    any_fatal = False
+    for bp in config._bib_files:
+        rep = validate_bib(bp)
+        msg = format_report(rep, label=bp.name)
+        if msg:
+            print(msg)
+        if not rep.ok:
+            any_fatal = True
+    for tp in config._tex_files:
+        rep = validate_tex(tp)
+        msg = format_report(rep, label=tp.name)
+        if msg:
+            print(msg)
+        if not rep.ok:
+            any_fatal = True
+    if any_fatal:
+        sys.exit(1)
+
     # Load template if specified
     template = None
     if config.template:
@@ -143,12 +207,12 @@ Usage Examples:
             print(f"Error: Unknown template: {config.template}")
             print("Use --list-templates to see available templates")
             sys.exit(1)
-    
+
     # Run the checker
     try:
         run_checker(config, template)
     except KeyboardInterrupt:
-        print("\n\nCancelled")
+        print("\n\n[BibGuard] Interrupted. Partial reports (if any) are in the output dir.")
         sys.exit(130)
     except Exception as e:
         print(f"\nError: {e}")
@@ -250,32 +314,62 @@ def run_checker(config: BibGuardConfig, template=None):
         [str(f) for f in config._tex_files]
     )
     
+    # Build the per-checker config dict (glossary, template, etc.)
+    checker_config = {
+        "glossary_preferred": config.glossary.preferred,
+        "glossary_acronyms": config.glossary.acronyms,
+        "template": template,
+    }
+
     # Run submission quality checks
     submission_results = []
-    enabled_checkers = config.submission.get_enabled_checkers()
-    
+    enabled_checkers = list(config.submission.get_enabled_checkers())
+    if template is not None and "template" not in enabled_checkers:
+        enabled_checkers.append("template")
+
     for checker_name in enabled_checkers:
         if checker_name in CHECKER_REGISTRY:
             checker = CHECKER_REGISTRY[checker_name]()
             for tex_path_str, content in tex_contents.items():
-                results = checker.check(content, {})
-                # Tag results with file path
-                for r in results:
-                    r.file_path = tex_path_str
+                # Run the checker on this file. We deliberately do NOT tag
+                # `r.file_path = tex_path_str` because user-facing reports
+                # never expose local tex paths (basename or full).
+                results = checker.check(content, checker_config)
                 submission_results.extend(results)
-    
+
     # Set results in report generator for summary calculation
     report_gen.set_submission_results(submission_results, template)
-    
+
     # Check for duplicates (silent)
     if bib_config.check_duplicates and duplicate_detector:
         duplicate_groups = duplicate_detector.find_duplicates(entries)
         report_gen.set_duplicate_groups(duplicate_groups)
-    
+
     # Check missing citations (silent)
     if bib_config.check_usage and usage_checker:
         missing = usage_checker.get_missing_entries(entries)
         report_gen.set_missing_citations(missing)
+
+    # Retraction lookups (F1)
+    if config.submission_extra.retraction:
+        try:
+            findings = RetractionChecker().check_entries(entries)
+            report_gen.set_retraction_findings(findings)
+            if findings:
+                logger.info("Retraction check found %d flagged entries", len(findings))
+        except Exception as e:
+            logger.debug("Retraction check failed: %s", e)
+
+    # URL liveness (F2)
+    if config.submission_extra.url_liveness:
+        try:
+            url_findings = URLChecker().check_entries(entries)
+            report_gen.set_url_findings(url_findings)
+            broken = sum(1 for f in url_findings if f.status != "ok")
+            if broken:
+                logger.info("URL liveness check: %d broken URL(s)", broken)
+        except Exception as e:
+            logger.debug("URL liveness check failed: %s", e)
     
     # Process entries
     
@@ -347,41 +441,46 @@ def run_checker(config: BibGuardConfig, template=None):
     # Determine number of workers (max 10 to avoid overwhelming APIs)
     max_workers = min(10, len(entries))
     
+    interrupted = False
     with progress.progress_context(len(entries), "Processing bibliography") as prog:
         # Use ThreadPoolExecutor for parallel processing
         with ThreadPoolExecutor(max_workers=max_workers) as executor:
             # Submit all tasks
             future_to_entry = {executor.submit(process_single_entry, entry): entry for entry in entries}
-            
+
             # Process completed tasks
-            for future in as_completed(future_to_entry):
-                entry = future_to_entry[future]
-                try:
-                    entry_report, comparison_result = future.result()
-                    
-                    # Thread-safe progress update
-                    with progress_lock:
-                        report_gen.add_entry_report(entry_report)
-                        
-                        # Update progress
-                        if comparison_result and comparison_result.is_match:
-                            prog.mark_success()
-                        elif comparison_result and comparison_result.has_issues:
-                            prog.mark_warning()
-                        else:
+            try:
+                for future in as_completed(future_to_entry):
+                    entry = future_to_entry[future]
+                    try:
+                        entry_report, comparison_result = future.result()
+
+                        # Thread-safe progress update
+                        with progress_lock:
+                            report_gen.add_entry_report(entry_report)
+
+                            # Update progress
+                            if comparison_result and comparison_result.is_match:
+                                prog.mark_success()
+                            elif comparison_result and comparison_result.has_issues:
+                                prog.mark_warning()
+                            else:
+                                prog.mark_error()
+
+                            completed_count[0] += 1
+                            prog.update(entry.key, "Done", 1)
+
+                    except Exception as e:
+                        with progress_lock:
                             prog.mark_error()
-                        
-                        completed_count[0] += 1
-                        prog.update(entry.key, "Done", 1)
-                        
-                except Exception as e:
-                    with progress_lock:
-                        prog.mark_error()
-                        progress.print_error(f"Error processing {entry.key}: {e}")
-                        completed_count[0] += 1
-                        prog.update(entry.key, "Failed", 1)
-    
-    # Summary will be printed at the very end
+                            progress.print_error(f"Error processing {entry.key}: {e}")
+                            completed_count[0] += 1
+                            prog.update(entry.key, "Failed", 1)
+            except KeyboardInterrupt:
+                interrupted = True
+                logger.warning("Interrupted by user; cancelling remaining work and saving partial reports")
+                for f in future_to_entry:
+                    f.cancel()
     
     # Generate reports and organize outputs (silent)
     
@@ -395,61 +494,55 @@ def run_checker(config: BibGuardConfig, template=None):
         shutil.copy2(bib_path, output_dir / bib_path.name)
     for tex_path in config._tex_files:
         shutil.copy2(tex_path, output_dir / tex_path.name)
-    # 1. Bibliography Report
-    bib_report_path = output_dir / "bibliography_report.md"
-    report_gen.save_bibliography_report(str(bib_report_path))
-    
-    # 2. LaTeX Quality Report
-    if submission_results:
-        latex_report_path = output_dir / "latex_quality_report.md"
-        report_gen.save_latex_quality_report(
-            str(latex_report_path),
-            submission_results,
-            template
-        )
-        
-        # 3. Line-by-Line Report
-        from src.report.line_report import generate_line_report
-        line_report_path = output_dir / "line_by_line_report.md"
-        
-        # For multiple files, we generate one big report with sections
-        all_line_reports = []
-        for tex_path_str, content in tex_contents.items():
-            file_results = [r for r in submission_results if r.file_path == tex_path_str]
-            if not file_results:
-                continue
-                
-            from src.report.line_report import LineByLineReportGenerator
-            gen = LineByLineReportGenerator(content, tex_path_str)
-            gen.add_results(file_results)
-            all_line_reports.append(gen.generate())
-            
-        if all_line_reports:
-            with open(line_report_path, 'w', encoding='utf-8') as f:
-                f.write("\n\n".join(all_line_reports))
-    
-    # 4. Clean bib file (if generated earlier)
+    requested_formats = {f.lower() for f in (config.output.formats or ["markdown", "html"])}
+
+    # 1. Bibliography Report (markdown)
+    if "markdown" in requested_formats:
+        bib_report_path = output_dir / "bibliography_report.md"
+        report_gen.save_bibliography_report(str(bib_report_path))
+
+        # 2. LaTeX Quality Report (markdown)
+        if submission_results:
+            latex_report_path = output_dir / "latex_quality_report.md"
+            report_gen.save_latex_quality_report(
+                str(latex_report_path),
+                submission_results,
+                template,
+            )
+
+    # 4. Self-contained HTML (★)
+    if "html" in requested_formats:
+        try:
+            report_gen.save_html(str(output_dir / "report.html"))
+        except Exception as e:
+            logger.warning("Failed to write HTML report: %s", e)
+
+    # 5. JSON output
+    if "json" in requested_formats:
+        try:
+            report_gen.save_json(str(output_dir / "report.json"))
+        except Exception as e:
+            logger.warning("Failed to write JSON report: %s", e)
+
+    # 6. Clean bib file (if generated earlier)
     if bib_config.check_usage and usage_checker:
         used_entries = [er.entry for er in report_gen.entries if er.usage and er.usage.is_used]
         if used_entries:
             try:
                 keys_to_keep = {entry.key for entry in used_entries}
-                # If multiple bibs, we merge them into one cleaned file
-                # or just use the first one if it's single mode.
-                # For now, let's just use a default name if multiple.
                 if len(config._bib_files) == 1:
                     clean_bib_path = output_dir / f"{config._bib_files[0].stem}_only_used.bib"
                     bib_parser.filter_file(str(config._bib_files[0]), str(clean_bib_path), keys_to_keep)
                 else:
                     clean_bib_path = output_dir / "merged_only_used.bib"
-                    # We need a way to filter multiple files into one.
-                    # BibParser.filter_file currently takes one input.
-                    # Let's just write all used entries to a new file.
                     with open(clean_bib_path, 'w', encoding='utf-8') as f:
                         for entry in used_entries:
-                            f.write(entry.raw + "\n\n")
+                            f.write(getattr(entry, "raw", "") + "\n\n")
             except Exception as e:
-                pass
+                logger.debug("Failed to write cleaned bib file: %s", e)
+
+    if interrupted:
+        print("[BibGuard] Saved partial reports for completed entries.")
     
     # Print beautiful console summary
     if not config.output.quiet:
@@ -461,85 +554,40 @@ def fetch_and_compare_with_workflow(
     entry, workflow_config, arxiv_fetcher, crossref_fetcher, scholar_fetcher,
     semantic_scholar_fetcher, openalex_fetcher, dblp_fetcher, comparator
 ):
-    """Fetch metadata from online sources using the configured workflow."""
-    from src.utils.normalizer import TextNormalizer
-    
-    all_results = []
-    enabled_steps = workflow_config.get_enabled_steps()
-    
-    for step in enabled_steps:
-        result = None
-        
-        if step.name == "arxiv_id" and entry.has_arxiv and arxiv_fetcher:
-            arxiv_meta = arxiv_fetcher.fetch_by_id(entry.arxiv_id)
-            if arxiv_meta:
-                result = comparator.compare_with_arxiv(entry, arxiv_meta)
-        
-        elif step.name == "crossref_doi" and entry.doi and crossref_fetcher:
-            crossref_result = crossref_fetcher.search_by_doi(entry.doi)
-            if crossref_result:
-                result = comparator.compare_with_crossref(entry, crossref_result)
-        
-        elif step.name == "semantic_scholar" and entry.title and semantic_scholar_fetcher:
-            ss_result = None
-            if entry.doi:
-                ss_result = semantic_scholar_fetcher.fetch_by_doi(entry.doi)
-            if not ss_result:
-                ss_result = semantic_scholar_fetcher.search_by_title(entry.title)
-            if ss_result:
-                result = comparator.compare_with_semantic_scholar(entry, ss_result)
-        
-        elif step.name == "dblp" and entry.title and dblp_fetcher:
-            dblp_result = dblp_fetcher.search_by_title(entry.title)
-            if dblp_result:
-                result = comparator.compare_with_dblp(entry, dblp_result)
-        
-        elif step.name == "openalex" and entry.title and openalex_fetcher:
-            oa_result = None
-            if entry.doi:
-                oa_result = openalex_fetcher.fetch_by_doi(entry.doi)
-            if not oa_result:
-                oa_result = openalex_fetcher.search_by_title(entry.title)
-            if oa_result:
-                result = comparator.compare_with_openalex(entry, oa_result)
-        
-        elif step.name == "arxiv_title" and entry.title and arxiv_fetcher:
-            results = arxiv_fetcher.search_by_title(entry.title, max_results=3)
-            if results:
-                best_result = None
-                best_sim = 0.0
-                norm1 = TextNormalizer.normalize_for_comparison(entry.title)
-                
-                for r in results:
-                    norm2 = TextNormalizer.normalize_for_comparison(r.title)
-                    sim = TextNormalizer.similarity_ratio(norm1, norm2)
-                    if sim > best_sim:
-                        best_sim = sim
-                        best_result = r
-                
-                if best_result and best_sim > 0.5:
-                    result = comparator.compare_with_arxiv(entry, best_result)
-        
-        elif step.name == "crossref_title" and entry.title and crossref_fetcher:
-            crossref_result = crossref_fetcher.search_by_title(entry.title)
-            if crossref_result:
-                result = comparator.compare_with_crossref(entry, crossref_result)
-        
-        elif step.name == "google_scholar" and entry.title and scholar_fetcher:
+    """
+    Fetch metadata across all configured sources and pick the best match.
+
+    Delegates the heavy lifting to ``app_helper.fetch_and_compare_with_workflow``,
+    which runs identifier-based and title-based lookups in parallel and uses
+    cross-source corroboration to decide is_match. Google Scholar is consulted
+    only as a last-resort fallback because scraping is fragile and frequently
+    blocked.
+    """
+    from app_helper import fetch_and_compare_with_workflow as _parallel_lookup
+
+    primary = _parallel_lookup(
+        entry, workflow_config, arxiv_fetcher, crossref_fetcher,
+        semantic_scholar_fetcher, openalex_fetcher, dblp_fetcher, comparator,
+    )
+
+    if primary and primary.source != "unable":
+        return primary
+
+    # Last-resort Google Scholar fallback (web scraping; frequently blocked).
+    if entry.title and scholar_fetcher:
+        try:
             scholar_result = scholar_fetcher.search_by_title(entry.title)
             if scholar_result:
-                result = comparator.compare_with_scholar(entry, scholar_result)
-        
-        if result:
-            all_results.append(result)
-            if result.is_match:
-                return result
-    
-    if all_results:
-        all_results.sort(key=lambda r: r.confidence, reverse=True)
-        return all_results[0]
-    
-    return comparator.create_unable_result(entry, "Unable to find this paper in any data source")
+                return comparator.compare_with_scholar(entry, scholar_result)
+        except Exception as e:
+            logger.warning(
+                "Google Scholar fallback failed for entry=%s: %s",
+                getattr(entry, "key", "<unknown>"), e, exc_info=True,
+            )
+
+    return primary or comparator.create_unable_result(
+        entry, "Unable to find this paper in any data source"
+    )
 
 
 def get_abstract(entry, comparison_result, arxiv_fetcher):

requirements.txt

@@ -1,6 +1,7 @@
 gradio>=6.0.0
 bibtexparser>=1.4.0
 requests>=2.31.0
+requests-cache>=1.2.0
 beautifulsoup4>=4.12.0
 rich>=13.7.0
 Unidecode>=1.3.0

scripts/install-hook.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Install a git pre-commit hook that runs BibGuard in --quick mode whenever
+# the staged changes touch .bib or .tex files.
+#
+# Usage (run from the repo root that contains your paper, NOT BibGuard's repo):
+#   bash /path/to/BibGuard/scripts/install-hook.sh
+#
+# Skip the hook for one commit:  git commit --no-verify
+set -euo pipefail
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo "Error: not inside a git repo." >&2
+  exit 1
+fi
+
+HOOK_DIR="$(git rev-parse --git-dir)/hooks"
+HOOK="$HOOK_DIR/pre-commit"
+
+# Locate BibGuard's main.py — we assume this script lives in BibGuard/scripts/.
+BIBGUARD_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MAIN_PY="$BIBGUARD_DIR/main.py"
+if [[ ! -f "$MAIN_PY" ]]; then
+  echo "Error: cannot locate BibGuard main.py at $MAIN_PY" >&2
+  exit 1
+fi
+
+mkdir -p "$HOOK_DIR"
+
+if [[ -f "$HOOK" ]]; then
+  echo "A pre-commit hook already exists at $HOOK"
+  echo "Backing it up to $HOOK.bibguard-backup"
+  mv "$HOOK" "$HOOK.bibguard-backup"
+fi
+
+cat >"$HOOK" <<EOF
+#!/usr/bin/env bash
+# BibGuard pre-commit hook (auto-generated)
+# Runs only if staged files include .tex or .bib.
+set -e
+
+if git diff --cached --name-only --diff-filter=ACM | grep -qE '\.(tex|bib)$'; then
+  echo "[BibGuard] Running quick checks on staged paper sources…"
+  python "$MAIN_PY" --quick || {
+    echo
+    echo "[BibGuard] Issues found. Fix or run:  git commit --no-verify  to skip."
+    exit 1
+  }
+fi
+EOF
+
+chmod +x "$HOOK"
+echo "Installed BibGuard pre-commit hook at: $HOOK"
+echo "It will run only when staged files include .tex or .bib."

src/analyzers/llm_evaluator.py

@@ -3,14 +3,18 @@ LLM-based citation relevance evaluator.
 Supports OpenAI, Anthropic, DeepSeek, Gemini, vLLM, and Ollama backends.
 """
 import json
+import logging
 import re
-from dataclasses import dataclass
-from typing import Optional, Dict, Any
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Tuple
 from enum import Enum
 import os
 
 import requests
 
+logger = logging.getLogger(__name__)
+
 
 class LLMBackend(Enum):
     OPENAI = "openai"
@@ -21,6 +25,52 @@ class LLMBackend(Enum):
     DEEPSEEK = "deepseek"
 
 
+# Map backend → environment variable name for the API key.
+_BACKEND_ENV = {
+    LLMBackend.OPENAI: "OPENAI_API_KEY",
+    LLMBackend.ANTHROPIC: "ANTHROPIC_API_KEY",
+    LLMBackend.GEMINI: "GEMINI_API_KEY",
+    LLMBackend.DEEPSEEK: "DEEPSEEK_API_KEY",
+    LLMBackend.VLLM: "VLLM_API_KEY",
+    LLMBackend.OLLAMA: "",  # local, no key
+}
+
+# Order in which we auto-detect a usable backend when the user hasn't picked
+# one explicitly. Cheapest/fastest first.
+_AUTODETECT_ORDER = [
+    LLMBackend.GEMINI,
+    LLMBackend.OPENAI,
+    LLMBackend.DEEPSEEK,
+    LLMBackend.ANTHROPIC,
+    LLMBackend.OLLAMA,
+]
+
+
+def autodetect_backend() -> Optional[Tuple[LLMBackend, str]]:
+    """
+    Find the first backend that has credentials in the environment.
+
+    Returns (backend, api_key) or None. For Ollama we attempt a localhost
+    probe so users with `ollama serve` running get auto-selected with no
+    config.
+    """
+    for backend in _AUTODETECT_ORDER:
+        env = _BACKEND_ENV.get(backend, "")
+        if env:
+            key = os.environ.get(env, "").strip()
+            if key:
+                return backend, key
+        elif backend == LLMBackend.OLLAMA:
+            # Local probe — small timeout so absence isn't painful.
+            try:
+                r = requests.get("http://localhost:11434/api/tags", timeout=1.0)
+                if r.status_code == 200:
+                    return backend, ""
+            except requests.RequestException:
+                continue
+    return None
+
+
 @dataclass
 class EvaluationResult:
     """Result of LLM citation evaluation."""
@@ -30,15 +80,16 @@ class EvaluationResult:
     explanation: str
     context_used: str
     abstract_used: str
+    citation_role: str = ""  # baseline | method | dataset | counterexample | survey | motivation | other
     line_number: Optional[int] = None
     file_path: Optional[str] = None
     error: Optional[str] = None
-    
+
     @property
     def score_label(self) -> str:
         labels = {
             1: "Not Relevant",
-            2: "Marginally Relevant", 
+            2: "Marginally Relevant",
             3: "Somewhat Relevant",
             4: "Relevant",
             5: "Highly Relevant"
@@ -49,7 +100,7 @@ class EvaluationResult:
 class LLMEvaluator:
     """Evaluates citation relevance using LLM."""
     
-    PROMPT_TEMPLATE = """You are an expert academic reviewer. Given a citation context from a LaTeX document and the cited paper's abstract, evaluate whether this citation is appropriate and relevant.
+    PROMPT_TEMPLATE = """You are an expert academic reviewer. Given a citation context from a LaTeX document and the cited paper's abstract, evaluate whether this citation is appropriate and relevant, and identify the citation's role in the manuscript.
 
 ## Citation Context (from the manuscript):
 {context}
@@ -62,23 +113,28 @@ Evaluate the relevance and appropriateness of this citation. Consider:
 1. Does the citation support the claim being made in the context?
 2. Is the cited paper's topic related to the discussion?
 3. Is this citation necessary, or could it be replaced with a more relevant one?
+4. What is the *role* of this citation in the manuscript?
+
+## Citation roles (pick exactly one):
+- "baseline": cited paper is used/compared as a baseline or prior method.
+- "method": cited paper introduces a method that the manuscript builds on or uses directly.
+- "dataset": cited paper provides a dataset/benchmark the manuscript uses.
+- "counterexample": cited to show a contrary finding or argue against.
+- "survey": cited as a survey/overview reference.
+- "motivation": cited to motivate the problem (background, application, statistics).
+- "other": none of the above clearly applies.
 
 ## Response Format:
-Provide your response in the following JSON format:
+Respond with ONE JSON object, no other text:
 {{
-    "relevance_score": <1-5 integer>,
-    "is_relevant": <true/false>,
-    "explanation": "<brief explanation in 1-2 sentences>"
+    "relevance_score": <integer 1-5>,
+    "is_relevant": <true|false>,
+    "citation_role": "<one of: baseline|method|dataset|counterexample|survey|motivation|other>",
+    "explanation": "<1-2 sentences>"
 }}
 
-Score guide:
-- 1: Not relevant at all
-- 2: Marginally relevant
-- 3: Somewhat relevant
-- 4: Relevant and appropriate
-- 5: Highly relevant and essential
-
-STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other text."""
+Score guide: 1=Not relevant, 2=Marginally, 3=Somewhat, 4=Relevant, 5=Highly relevant.
+STRICTLY FOLLOW THE JSON FORMAT."""
 
     def __init__(
         self,
@@ -90,28 +146,32 @@ STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other tex
         self.backend = backend
         self.api_key = api_key or os.environ.get(f"{backend.name}_API_KEY")
         
-        # Set defaults based on backend
+        # Set defaults based on backend (cheap, fast models that exist)
         if backend == LLMBackend.OPENAI:
             self.endpoint = endpoint or "https://api.openai.com/v1/chat/completions"
-            self.model = model or "gpt-5-mini"
+            self.model = model or "gpt-4o-mini"
         elif backend == LLMBackend.ANTHROPIC:
             self.endpoint = endpoint or "https://api.anthropic.com/v1/messages"
-            self.model = model or "claude-4.5-haiku"
+            self.model = model or "claude-haiku-4-5-20251001"
         elif backend == LLMBackend.DEEPSEEK:
             self.endpoint = endpoint or "https://api.deepseek.com/chat/completions"
             self.model = model or "deepseek-chat"
         elif backend == LLMBackend.OLLAMA:
             self.endpoint = endpoint or "http://localhost:11434/api/generate"
-            self.model = model or "Qwen/qwen3-4B-Instruct-2507"
+            self.model = model or "qwen2.5:3b-instruct"
         elif backend == LLMBackend.VLLM:
             self.endpoint = endpoint or "http://localhost:8000/v1/chat/completions"
-            self.model = model or "Qwen/qwen3-4B-Instruct-2507"
+            self.model = model or "Qwen/Qwen2.5-3B-Instruct"
         elif backend == LLMBackend.GEMINI:
             self.endpoint = endpoint or "https://generativelanguage.googleapis.com/v1beta/models"
-            self.model = model or "gemini-2.5-flash-lite"
+            self.model = model or "gemini-2.5-flash"
     
+    # Retry config for transient LLM failures (rate limits, server errors, JSON issues).
+    MAX_ATTEMPTS = 3
+    RETRY_BASE_DELAY = 1.5  # seconds, exponential
+
     def evaluate(self, entry_key: str, context: str, abstract: str) -> EvaluationResult:
-        """Evaluate citation relevance."""
+        """Evaluate citation relevance with retries on transient errors."""
         if not context or not abstract:
             return EvaluationResult(
                 entry_key=entry_key,
@@ -122,34 +182,51 @@ STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other tex
                 abstract_used=abstract,
                 error="Missing context or abstract for evaluation"
             )
-        
-        # Don't truncate - preserve full context and abstract
+
         prompt = self.PROMPT_TEMPLATE.format(context=context, abstract=abstract)
-        
-        try:
-            if self.backend in (LLMBackend.OPENAI, LLMBackend.DEEPSEEK, LLMBackend.VLLM):
-                response = self._call_openai_compatible(prompt)
-            elif self.backend == LLMBackend.ANTHROPIC:
-                response = self._call_anthropic(prompt)
-            elif self.backend == LLMBackend.OLLAMA:
-                response = self._call_ollama(prompt)
-            elif self.backend == LLMBackend.GEMINI:
-                response = self._call_gemini(prompt)
-            else:
-                raise ValueError(f"Unknown backend: {self.backend}")
-            
-            return self._parse_response(entry_key, response, context, abstract)
-            
-        except Exception as e:
-            return EvaluationResult(
-                entry_key=entry_key,
-                relevance_score=0,
-                is_relevant=False,
-                explanation="",
-                context_used=context,
-                abstract_used=abstract,
-                error=str(e)
-            )
+
+        last_err: Optional[str] = None
+        for attempt in range(1, self.MAX_ATTEMPTS + 1):
+            try:
+                if self.backend in (LLMBackend.OPENAI, LLMBackend.DEEPSEEK, LLMBackend.VLLM):
+                    response = self._call_openai_compatible(prompt)
+                elif self.backend == LLMBackend.ANTHROPIC:
+                    response = self._call_anthropic(prompt)
+                elif self.backend == LLMBackend.OLLAMA:
+                    response = self._call_ollama(prompt)
+                elif self.backend == LLMBackend.GEMINI:
+                    response = self._call_gemini(prompt)
+                else:
+                    raise ValueError(f"Unknown backend: {self.backend}")
+
+                parsed = self._parse_response(entry_key, response, context, abstract)
+                # Successful structured parse → return.
+                if parsed.error is None:
+                    return parsed
+                # JSON parse failed — retry with the same prompt; LLM jitter
+                # often resolves on a second pass.
+                last_err = parsed.error
+            except requests.exceptions.RequestException as e:
+                last_err = f"network: {e}"
+                # Transient: retry with backoff.
+            except Exception as e:
+                last_err = str(e)
+
+            if attempt < self.MAX_ATTEMPTS:
+                delay = self.RETRY_BASE_DELAY * (2 ** (attempt - 1))
+                logger.debug("LLM attempt %d/%d failed (%s); retrying in %.1fs",
+                             attempt, self.MAX_ATTEMPTS, last_err, delay)
+                time.sleep(delay)
+
+        return EvaluationResult(
+            entry_key=entry_key,
+            relevance_score=0,
+            is_relevant=False,
+            explanation="",
+            context_used=context,
+            abstract_used=abstract,
+            error=last_err or "Unknown error after retries"
+        )
     
     def _call_openai_compatible(self, prompt: str) -> str:
         """Call OpenAI-compatible API (OpenAI, DeepSeek, vLLM)."""
@@ -272,24 +349,77 @@ STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other tex
                 return parts[0].get("text", "")
         return ""
     
-    def _parse_response(self, entry_key: str, response: str, context: str, abstract: str) -> EvaluationResult:
-        """Parse LLM response."""
-        # Try to extract JSON from response
-        json_match = re.search(r'\{[^{}]*\}', response, re.DOTALL)
-        
-        data = {}
-        if not json_match:
-            # Try to parse the whole response as JSON
-            try:
-                data = json.loads(response.strip())
-            except json.JSONDecodeError:
-                pass
-        else:
+    @staticmethod
+    def _extract_json_object(text: str) -> Optional[dict]:
+        """
+        Robust JSON extraction. Handles:
+          - bare JSON
+          - fenced ```json ... ``` blocks
+          - JSON embedded in surrounding prose
+          - nested objects (the simple `\\{[^{}]*\\}` regex misses these)
+        """
+        if not text:
+            return None
+        s = text.strip()
+
+        # Direct parse
+        try:
+            obj = json.loads(s)
+            if isinstance(obj, dict):
+                return obj
+        except json.JSONDecodeError:
+            pass
+
+        # Strip Markdown code fences (```json ... ``` or ``` ... ```)
+        fence_match = re.search(r"```(?:json)?\s*(.*?)```", s, re.DOTALL | re.IGNORECASE)
+        if fence_match:
+            inner = fence_match.group(1).strip()
             try:
-                data = json.loads(json_match.group())
+                obj = json.loads(inner)
+                if isinstance(obj, dict):
+                    return obj
             except json.JSONDecodeError:
                 pass
-        
+            s = inner  # fall through to brace-balance scan on inner
+
+        # Brace-balanced scan: find the first complete top-level {...}.
+        start = s.find("{")
+        while start != -1:
+            depth = 0
+            in_str = False
+            esc = False
+            for i in range(start, len(s)):
+                ch = s[i]
+                if esc:
+                    esc = False
+                    continue
+                if ch == "\\":
+                    esc = True
+                    continue
+                if ch == '"':
+                    in_str = not in_str
+                    continue
+                if in_str:
+                    continue
+                if ch == "{":
+                    depth += 1
+                elif ch == "}":
+                    depth -= 1
+                    if depth == 0:
+                        chunk = s[start:i + 1]
+                        try:
+                            obj = json.loads(chunk)
+                            if isinstance(obj, dict):
+                                return obj
+                        except json.JSONDecodeError:
+                            break
+            start = s.find("{", start + 1)
+        return None
+
+    def _parse_response(self, entry_key: str, response: str, context: str, abstract: str) -> EvaluationResult:
+        """Parse LLM response with robust JSON extraction."""
+        data = self._extract_json_object(response) or {}
+
         if not data:
              return EvaluationResult(
                 entry_key=entry_key,
@@ -301,27 +431,44 @@ STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other tex
                 error="Failed to parse LLM response as JSON"
             )
         
-        # Extract fields
-        relevance_score = data.get("relevance_score", 0)
-        if isinstance(relevance_score, str):
-            try:
-                relevance_score = int(relevance_score)
-            except ValueError:
-                relevance_score = 0
-        
-        is_relevant = data.get("is_relevant", False)
+        # Extract & validate fields
+        raw_score = data.get("relevance_score", data.get("score", 0))
+        try:
+            relevance_score = int(float(raw_score))
+        except (TypeError, ValueError):
+            relevance_score = 0
+        relevance_score = max(0, min(5, relevance_score))
+
+        is_relevant = data.get("is_relevant", relevance_score >= 4)
         if isinstance(is_relevant, str):
-            is_relevant = is_relevant.lower() in ("true", "yes", "1")
-        
-        explanation = data.get("explanation", "")
-        
+            is_relevant = is_relevant.strip().lower() in ("true", "yes", "1", "y")
+
+        explanation = str(data.get("explanation", data.get("reason", ""))).strip()
+        citation_role = str(data.get("citation_role", data.get("role", ""))).strip().lower() or "other"
+        if citation_role not in {"baseline", "method", "dataset", "counterexample", "survey", "motivation", "other"}:
+            citation_role = "other"
+
+        # Sanity: a score of 0 means the LLM didn't actually return one — flag it.
+        if relevance_score == 0:
+            return EvaluationResult(
+                entry_key=entry_key,
+                relevance_score=0,
+                is_relevant=False,
+                explanation=explanation or response,
+                context_used=context,
+                abstract_used=abstract,
+                citation_role=citation_role,
+                error="LLM did not return a usable relevance_score",
+            )
+
         return EvaluationResult(
             entry_key=entry_key,
             relevance_score=relevance_score,
             is_relevant=is_relevant,
             explanation=explanation,
             context_used=context,
-            abstract_used=abstract
+            abstract_used=abstract,
+            citation_role=citation_role,
         )
     
     def test_connection(self) -> bool:
@@ -371,6 +518,7 @@ STRICTLY FOLLOW THE JSON FORMAT. Respond ONLY with the JSON object, no other tex
                 }
                 response = requests.post(url, json=payload, timeout=10)
                 return response.status_code == 200
-        except Exception:
+        except Exception as e:
+            logger.debug("LLM test_connection failed for %s: %s", self.backend.value, e)
             return False
         return False

src/analyzers/metadata_comparator.py

@@ -18,30 +18,41 @@ from ..utils.normalizer import TextNormalizer
 class ComparisonResult:
     """Result of comparing bib entry with fetched metadata."""
     entry_key: str
-    
+
     # Title comparison
     title_match: bool
     title_similarity: float
     bib_title: str
     fetched_title: str
-    
+
     # Author comparison
     author_match: bool
     author_similarity: float
     bib_authors: list[str]
     fetched_authors: list[str]
-    
+
     # Year comparison
     year_match: bool
     bib_year: str
     fetched_year: str
-    
+
     # Overall assessment
     is_match: bool
     confidence: float
     issues: list[str]
     source: str  # 'arxiv', 'crossref', 'scholar', 'semantic_scholar', 'openalex', 'dblp', or 'unable'
-    
+
+    # F4: When an arXiv preprint has a published counterpart, surface it here.
+    published_version_hint: str = ""  # e.g. "Also published at NeurIPS 2024 (doi:10.1145/...)"
+
+    # Positive / informational notes that should NOT be counted as issues
+    # (e.g. "corroborated by S2", "year differs by ≤1, treated as match").
+    notes: list[str] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.notes is None:
+            self.notes = []
+
     @property
     def has_issues(self) -> bool:
         return len(self.issues) > 0
@@ -60,7 +71,17 @@ class MetadataComparator:
     def compare_with_arxiv(self, bib_entry: BibEntry, arxiv_meta: ArxivMetadata) -> ComparisonResult:
         """Compare bib entry with arXiv metadata."""
         issues = []
-        
+
+        # F4: Extract a published-version hint if arXiv records it.
+        published_hint = ""
+        if arxiv_meta.journal_ref or arxiv_meta.doi:
+            parts = []
+            if arxiv_meta.journal_ref:
+                parts.append(arxiv_meta.journal_ref.strip())
+            if arxiv_meta.doi:
+                parts.append(f"doi:{arxiv_meta.doi.strip()}")
+            published_hint = "Has a published version — " + " | ".join(parts)
+
         # Compare titles
         bib_title_norm = self.normalizer.normalize_for_comparison(bib_entry.title)
         arxiv_title_norm = self.normalizer.normalize_for_comparison(arxiv_meta.title)
@@ -114,7 +135,8 @@ class MetadataComparator:
             is_match=is_match,
             confidence=confidence,
             issues=issues,
-            source="arxiv"
+            source="arxiv",
+            published_version_hint=published_hint,
         )
     
     def compare_with_scholar(self, bib_entry: BibEntry, scholar_result: ScholarResult) -> ComparisonResult:

src/checkers/__init__.py

@@ -11,6 +11,7 @@ from .consistency_checker import ConsistencyChecker
 from .citation_quality_checker import CitationQualityChecker
 from .equation_checker import EquationChecker
 from .acronym_checker import AcronymChecker
+from .template_checker import TemplateChecker
 
 __all__ = [
     'BaseChecker',
@@ -27,6 +28,7 @@ __all__ = [
     'CitationQualityChecker',
     'EquationChecker',
     'AcronymChecker',
+    'TemplateChecker',
 ]
 
 
@@ -43,6 +45,7 @@ CHECKER_REGISTRY = {
     'citation_quality': CitationQualityChecker,
     'equation': EquationChecker,
     'acronym': AcronymChecker,
+    'template': TemplateChecker,
 }
 
 

src/checkers/acronym_checker.py

@@ -87,23 +87,30 @@ class AcronymChecker(BaseChecker):
     }
     
     def check(self, tex_content: str, config: dict = None) -> List[CheckResult]:
+        config = config or {}
         results = []
-        
+
+        # Project glossary: skip-set + auto-defined map
+        user_acronyms = dict(config.get('glossary_acronyms', {}) or {})
+        # All user-supplied acronyms are considered "known/defined" — never warn about them.
+        glossary_skip = {k.upper() for k in user_acronyms.keys()}
+        common_plus_glossary = self.COMMON_ACRONYMS | glossary_skip
+
         # Remove comments using base class method
         content = self._remove_comments(tex_content)
-        
+
         # Find all defined acronyms with their positions
         defined_acronyms = self._find_definitions(content)
-        
+
         # Find all acronym usages (excluding special contexts)
         all_usages = self._find_all_usages(content)
-        
+
         # NEW: Find potential full forms for each acronym
         acronym_full_forms = self._find_potential_full_forms(content, all_usages.keys())
-        
+
         # Check for undefined acronyms (only those with matching full forms)
         for acronym, positions in all_usages.items():
-            if acronym in self.COMMON_ACRONYMS:
+            if acronym in common_plus_glossary:
                 continue
             
             # Skip if no matching full form found in document

src/checkers/ai_artifacts_checker.py

@@ -125,7 +125,7 @@ class AIArtifactsChecker(BaseChecker):
                         severity=CheckSeverity.ERROR,
                         message=f"{description} detected",
                         line_number=line_num,
-                        line_content=line.strip()[:100],
+                        line_content=line.strip(),
                         suggestion="Remove AI-generated conversational text"
                     ))
                     break  # One match per line for this category
@@ -139,7 +139,7 @@ class AIArtifactsChecker(BaseChecker):
                         severity=CheckSeverity.WARNING,
                         message=f"{description}: '{match.group(0)[:50]}'",
                         line_number=line_num,
-                        line_content=line.strip()[:100],
+                        line_content=line.strip(),
                         suggestion="Replace placeholder with actual content or remove"
                     ))
             
@@ -169,7 +169,7 @@ class AIArtifactsChecker(BaseChecker):
                         severity=CheckSeverity.INFO,
                         message=f"Possible {description} in LaTeX",
                         line_number=line_num,
-                        line_content=line.strip()[:100],
+                        line_content=line.strip(),
                         suggestion="Convert to LaTeX formatting or remove if unintentional"
                     ))
         

src/checkers/anonymization_checker.py

@@ -79,7 +79,7 @@ class AnonymizationChecker(BaseChecker):
                             severity=CheckSeverity.WARNING,
                             message=f"{desc} in comment (could be revealed when compiling)",
                             line_number=line_num,
-                            line_content=line.strip()[:100],
+                            line_content=line.strip(),
                             suggestion="Remove or anonymize URL even in comments"
                         ))
                 continue
@@ -91,7 +91,7 @@ class AnonymizationChecker(BaseChecker):
                         severity=CheckSeverity.ERROR,
                         message=f"{desc} may reveal author identity",
                         line_number=line_num,
-                        line_content=line.strip()[:100],
+                        line_content=line.strip(),
                         suggestion="Replace with anonymized URL or remove for review"
                     ))
         
@@ -112,7 +112,7 @@ class AnonymizationChecker(BaseChecker):
                         severity=CheckSeverity.WARNING,
                         message="Potentially self-revealing citation pattern",
                         line_number=line_num,
-                        line_content=line.strip()[:100],
+                        line_content=line.strip(),
                         suggestion="Rephrase to avoid revealing authorship (e.g., 'Prior work shows...')"
                     ))
         

src/checkers/base.py

@@ -29,7 +29,10 @@ class CheckResult:
     line_content: Optional[str] = None
     suggestion: Optional[str] = None
     file_path: Optional[str] = None
-    
+    # Substring of line_content that triggered the issue. The renderer wraps
+    # this in <mark> so the user can see *where* in the line to look.
+    match_text: Optional[str] = None
+
     def to_dict(self) -> dict:
         return {
             'checker': self.checker_name,
@@ -39,7 +42,8 @@ class CheckResult:
             'line': self.line_number,
             'content': self.line_content,
             'suggestion': self.suggestion,
-            'file_path': self.file_path
+            'file_path': self.file_path,
+            'match_text': self.match_text,
         }
 
 
@@ -178,7 +182,8 @@ class BaseChecker(ABC):
         message: str,
         line_number: Optional[int] = None,
         line_content: Optional[str] = None,
-        suggestion: Optional[str] = None
+        suggestion: Optional[str] = None,
+        match_text: Optional[str] = None,
     ) -> CheckResult:
         """Helper to create a CheckResult with this checker's name."""
         return CheckResult(
@@ -188,6 +193,7 @@ class BaseChecker(ABC):
             message=message,
             line_number=line_number,
             line_content=line_content,
-            suggestion=suggestion
+            suggestion=suggestion,
+            match_text=match_text,
         )
 

src/checkers/citation_quality_checker.py

@@ -124,7 +124,7 @@ class CitationQualityChecker(BaseChecker):
                         severity=CheckSeverity.WARNING,
                         message="Appears to be hardcoded citation instead of \\cite",
                         line_number=line_num,
-                        line_content=line.strip()[:80],
+                        line_content=line.strip(),
                         suggestion="Use \\cite{} for proper bibliography management"
                     ))
         

src/checkers/consistency_checker.py

@@ -149,25 +149,45 @@ class ConsistencyChecker(BaseChecker):
     ]
     
     def check(self, tex_content: str, config: dict = None) -> List[CheckResult]:
+        config = config or {}
         results = []
-        
+
         # Remove comments
         content = re.sub(r'(?<!\\)%.*$', '', tex_content, flags=re.MULTILINE)
         content_lower = content.lower()
-        
+
+        # Merge user glossary preferred terms into the variant table
+        glossary_preferred = list(config.get('glossary_preferred', []))
+        merged_variants = dict(self.KNOWN_VARIANTS)
+        for term in glossary_preferred:
+            term = (term or "").strip()
+            if not term:
+                continue
+            # Generate plausible variants: hyphen ↔ space ↔ collapsed; lower vs canonical
+            forms = {term}
+            if "-" in term:
+                forms.add(term.replace("-", " "))
+                forms.add(term.replace("-", ""))
+            if " " in term:
+                forms.add(term.replace(" ", "-"))
+                forms.add(term.replace(" ", ""))
+            forms.discard(term)
+            if forms:
+                merged_variants.setdefault(term, []).extend(sorted(forms))
+
         # Check for known variant inconsistencies
-        for canonical, variants in self.KNOWN_VARIANTS.items():
+        for canonical, variants in merged_variants.items():
             found_forms = []
-            
+
             # Check canonical form
             if re.search(rf'\b{re.escape(canonical)}\b', content, re.IGNORECASE):
                 found_forms.append(canonical)
-            
+
             # Check variants
             for variant in variants:
                 if re.search(rf'\b{re.escape(variant)}\b', content, re.IGNORECASE):
                     found_forms.append(variant)
-            
+
             if len(found_forms) > 1:
                 results.append(self._create_result(
                     passed=False,

src/checkers/formatting_checker.py

@@ -41,9 +41,6 @@ class FormattingChecker(BaseChecker):
         '^': r'(?<![\\$])\^(?![^$]*\$)',  # Unescaped ^ outside math
     }
     
-    # Multiple blank lines pattern (3 or more blank lines)
-    MULTI_BLANK_PATTERN = re.compile(r'\n\s*\n\s*\n\s*\n')
-    
     def check(self, tex_content: str, config: dict = None) -> List[CheckResult]:
         results = []
         lines = tex_content.split('\n')
@@ -66,8 +63,9 @@ class FormattingChecker(BaseChecker):
                     severity=CheckSeverity.INFO,
                     message="Citation without non-breaking space",
                     line_number=line_num,
-                    line_content=line.strip()[:100],
-                    suggestion="Use ~ before \\cite (e.g., 'text~\\cite{key}')"
+                    line_content=line.strip(),
+                    suggestion="Use ~ before \\cite (e.g., 'text~\\cite{key}')",
+                    match_text=match.group(0),
                 ))
             
             # Track citation styles
@@ -90,40 +88,6 @@ class FormattingChecker(BaseChecker):
                 suggestion="Consider using consistent citation style throughout"
             ))
         
-        # Check for multiple blank lines (3 or more)
-        for match in self.MULTI_BLANK_PATTERN.finditer(tex_content):
-            line_num = self._find_line_number(tex_content, match.start())
-            # Count how many blank lines
-            blank_count = match.group(0).count('\n') - 1
-            
-            # Get context: the line before, blank lines, and the line after
-            start_pos = match.start()
-            end_pos = match.end()
-            
-            # Find the line before the blank lines
-            prev_line_start = tex_content.rfind('\n', 0, start_pos) + 1
-            prev_line_end = start_pos
-            prev_line = tex_content[prev_line_start:prev_line_end].rstrip()
-            
-            # Find the line after the blank lines
-            next_line_end = tex_content.find('\n', end_pos)
-            if next_line_end == -1:
-                next_line_end = len(tex_content)
-            next_line = tex_content[end_pos:next_line_end].rstrip()
-            
-            # Create visual representation with warning markers
-            blank_lines = '\n'.join([f"> blank line ⚠️"] * blank_count)
-            line_content = f"{prev_line}\n{blank_lines}\n{next_line}"
-            
-            results.append(self._create_result(
-                passed=False,
-                severity=CheckSeverity.INFO,
-                message=f"Multiple blank lines ({blank_count} consecutive blank lines)",
-                line_number=line_num,
-                line_content=line_content,
-                suggestion="Reduce to single blank line or use \\vspace"
-            ))
-        
         # Check for common issues with special characters
         results.extend(self._check_special_chars(tex_content, lines))
         
@@ -159,8 +123,9 @@ class FormattingChecker(BaseChecker):
                             severity=CheckSeverity.WARNING,
                             message="Unescaped & outside tabular/math environment",
                             line_number=line_num,
-                            line_content=line.strip()[:100],
-                            suggestion="Use \\& to escape"
+                            line_content=line.strip(),
+                            suggestion="Use \\& to escape",
+                            match_text=match.group(0),
                         ))
         
         return results

src/checkers/retraction_checker.py

@@ -0,0 +1,53 @@
+"""
+Bibliography-level checker that flags retracted DOIs.
+
+Unlike the LaTeX-line checkers in src/checkers/, this one operates on parsed
+BibEntry objects, not on a tex_content string. main.py / app.py invoke it
+directly via `check_entries(entries)`.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import logging
+from dataclasses import dataclass
+from typing import Iterable, List
+
+from src.fetchers.retraction_fetcher import RetractionFetcher, RetractionResult
+from src.parsers.bib_parser import BibEntry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RetractionFinding:
+    entry_key: str
+    doi: str
+    result: RetractionResult
+
+
+class RetractionChecker:
+    """Concurrent batch retraction lookup."""
+
+    def __init__(self, max_workers: int = 6):
+        self.fetcher = RetractionFetcher()
+        self.max_workers = max_workers
+
+    def check_entries(self, entries: Iterable[BibEntry]) -> List[RetractionFinding]:
+        """Look up retraction status for every entry that has a DOI."""
+        with_doi = [e for e in entries if getattr(e, "doi", "")]
+        if not with_doi:
+            return []
+
+        findings: List[RetractionFinding] = []
+
+        def _one(entry: BibEntry):
+            res = self.fetcher.check(entry.doi)
+            return entry, res
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as ex:
+            for entry, res in ex.map(_one, with_doi):
+                if res is None:
+                    continue
+                if res.is_retracted or res.update_type:
+                    findings.append(RetractionFinding(entry.key, entry.doi, res))
+        return findings

src/checkers/sentence_checker.py

@@ -76,7 +76,7 @@ class SentenceChecker(BaseChecker):
                         severity=CheckSeverity.INFO,
                         message=message,
                         line_number=line_num,
-                        line_content=line.strip()[:80]
+                        line_content=line.strip()
                     ))
                     break  # One per line
             

src/checkers/template_checker.py

@@ -0,0 +1,393 @@
+"""
+Conference-template conformance checker.
+
+Reads the rich rule set defined in :mod:`src.templates.base_template` and runs
+per-venue checks against the LaTeX source. Each rule fragment lives in its own
+small private method so adding new conferences (or new rules) doesn't bloat the
+public ``check`` method.
+
+Severity convention used here:
+
+* ``ERROR``    — desk-reject material if uncorrected (NeurIPS missing checklist,
+                 ACL missing Limitations, double-blind \\author leak).
+* ``WARNING``  — likely a real problem but might be a false positive (style
+                 package mismatch, identifying URL).
+* ``INFO``     — soft reminder that something MUST happen later (camera-ready
+                 sections, lay summaries, font requirements, page-limit
+                 estimation that the .tex source can't actually verify).
+"""
+from __future__ import annotations
+
+import re
+from typing import List, Optional
+
+from .base import BaseChecker, CheckResult, CheckSeverity
+
+
+# ------------------------------------------------------------------ helpers ---
+
+# Match \section{X}, \subsection{X}, \paragraph{X}, optionally starred,
+# allowing an optional [short] argument before the {body}.
+def _section_pattern(name: str) -> re.Pattern:
+    return re.compile(
+        r'\\(?:section|subsection|paragraph)\*?\s*(?:\[[^\]]*\])?\s*\{[^}]*?'
+        + re.escape(name) + r'[^}]*\}',
+        re.IGNORECASE,
+    )
+
+
+# Domains/URL patterns that strongly de-anonymize an author. Whitelisted
+# domains (which legitimately appear in CV/ML papers without leaking identity)
+# are excluded.
+_IDENTIFYING_URL_PATTERNS = [
+    re.compile(r'\bgithub\.com/(?!anonymous)[A-Za-z0-9_\-]+/', re.IGNORECASE),
+    re.compile(r'\b[A-Za-z0-9_\-]+\.github\.io\b', re.IGNORECASE),
+    re.compile(r'\bgitlab\.com/(?!anonymous)[A-Za-z0-9_\-]+/', re.IGNORECASE),
+    re.compile(r'\bbitbucket\.org/(?!anonymous)[A-Za-z0-9_\-]+/', re.IGNORECASE),
+    re.compile(r'\b(?:huggingface\.co|wandb\.ai)/(?!anonymous)[A-Za-z0-9_\-]+/', re.IGNORECASE),
+    re.compile(r'\b(?:linkedin|twitter|x)\.com/[A-Za-z0-9_\-]+', re.IGNORECASE),
+]
+
+# URLs that are explicitly anonymous-friendly and should NOT be flagged.
+_ANONYMOUS_URL_HINTS = re.compile(
+    r'(anonymous|anon|blind|review|submission|4open\.science)', re.IGNORECASE,
+)
+
+# Capture URLs from \url{...}, \href{...}{...}, and bare http(s)://...
+_URL_FROM_TEX = re.compile(
+    r'\\(?:url|href)\s*\{([^}]+)\}|(?<![/\w])(https?://[^\s,)\\]+)',
+)
+
+# Acknowledgments macros / sections used by various templates.
+_ACK_PATTERNS = [
+    re.compile(r'\\section\*?\s*\{\s*Acknowledg\w*\s*\}', re.IGNORECASE),
+    re.compile(r'\\acknowledgments?\s*\{', re.IGNORECASE),
+    re.compile(r'\\begin\{acks\}', re.IGNORECASE),
+]
+
+# NeurIPS Paper Checklist markers — the official template either calls
+# \input{neurips_paper_checklist} or includes a \section*{NeurIPS Paper Checklist}.
+_NEURIPS_CHECKLIST_PATTERNS = [
+    re.compile(r'\\section\*?\s*\{[^}]*Paper\s+Checklist[^}]*\}', re.IGNORECASE),
+    re.compile(r'\\input\{[^}]*paper[_\-]?checklist[^}]*\}', re.IGNORECASE),
+    re.compile(r'\\input\{[^}]*neurips[_\-]?\d{0,4}[_\-]?checklist[^}]*\}', re.IGNORECASE),
+    re.compile(r'\\paperchecklist\b', re.IGNORECASE),
+]
+
+# Reproducibility Statement (ICLR / NeurIPS).
+_REPRO_SECTION = re.compile(
+    r'\\section\*?\s*\{[^}]*Reproducibility[^}]*\}', re.IGNORECASE,
+)
+
+# Document-class options carry the paper size.
+_DOCCLASS_RE = re.compile(
+    r'\\documentclass\s*(?:\[([^\]]*)\])?\s*\{([^}]+)\}'
+)
+
+# A very rough regex for figures/tables INSIDE the Limitations section
+# (used to enforce ACL "discussion only" rule).
+_FLOAT_OR_NEW_SECTION_RE = re.compile(
+    r'\\begin\{(?:table|figure|algorithm)\*?\}|\\section\*?\s*\{', re.IGNORECASE,
+)
+
+
+# ----------------------------------------------------------------- checker ---
+
+class TemplateChecker(BaseChecker):
+    name = "template"
+    display_name = "Conference Template"
+    description = "Verify per-venue submission rules (sections, style, anonymity, deliverables)"
+
+    def check(self, tex_content: str, config: dict = None) -> List[CheckResult]:
+        config = config or {}
+        template = config.get("template")
+        if template is None:
+            return []
+
+        content = self._remove_comments(tex_content)
+        results: List[CheckResult] = []
+
+        self._check_mandatory_sections(template, content, results)
+        self._check_camera_only_sections(template, content, results)
+        self._check_style_package(template, content, results)
+        self._check_doc_class(template, content, results)
+        self._check_paper_size(template, content, results)
+
+        if template.double_blind:
+            self._check_double_blind_author(template, content, results)
+            if template.forbid_identifying_urls:
+                self._check_identifying_urls(template, content, results)
+            if template.forbid_acks_in_review:
+                self._check_acknowledgments(template, content, results)
+
+        if template.requires_paper_checklist:
+            self._check_paper_checklist(template, content, results)
+        if template.requires_reproducibility_statement:
+            self._check_reproducibility_statement(template, content, results)
+        if template.requires_lay_summary_camera:
+            self._inform_lay_summary(template, results)
+        if template.requires_type1_fonts:
+            self._inform_type1_fonts(template, results)
+        if template.min_main_pages > 0:
+            self._inform_min_pages(template, results)
+
+        if "Limitations" in template.mandatory_sections:
+            self._check_limitations_content(template, content, results)
+
+        return results
+
+    # ============================================================== sections ==
+
+    def _check_mandatory_sections(self, template, content: str, results: List[CheckResult]):
+        for section in template.mandatory_sections or []:
+            if not _section_pattern(section).search(content):
+                results.append(self._create_result(
+                    passed=False,
+                    severity=CheckSeverity.ERROR,
+                    message=f"[{template.name}] Missing mandatory section: '{section}'",
+                    suggestion=f"Add `\\section{{{section}}}` (required by {template.name}).",
+                ))
+
+    def _check_camera_only_sections(self, template, content: str, results: List[CheckResult]):
+        for section in template.mandatory_camera_sections or []:
+            if not _section_pattern(section).search(content):
+                results.append(self._create_result(
+                    passed=False,
+                    severity=CheckSeverity.INFO,
+                    message=(
+                        f"[{template.name}] Camera-ready section '{section}' not found. "
+                        "Required for the camera-ready version, optional for review."
+                    ),
+                    suggestion=f"Add `\\section{{{section}}}` before References for camera-ready.",
+                ))
+
+    # =================================================== style / typesetting ==
+
+    def _check_style_package(self, template, content: str, results: List[CheckResult]):
+        pkg = (template.style_package or "").strip()
+        if not pkg:
+            return
+        pkg_re = re.compile(
+            r'\\(?:usepackage|documentclass)(?:\[[^\]]*\])?\s*\{\s*'
+            + re.escape(pkg) + r'\s*\}'
+        )
+        if not pkg_re.search(content):
+            results.append(self._create_result(
+                passed=False,
+                severity=CheckSeverity.WARNING,
+                message=(
+                    f"[{template.name}] Style package '{pkg}' not found. "
+                    "If you really are submitting to this venue, your template may be wrong."
+                ),
+                suggestion=f"Use the official `{pkg}` style package.",
+            ))
+
+    def _check_doc_class(self, template, content: str, results: List[CheckResult]):
+        wanted = (template.doc_class or "").strip()
+        if not wanted:
+            return
+        m = _DOCCLASS_RE.search(content)
+        actual = m.group(2).strip() if m else ""
+        if actual.lower() != wanted.lower():
+            results.append(self._create_result(
+                passed=False,
+                severity=CheckSeverity.WARNING,
+                message=(
+                    f"[{template.name}] Expected `\\documentclass{{{wanted}}}`, "
+                    f"found `{actual or 'none'}`."
+                ),
+                suggestion=f"Use the official document class `{wanted}` (Springer LNCS for ECCV).",
+            ))
+
+    def _check_paper_size(self, template, content: str, results: List[CheckResult]):
+        wanted = (template.paper_size or "").lower()
+        if wanted not in {"letter", "a4"}:
+            return
+        m = _DOCCLASS_RE.search(content)
+        if not m:
+            return
+        opts = (m.group(1) or "").lower()
+        actual = None
+        if "letterpaper" in opts or "letter" in opts:
+            actual = "letter"
+        elif "a4paper" in opts or "a4" in opts:
+            actual = "a4"
+        if actual and actual != wanted:
+            results.append(self._create_result(
+                passed=False,
+                severity=CheckSeverity.WARNING,
+                message=(
+                    f"[{template.name}] Expected paper size '{wanted}', "
+                    f"document class is set to '{actual}'."
+                ),
+                suggestion=f"Use `\\documentclass[{wanted}paper]{{...}}`.",
+            ))
+
+    # ================================================================ blinding =
+
+    def _check_double_blind_author(self, template, content: str, results: List[CheckResult]):
+        m = re.search(r'\\author\s*(?:\[[^\]]*\])?\s*\{([^}]*)\}', content)
+        if not m:
+            return
+        body = m.group(1)
+        if not body.strip():
+            return
+        if re.search(r'(anonymous|hidden|blind|submission)', body, re.IGNORECASE):
+            return
+        line_num = self._find_line_number(content, m.start())
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.ERROR,
+            message=f"[{template.name}] Double-blind: \\author appears to contain identifying info",
+            line_number=line_num,
+            line_content=body.strip(),
+            suggestion=r"Replace \author with anonymous placeholder during review.",
+        ))
+
+    def _check_identifying_urls(self, template, content: str, results: List[CheckResult]):
+        for m in _URL_FROM_TEX.finditer(content):
+            url = (m.group(1) or m.group(2) or "").strip()
+            if not url:
+                continue
+            if _ANONYMOUS_URL_HINTS.search(url):
+                continue
+            for pat in _IDENTIFYING_URL_PATTERNS:
+                if pat.search(url):
+                    line_num = self._find_line_number(content, m.start())
+                    results.append(self._create_result(
+                        passed=False,
+                        severity=CheckSeverity.WARNING,
+                        message=(
+                            f"[{template.name}] Possible identifying URL during double-blind review: "
+                            f"{url[:120]}"
+                        ),
+                        line_number=line_num,
+                        line_content=url,
+                        suggestion=(
+                            "Use Anonymous GitHub (https://anonymous.4open.science) or remove "
+                            "the link until the camera-ready version."
+                        ),
+                    ))
+                    break  # one finding per URL
+
+    def _check_acknowledgments(self, template, content: str, results: List[CheckResult]):
+        for pat in _ACK_PATTERNS:
+            m = pat.search(content)
+            if m:
+                line_num = self._find_line_number(content, m.start())
+                results.append(self._create_result(
+                    passed=False,
+                    severity=CheckSeverity.WARNING,
+                    message=(
+                        f"[{template.name}] Acknowledgments section detected; "
+                        f"{template.short_name.upper()} requires omitting it during review."
+                    ),
+                    line_number=line_num,
+                    suggestion=(
+                        "Comment out or wrap acks in `\\if<reviewmode>...\\fi` so they only "
+                        "appear in the camera-ready version."
+                    ),
+                ))
+                return  # one finding is enough
+
+    # ============================================== per-venue special items ===
+
+    def _check_paper_checklist(self, template, content: str, results: List[CheckResult]):
+        for pat in _NEURIPS_CHECKLIST_PATTERNS:
+            if pat.search(content):
+                return
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.ERROR,
+            message=(
+                f"[{template.name}] NeurIPS Paper Checklist not found. "
+                "NeurIPS desk-rejects submissions without the checklist."
+            ),
+            suggestion=(
+                "Add `\\input{neurips_paper_checklist}` (or paste the official template) "
+                "after References / supplementary."
+            ),
+        ))
+
+    def _check_reproducibility_statement(self, template, content: str, results: List[CheckResult]):
+        if _REPRO_SECTION.search(content):
+            return
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.INFO,
+            message=(
+                f"[{template.name}] Reproducibility Statement not found. "
+                "It's encouraged (~1 page) and does not count toward the page limit."
+            ),
+            suggestion=(
+                "Add `\\section*{Reproducibility Statement}` before References summarizing "
+                "code/data/seeds/hyperparameter availability."
+            ),
+        ))
+
+    def _inform_lay_summary(self, template, results: List[CheckResult]):
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.INFO,
+            message=(
+                f"[{template.name}] Lay summary required at camera-ready time "
+                "(plain-language summary submitted via OpenReview)."
+            ),
+            suggestion="Draft a 1–2 paragraph plain-language summary now to avoid a last-minute scramble.",
+        ))
+
+    def _inform_type1_fonts(self, template, results: List[CheckResult]):
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.INFO,
+            message=(
+                f"[{template.name}] Embedded fonts must be Type-1 only — verify with "
+                "`pdffonts <paper.pdf>`. Cannot be checked from .tex source alone."
+            ),
+            suggestion="Compile with `pdflatex` (not XeLaTeX/LuaLaTeX) and convert any Type-3 fonts.",
+        ))
+
+    def _inform_min_pages(self, template, results: List[CheckResult]):
+        results.append(self._create_result(
+            passed=False,
+            severity=CheckSeverity.INFO,
+            message=(
+                f"[{template.name}] Main text must be at least {template.min_main_pages} pages "
+                f"and at most {template.page_limit_review} pages. Cannot be measured from source."
+            ),
+            suggestion=(
+                f"Compile and confirm the rendered PDF stays within "
+                f"{template.min_main_pages}–{template.page_limit_review} pages of main text."
+            ),
+        ))
+
+    # ============================================ ACL family: Limitations rule
+
+    def _check_limitations_content(self, template, content: str, results: List[CheckResult]):
+        # Find the Limitations section span up to the next \section or end of doc.
+        m = re.search(
+            r'(\\section\*?\s*(?:\[[^\]]*\])?\s*\{[^}]*Limitations[^}]*\})',
+            content, re.IGNORECASE,
+        )
+        if not m:
+            return  # mandatory_sections check already flagged absence
+        start = m.end()
+        nxt = re.search(r'\\section\*?\s*\{', content[start:], re.IGNORECASE)
+        end = start + nxt.start() if nxt else len(content)
+        section_body = content[start:end]
+        # Discussion-only rule: no floats, no nested \section
+        if _FLOAT_OR_NEW_SECTION_RE.search(section_body):
+            line_num = self._find_line_number(content, start)
+            results.append(self._create_result(
+                passed=False,
+                severity=CheckSeverity.WARNING,
+                message=(
+                    f"[{template.name}] Limitations section appears to contain floats or a "
+                    "nested section. ACL/EMNLP/NAACL require Limitations to be discussion only."
+                ),
+                line_number=line_num,
+                suggestion=(
+                    "Move tables/figures/algorithms out of Limitations into the main body or "
+                    "appendix; Limitations should be prose-only."
+                ),
+            ))

src/checkers/url_checker.py

@@ -0,0 +1,80 @@
+"""
+URL liveness checker for bibliography entries.
+
+Many @misc / blog / repo references rot over time. This checker does a HEAD
+(falling back to a small GET) on entry.url and flags anything that returns
+4xx/5xx or fails to connect.
+
+Operates on BibEntry objects, not on tex_content. Invoked from main.py / app.py
+when `submission_extra.url_liveness` is true.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import logging
+from dataclasses import dataclass
+from typing import Iterable, List, Optional
+
+import requests
+
+from src.utils.http import get_session
+from src.parsers.bib_parser import BibEntry
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class URLFinding:
+    entry_key: str
+    url: str
+    status: str            # "ok" | "broken" | "unreachable" | "skipped"
+    status_code: Optional[int] = None
+    detail: str = ""
+
+
+class URLChecker:
+    """Concurrent HEAD-then-GET liveness check."""
+
+    SKIP_PREFIXES = ("mailto:", "ftp://", "tel:", "javascript:")
+
+    def __init__(self, max_workers: int = 8, timeout: float = 15.0):
+        self.max_workers = max_workers
+        self.timeout = timeout
+
+    def _check_one(self, entry: BibEntry) -> Optional[URLFinding]:
+        url = (entry.url or "").strip()
+        if not url:
+            return None
+        if any(url.lower().startswith(p) for p in self.SKIP_PREFIXES):
+            return URLFinding(entry.key, url, "skipped", detail="non-http scheme")
+
+        session = get_session()
+        try:
+            r = session.head(url, allow_redirects=True, timeout=self.timeout)
+            # Many servers return 405/403 for HEAD but are fine with GET; double-check with a tiny GET.
+            if r.status_code in (403, 405, 501):
+                r = session.get(url, allow_redirects=True, timeout=self.timeout, stream=True)
+                # Don't actually read the body
+                r.close()
+        except requests.RequestException as e:
+            logger.debug("URL check failed for %s: %s", url, e, exc_info=True)
+            return URLFinding(entry.key, url, "unreachable", detail=str(e)[:120])
+
+        if 200 <= r.status_code < 400:
+            return URLFinding(entry.key, url, "ok", status_code=r.status_code)
+        return URLFinding(
+            entry.key, url, "broken",
+            status_code=r.status_code,
+            detail=f"HTTP {r.status_code}",
+        )
+
+    def check_entries(self, entries: Iterable[BibEntry]) -> List[URLFinding]:
+        targets = [e for e in entries if getattr(e, "url", "")]
+        if not targets:
+            return []
+        findings: List[URLFinding] = []
+        with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as ex:
+            for f in ex.map(self._check_one, targets):
+                if f is not None:
+                    findings.append(f)
+        return findings

src/config/yaml_config.py

@@ -97,11 +97,36 @@ class LLMConfig:
     api_key: str = ""
 
 
-@dataclass 
+@dataclass
 class OutputConfig:
     """Output configuration."""
     quiet: bool = False
     minimal_verified: bool = False
+    formats: List[str] = field(default_factory=lambda: ["markdown", "html"])  # markdown, html, json
+
+
+@dataclass
+class NetworkConfig:
+    """Network / politeness configuration."""
+    contact_email: str = ""
+    cache_enabled: bool = True
+    cache_ttl_hours: int = 24
+    retry_total: int = 5
+    retry_backoff_factor: float = 1.5
+
+
+@dataclass
+class GlossaryConfig:
+    """User-supplied project glossary for ConsistencyChecker / AcronymChecker."""
+    preferred: List[str] = field(default_factory=list)  # e.g. ["Transformer", "fine-tuning"]
+    acronyms: Dict[str, str] = field(default_factory=dict)  # e.g. {"NLP": "Natural Language Processing"}
+
+
+@dataclass
+class SubmissionExtraConfig:
+    """Extra submission checks added on top of the original list."""
+    url_liveness: bool = False
+    retraction: bool = True
 
 
 @dataclass
@@ -111,9 +136,12 @@ class BibGuardConfig:
     template: str = ""
     bibliography: BibliographyConfig = field(default_factory=BibliographyConfig)
     submission: SubmissionConfig = field(default_factory=SubmissionConfig)
+    submission_extra: SubmissionExtraConfig = field(default_factory=SubmissionExtraConfig)
     workflow: List[WorkflowStep] = field(default_factory=list)
     llm: LLMConfig = field(default_factory=LLMConfig)
     output: OutputConfig = field(default_factory=OutputConfig)
+    network: NetworkConfig = field(default_factory=NetworkConfig)
+    glossary: GlossaryConfig = field(default_factory=GlossaryConfig)
     
     # Internal fields to store discovered files in directory mode
     _bib_files: List[Path] = field(default_factory=list)
@@ -225,11 +253,48 @@ def load_config(config_path: str) -> BibGuardConfig:
     # Parse output section
     if 'output' in data:
         out = data['output']
+        formats = out.get('formats', ["markdown", "html"])
+        if isinstance(formats, str):
+            formats = [f.strip() for f in formats.split(",") if f.strip()]
         config.output = OutputConfig(
             quiet=out.get('quiet', False),
-            minimal_verified=out.get('minimal_verified', False)
+            minimal_verified=out.get('minimal_verified', False),
+            formats=list(formats),
         )
-    
+
+    # Parse network section
+    if 'network' in data:
+        net = data['network'] or {}
+        config.network = NetworkConfig(
+            contact_email=net.get('contact_email', ''),
+            cache_enabled=bool(net.get('cache_enabled', True)),
+            cache_ttl_hours=int(net.get('cache_ttl_hours', 24)),
+            retry_total=int(net.get('retry_total', 5)),
+            retry_backoff_factor=float(net.get('retry_backoff_factor', 1.5)),
+        )
+
+    # Parse glossary section
+    if 'glossary' in data:
+        g = data['glossary'] or {}
+        preferred = g.get('preferred', []) or []
+        acronyms = g.get('acronyms', {}) or {}
+        if not isinstance(preferred, list):
+            preferred = [str(preferred)]
+        if not isinstance(acronyms, dict):
+            acronyms = {}
+        config.glossary = GlossaryConfig(
+            preferred=[str(x) for x in preferred],
+            acronyms={str(k): str(v) for k, v in acronyms.items()},
+        )
+
+    # Parse submission_extra section (URL liveness, retraction)
+    if 'submission_extra' in data:
+        sx = data['submission_extra'] or {}
+        config.submission_extra = SubmissionExtraConfig(
+            url_liveness=bool(sx.get('url_liveness', False)),
+            retraction=bool(sx.get('retraction', True)),
+        )
+
     return config
 
 
@@ -264,6 +329,15 @@ files:
 
 template: ""
 
+network:
+  # Real email used in polite-pool User-Agents (arXiv/CrossRef/OpenAlex).
+  # Strongly recommended.
+  contact_email: ""
+  cache_enabled: true       # Local SQLite cache for HTTP responses
+  cache_ttl_hours: 24
+  retry_total: 5
+  retry_backoff_factor: 1.5
+
 bibliography:
   check_metadata: true
   check_usage: true
@@ -285,16 +359,27 @@ submission:
   citation_quality: true
   anonymization: true
 
+submission_extra:
+  url_liveness: false       # HEAD-check every entry.url field (slow, off by default)
+  retraction: true          # Flag retracted DOIs via CrossRef
+
+# Project-specific glossary helps ConsistencyChecker and AcronymChecker
+# avoid false positives and enforce house style.
+glossary:
+  preferred: []             # e.g. ["Transformer", "fine-tuning"]
+  acronyms: {}              # e.g. {NLP: "Natural Language Processing"}
+
 llm:
-  backend: "gemini"
-  model: ""
-  api_key: ""
+  backend: "gemini"         # gemini | openai | anthropic | deepseek | ollama | vllm
+  model: ""                 # leave empty for sensible default per backend
+  api_key: ""               # prefer env var <BACKEND>_API_KEY
 
 output:
   quiet: false
   minimal_verified: false
+  formats: [markdown, html] # any of: markdown, html, json
 """
     with open(output_path, 'w', encoding='utf-8') as f:
         f.write(default)
-    
+
     return output_path