sciwrite-lint 0.2.0__py3-none-any.whl

sciwrite_lint/web.py

@@ -0,0 +1,369 @@
+"""Web resource verification: URL liveness check + content download as markdown.
+
+For citations that are blog posts, GitHub repos, or other web resources rather
+than academic papers. These skip academic APIs and instead verify the URL is
+alive and download content for LLM claim-checking.
+"""
+
+from __future__ import annotations
+
+import re
+from pydantic import BaseModel
+from pathlib import Path
+from urllib.parse import urlparse, urlunparse
+
+import httpx
+
+from sciwrite_lint._network import is_hostname_safe
+
+# Defaults (overridable via LintConfig)
+_DEFAULT_TIMEOUT = 15.0
+_DEFAULT_USER_AGENT = "sciwrite-lint/0.1 (citation-verification)"
+_MAX_HTML_BYTES = 10 * 1024 * 1024  # 10 MB — reject pages larger than this
+
+
+def _www_variant(url: str) -> str | None:
+    """Return the www-toggled variant of a URL, or None if not applicable."""
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    if host.startswith("www."):
+        alt_host = host[4:]
+    else:
+        alt_host = f"www.{host}"
+    # Rebuild netloc preserving port if present
+    if parsed.port:
+        alt_netloc = f"{alt_host}:{parsed.port}"
+    else:
+        alt_netloc = alt_host
+    return urlunparse(parsed._replace(netloc=alt_netloc))
+
+
+class WebResult(BaseModel):
+    """Result of a web resource verification attempt."""
+
+    url_alive: bool
+    status_code: int = 0
+    content_type: str = ""
+    local_path: str | None = None  # path relative to references/
+    title: str | None = None  # extracted page title
+    error: str | None = None
+    resolved_url: str | None = (
+        None  # URL that actually responded (may differ from input after www alternation)
+    )
+
+
+async def check_url(
+    url: str,
+    client: httpx.AsyncClient | None = None,
+    timeout: float = _DEFAULT_TIMEOUT,
+    user_agent: str = _DEFAULT_USER_AGENT,
+) -> WebResult:
+    """Check if a URL is alive via HEAD request, retry with GET on 405.
+
+    Alternates between www and non-www variants (adds www. if missing,
+    removes it if present) to handle sites where only one variant resolves.
+    """
+    own_client = client is None
+    if own_client:
+        client = httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": user_agent},
+        )
+    assert client is not None
+    try:
+        result = await _check_url_once(url, client, user_agent)
+
+        # Retry once on transient connection errors
+        if not result.url_alive and result.error and result.status_code == 0:
+            import asyncio as _asyncio
+
+            await _asyncio.sleep(1)
+            result = await _check_url_once(url, client, user_agent)
+
+        if result.url_alive:
+            result.resolved_url = url
+        else:
+            alt = _www_variant(url)
+            if alt:
+                alt_result = await _check_url_once(alt, client, user_agent)
+                if alt_result.url_alive:
+                    alt_result.resolved_url = alt
+                    return alt_result
+        return result
+    finally:
+        if own_client:
+            await client.aclose()
+
+
+async def _check_url_once(
+    url: str,
+    client: httpx.AsyncClient,
+    user_agent: str,
+) -> WebResult:
+    """Single-attempt URL liveness check (HEAD, retry with GET on 405)."""
+    try:
+        resp = await client.head(url, headers={"User-Agent": user_agent})
+        if resp.status_code == 405:
+            resp = await client.get(url, headers={"User-Agent": user_agent})
+    except httpx.HTTPError as e:
+        return WebResult(url_alive=False, error=str(e))
+
+    alive = 200 <= resp.status_code < 400
+    content_type = resp.headers.get("content-type", "")
+    return WebResult(
+        url_alive=alive,
+        status_code=resp.status_code,
+        content_type=content_type,
+    )
+
+
+async def fetch_web_content(
+    url: str,
+    key: str,
+    references_dir: Path,
+    client: httpx.AsyncClient | None = None,
+    timeout: float = _DEFAULT_TIMEOUT,
+    user_agent: str = _DEFAULT_USER_AGENT,
+) -> WebResult:
+    """Fetch a web page, extract content as markdown, save to references/.
+
+    Returns WebResult with local_path set if content was saved successfully.
+    Alternates between www and non-www variants if the original URL fails.
+    """
+    own_client = client is None
+    if own_client:
+        client = httpx.AsyncClient(
+            timeout=timeout,
+            follow_redirects=True,
+            headers={"User-Agent": user_agent},
+        )
+    assert client is not None
+    try:
+        resp, fetch_error = await _fetch_once(url, client, user_agent)
+
+        # Retry once on transient errors (decompression, connection reset)
+        if fetch_error is not None and resp is None:
+            import asyncio as _asyncio
+
+            await _asyncio.sleep(1)
+            resp, fetch_error = await _fetch_once(url, client, user_agent)
+
+        if fetch_error is not None or (resp is not None and resp.status_code >= 400):
+            alt = _www_variant(url)
+            if alt:
+                alt_resp, alt_error = await _fetch_once(alt, client, user_agent)
+                if (
+                    alt_error is None
+                    and alt_resp is not None
+                    and alt_resp.status_code < 400
+                ):
+                    resp, fetch_error = alt_resp, alt_error
+                    url = alt  # use working URL for saved metadata
+
+        if fetch_error is not None:
+            return WebResult(url_alive=False, error=fetch_error, resolved_url=url)
+
+        assert resp is not None  # mypy: if fetch_error is None, resp is set
+        if resp.status_code >= 400:
+            return WebResult(
+                url_alive=False,
+                status_code=resp.status_code,
+                error=f"HTTP {resp.status_code}",
+                resolved_url=url,
+            )
+
+        content_type = resp.headers.get("content-type", "")
+        html = resp.text
+
+        # Extract page title
+        title = _extract_title(html)
+
+        # Convert to markdown
+        markdown = _html_to_markdown(html, url)
+        if not markdown or len(markdown.strip()) < 100:
+            # Check for JS/meta redirect before giving up
+            redirect_url = _extract_redirect_url(html, url)
+            if redirect_url and redirect_url != url:
+                from loguru import logger
+
+                logger.info("Following redirect from {} to {}", key, redirect_url)
+                redirect_resp, redirect_err = await _fetch_once(
+                    redirect_url, client, user_agent
+                )
+                if redirect_err is None and redirect_resp is not None:
+                    html = redirect_resp.text
+                    url = redirect_url
+                    title = _extract_title(html) or title
+                    markdown = _html_to_markdown(html, url)
+
+        if not markdown or len(markdown.strip()) < 100:
+            return WebResult(
+                url_alive=True,
+                status_code=resp.status_code,
+                content_type=content_type,
+                title=title,
+                error="Content extraction failed"
+                if not markdown
+                else f"Extracted content too short ({len(markdown.strip())} chars)",
+                resolved_url=url,
+            )
+
+        # Save to references/
+        references_dir.mkdir(parents=True, exist_ok=True)
+        dest = references_dir / f"{key}_web.md"
+        header = f"# {title or key}\n\nSource: {url}\n\n---\n\n"
+        dest.write_text(header + markdown, encoding="utf-8")
+        local_path = str(dest.relative_to(references_dir))
+
+        return WebResult(
+            url_alive=True,
+            status_code=resp.status_code,
+            content_type=content_type,
+            local_path=local_path,
+            title=title,
+            resolved_url=url,
+        )
+    finally:
+        if own_client:
+            await client.aclose()
+
+
+async def _fetch_once(
+    url: str,
+    client: httpx.AsyncClient,
+    user_agent: str,
+    max_bytes: int = _MAX_HTML_BYTES,
+) -> tuple[httpx.Response | None, str | None]:
+    """Single GET attempt with size enforcement.
+
+    Uses streaming with a gzip-safe size guard: skips Content-Length
+    pre-check when Content-Encoding is present (compressed wire size
+    != decompressed body size), and always enforces max_bytes on the
+    decompressed data stream.
+    """
+    try:
+        async with client.stream(
+            "GET", url, headers={"User-Agent": user_agent}
+        ) as resp:
+            # Only trust Content-Length when no Content-Encoding —
+            # otherwise the header reports compressed wire size,
+            # not the decompressed size we'll actually read.
+            if not resp.headers.get("content-encoding"):
+                cl = resp.headers.get("content-length")
+                if cl and int(cl) > max_bytes:
+                    return None, f"Response too large ({cl} bytes)"
+
+            # Byte-count guard on decompressed data — always enforced
+            chunks: list[bytes] = []
+            total = 0
+            async for chunk in resp.aiter_bytes():
+                total += len(chunk)
+                if total > max_bytes:
+                    return None, f"Response exceeded {max_bytes} bytes during download"
+                chunks.append(chunk)
+
+        body = b"".join(chunks)
+        full_resp = httpx.Response(
+            status_code=resp.status_code,
+            headers=resp.headers,
+            content=body,
+            request=resp.request,
+        )
+        return full_resp, None
+    except httpx.HTTPError as e:
+        return None, str(e)
+
+
+def _extract_title(html: str) -> str | None:
+    """Extract <title> from HTML."""
+    match = re.search(r"<title[^>]*>(.*?)</title>", html, re.IGNORECASE | re.DOTALL)
+    if match:
+        title = match.group(1).strip()
+        title = re.sub(r"\s+", " ", title)
+        return title if title else None
+    return None
+
+
+def _extract_redirect_url(html: str, source_url: str) -> str | None:
+    """Extract redirect target from HTML meta-refresh or JS patterns.
+
+    Detects:
+      - <meta http-equiv="refresh" content="0;url=...">
+      - window.location = "..."
+      - window.location.href = "..."
+      - window.location.replace("...")
+      - document.location = "..."
+      - document.location.href = "..."
+
+    Returns None if multiple conflicting redirect targets are found.
+    """
+    targets: set[str] = set()
+
+    # Meta refresh
+    match = re.search(
+        r'<meta[^>]+http-equiv=["\']?refresh["\']?[^>]+content=["\']?\d+;\s*url=([^"\'>]+)',
+        html,
+        re.IGNORECASE,
+    )
+    if match:
+        targets.add(_resolve_url(match.group(1).strip(), source_url))
+
+    # JS location patterns
+    for pattern in (
+        r'(?:window|document)\.location(?:\.href)?\s*=\s*["\']([^"\']+)["\']',
+        r'(?:window|document)\.location\.replace\(\s*["\']([^"\']+)["\']\s*\)',
+    ):
+        for m in re.finditer(pattern, html):
+            targets.add(_resolve_url(m.group(1).strip(), source_url))
+
+    # Filter out unsafe redirect targets
+    safe_targets = {t for t in targets if _is_safe_redirect(t)}
+    if safe_targets != targets:
+        from loguru import logger
+
+        blocked = targets - safe_targets
+        logger.warning("Blocked unsafe redirect target(s): {}", blocked)
+
+    if len(safe_targets) == 1:
+        return safe_targets.pop()
+
+    if len(safe_targets) > 1:
+        from loguru import logger
+
+        logger.warning(
+            "Multiple conflicting redirect targets found, ignoring: {}",
+            safe_targets,
+        )
+
+    return None
+
+
+def _is_safe_redirect(url: str) -> bool:
+    """Check that a redirect URL is safe to follow.
+
+    Rejects non-HTTPS/HTTP schemes and any hostname that resolves to a
+    non-public IP. Delegates IP validation to ``_network.is_hostname_safe``.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        return False
+    host = (parsed.hostname or "").lower()
+    if not host:
+        return False
+    return is_hostname_safe(host)
+
+
+def _resolve_url(target: str, source_url: str) -> str:
+    """Resolve a possibly-relative redirect URL against the source URL."""
+    from urllib.parse import urljoin
+
+    return urljoin(source_url, target)
+
+
+def _html_to_markdown(html: str, url: str) -> str | None:
+    """Convert HTML to clean markdown using trafilatura."""
+    import trafilatura
+
+    result = trafilatura.extract(html, url=url, include_links=True)
+    return result or None

sciwrite_lint-0.2.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: sciwrite-lint
+Version: 0.2.0
+Summary: A linter for scientific manuscripts — reference verification, consistency checking, and structural validation.
+Author: Sergey Samsonau
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/authentic-research-partners/sciwrite-lint
+Project-URL: Repository, https://github.com/authentic-research-partners/sciwrite-lint
+Project-URL: Issues, https://github.com/authentic-research-partners/sciwrite-lint/issues
+Keywords: linter,scientific-writing,citation-verification,latex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: tenacity>=8.0
+Requires-Dist: trafilatura>=1.8
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: loguru>=0.7
+Requires-Dist: anyascii>=0.3
+Requires-Dist: rich>=13.0
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rapidfuzz>=3.0
+Requires-Dist: bibtexparser>=1.4
+Requires-Dist: pdfplumber>=0.10
+Requires-Dist: openai>=1.0
+Requires-Dist: grobid-tei-xml>=0.1
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.45
+Requires-Dist: Pillow>=10.0
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pypdfium2>=4.0
+Requires-Dist: pdf2image>=1.16
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.0; extra == "dev"
+Dynamic: license-file
+
+# sciwrite-lint
+
+A linter for scientific manuscripts. Checks that your references exist, your metadata is accurate, your citations support the claims you make, and your cited papers' own bibliographies are real. Works on LaTeX and PDF. Runs entirely on your machine. Produces a **SciLint Score**.
+
+The only open-source tool that combines reference verification, claim checking, manuscript consistency, figure analysis, and bibliography verification in one pipeline — powered entirely by a local LLM on your own GPU.
+
+## Why
+
+AI writing tools produce text that *looks* like good science — fluent prose, correct formatting, plausible-sounding citations. But they don't verify whether the references are real, whether the cited papers actually say what you claim, or whether the numbers in your abstract match your results.
+
+**sciwrite-lint does.** It checks your references against academic databases, downloads the cited papers, verifies that they actually say what you claim, and follows one level deeper to check your references' own bibliographies. Fully local — no manuscripts leave your machine.
+
+## Features
+
+**22 automated checks:**
+
+### Reference verification
+- **Do your references exist?** — checked against CrossRef, OpenAlex, Semantic Scholar, Open Library, and Library of Congress
+- **Is the metadata accurate?** — title, authors, year, venue compared against canonical records
+- **Are any retracted?** — every DOI cross-referenced against 60,000+ entries in the Retraction Watch database
+- **Robust matching** — when references lack DOIs, a multi-signal matching engine scores candidates across title, author, year, and venue (handles the metadata errors that LLMs routinely introduce)
+
+### Claim verification (local LLM)
+- **Do cited papers support your claims?** — downloads full text from 8 open-access sources (arXiv, Semantic Scholar, OpenAlex, PubMed Central, Europe PMC, Unpaywall, bioRxiv/medRxiv, CORE), parses via GROBID, embeds sections, and verifies each claim against the actual source text
+- **What role does each citation play?** — classifies citation purpose (evidence, contrast, method, attribution, context…) with graduated weights: an unsupported *evidence* citation is serious; an unsupported *context* citation barely matters
+- **Are your references' own bibliographies real?** — batch-checks cited papers' reference lists for existence, metadata accuracy, and retraction. Papers built on fabricated evidence are flagged
+
+### Manuscript consistency (local LLM)
+- **Cross-section contradictions** — numbers, claims, and framing that drift between sections
+- **Numbers vs. tables** — text claims that contradict the corresponding table or figure
+- **Arithmetic and percentages** — stated totals that don't match components; percentages that don't sum to 100%
+- **Sample size tracking** — N values that change across sections without explanation
+- **Causal language** — unhedged causal claims in correlational studies
+- **Abstract–body alignment** — abstract makes factual claims the body contradicts
+- **Statistical reporting** — p-values vs. their verbal interpretation
+- **Structure promises** — contributions promised in the introduction but never delivered
+
+### Figure checks (vision model + LLM)
+- **Caption vs. content** — does the caption match what the figure actually shows?
+- **Text vs. figure** — does the text describe the figure accurately?
+- **Axis labels** — units, labels, and scales consistent with the text
+- **Figure–table agreement** — same data in a figure and table should agree
+
+### Text checks (deterministic, no services needed)
+- **Dangling citations** — `\cite{key}` with no matching bib entry
+- **Dangling cross-references** — `\ref{X}` with no matching `\label{X}`
+- **Unreferenced figures** — figures included but never referenced in the text
+
+### Per-reference reliability score
+All signals — metadata, retraction status, claim support, consistency, bibliography health — aggregate into a single reliability score per reference. When multiple independent checks flag the same reference, it is flagged as unreliable with specific reasons.
+
+### SciLint Score
+
+```
+SciLint Score = Internal Consistency × Referencing Quality × Contribution
+```
+
+A single number combining:
+- **Internal Consistency** — fraction of checks passed within the manuscript
+- **Referencing Quality** — are references real, accurate, and do they support your claims? Each reference weighted by its reliability score and citation purpose
+- **Contribution** *(experimental)* — five axes from philosophy of science (Popper, Lakatos, Kitcher, Laudan, Mayo): empirical content, progressiveness, unification, problem-solving effectiveness, test severity. Defaults to 1.0 until `contributions` runs
+
+```bash
+sciwrite-lint contributions paper.pdf --format json
+```
+
+### Privacy and security
+
+- **Your manuscript never leaves your machine.** All parsing, LLM inference, and figure analysis run locally
+- **Only citation metadata is sent externally** — DOIs, titles, author names for API verification. No paper content
+- **Open-weights models pinned to specific versions** — results are reproducible forever, not dependent on a cloud provider's API updates
+- **No API keys required** — all verification uses free public databases. Optional keys increase rate limits
+
+### Two audiences
+
+- **Humans** — colored terminal output with severity levels, locations, and explanations. Decide in seconds whether each finding is real
+- **AI writing agents** — `--format json` output with structured fields (`level`, `rule_id`, `message`, `context`). Run sciwrite-lint in a write → check → fix → recheck loop. Configurable exit codes for CI integration
+
+### Optimizations
+
+Three models — a vision model (Qwen3-VL-2B), an embedding model (Arctic Embed), and an 8B reasoning LLM (Qwen3 via vLLM) — share a single consumer GPU. Models run in separate pipeline stages; on WSL2, CUDA memory virtualization pages idle allocations to system RAM, letting all three share physical VRAM. FP8 weights and KV cache (Ada Lovelace+) and per-paper SQLite caching with hash-based invalidation are baseline. On top of that:
+
+- **Semantic section filtering** — embedding-based KNN retrieval sends only the ~5 most relevant sections per claim to the LLM, reducing LLM calls ~4x
+- **Prefix-first prompt structure** — shared context placed before variable content in all prompts, maximizing vLLM's automatic prefix caching
+- **Per-call-site thinking budgets** — each LLM call site has empirically tuned (max_tokens, thinking_preset) pairs, measured via grid search to maximize detection quality
+- **Adaptive embedding batches** — token-aware batch sizing gives ~50x speedup over CPU while staying within VRAM limits
+- **Batch-staged multi-paper pipeline** — when checking 2+ papers, GPU models load once per batch (vision/embedding/cited-vision) and vLLM/network stages run concurrently, giving a meaningful speedup over sequential per-paper runs. Tune via `--concurrency` (default 2, validated up to 4 on a single consumer GPU)
+- **Phased API resolution** — citations flow through OpenAlex → Semantic Scholar → CrossRef → Open Library/LoC, each phase only processing what previous phases didn't resolve
+- **8-source full-text cascade** — early exit on first successful download across arXiv, Semantic Scholar, OpenAlex, PubMed Central, Europe PMC, Unpaywall, bioRxiv, CORE
+- **Live monitoring** *(advanced)* — `sciwrite-lint containers monitor` shows service health, VRAM usage, and KV cache utilization in a terminal dashboard
+
+Full pipeline on a 50-reference paper: ~30 minutes initial (dominated by downloads and claim verification), minutes on cached reruns. On native Linux, embedding and vision default to CPU (tens of times slower) due to limited VRAM on consumer GPUs and no transparent paging of inactive vLLM container allocations; force GPU via config if VRAM permits.
+
+## Install
+
+**Assumed setup:** A workstation with an NVIDIA GPU (16+ GB VRAM). Developed and tested on Windows (WSL2). Native Linux is likely to work with GPU memory allocation tuning (see [docs/services.md](docs/services.md#embedding-device)). Not tested on macOS.
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/), a container runtime (podman or docker), CUDA drivers, and [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
+
+```bash
+uv tool install sciwrite-lint --python 3.13
+```
+
+uv downloads Python 3.13 automatically (does not affect any Python you may already have) and installs sciwrite-lint as a globally available command.
+
+## Setup
+
+```bash
+sciwrite-lint init                     # scaffold .sciwrite-lint.toml + references/ + local_pdfs/
+sciwrite-lint config set-email you@example.com  # required for Unpaywall + Retraction Watch
+sciwrite-lint containers start         # start GROBID + vLLM (needs GPU for vLLM)
+sciwrite-lint containers monitor       # live dashboard: service health, VRAM, KV cache
+```
+
+![Monitor dashboard](docs/monitor.png)
+
+`init` detects `.tex` files and their `.bib` references and generates a `.sciwrite-lint.toml` config. Review to confirm the right files were detected.
+
+**Paywalled references:** drop PDFs into `local_pdfs/` with filenames matching the reference title. The tool fuzzy-matches filenames against your `.bib` titles and uses local copies instead of downloading.
+
+**Optional API keys** increase rate limits for Semantic Scholar, NCBI, and CORE:
+
+```bash
+sciwrite-lint config show              # see what's configured
+sciwrite-lint config set-key semantic-scholar YOUR_KEY  # dedicated rate limit
+```
+
+See [docs/services.md](docs/services.md) for GPU requirements, all external APIs, and API key details.
+
+## Usage
+
+```bash
+sciwrite-lint check --paper my_paper            # full pipeline + SciLint Score
+sciwrite-lint check --paper my_paper --fresh    # same, ignoring all caches
+sciwrite-lint check                             # all papers (batch-staged when 2+, ~4-5x faster than sequential)
+sciwrite-lint check --concurrency 4             # batch parallelism (default 2, validated up to 4)
+sciwrite-lint check paper.tex                   # text + LLM rules on a .tex file
+sciwrite-lint check paper.pdf                   # check a PDF (GROBID required)
+sciwrite-lint contributions --paper my_paper    # add contribution axes to SciLint Score
+sciwrite-lint contributions paper.pdf           # standalone file scoring
+```
+
+`check` runs the full pipeline in one command: text checks → figure analysis → LLM consistency → reference verification via APIs → download and parse cited papers → claim verification → consistency checks on cited papers → bibliography verification → aggregate reliability scores → SciLint Score. An initial run on a 50-reference paper takes up to 30 minutes (dominated by downloads and claim verification); subsequent cached runs complete in minutes.
+
+Use `--fresh` to start from scratch (backs up the existing workspace before recreating it).
+
+### Contribution axes (`sciwrite-lint contributions`)
+
+`contributions` computes 5 contribution axes from philosophy of science (Popper, Lakatos, Kitcher, Laudan, Mayo) and updates the SciLint Score. Requires vLLM.
+
+```bash
+sciwrite-lint check --paper my_paper           # SciLint Score (contribution = 1.0)
+sciwrite-lint contributions --paper my_paper   # add 5 contribution axes, update score
+```
+
+### Individual stages
+
+For debugging or advanced workflows, each pipeline stage is also available as a standalone command:
+
+| Command | What it does |
+|---------|-------------|
+| `verify --paper NAME` | API verification only (CrossRef, OpenAlex, Semantic Scholar, Open Library, Library of Congress) |
+| `fetch --paper NAME` | Download full-text PDFs for verified references |
+| `parse --paper NAME` | Parse PDFs via GROBID and compute embeddings |
+| `verify-claims --paper NAME` | LLM reads cited sources, checks claim support |
+| `ref-health --paper NAME` | Fast reference health check: cite/bib mismatches, ID coverage, local PDF matches (no API calls) |
+| `contributions --paper NAME` | Add 5 contribution axes to SciLint Score (requires vLLM) |
+
+## Output
+
+Each finding has a severity level, a rule ID, and a message explaining the issue:
+
+- **error** — a concrete manuscript problem (hallucinated reference, unsupported claim, retracted source)
+- **warning** — needs human judgment (metadata mismatch, weak citation purpose, cross-section inconsistency)
+- **info** — the tool could not complete a check (LLM error, API timeout, internal crash) or informational note
+
+Findings also carry a `context` field with the reasoning behind the verdict: the LLM's explanation, which identifiers were searched, or which API provided the canonical data. This lets you distinguish "the tool found a problem" from "the tool couldn't check this."
+
+Example terminal output:
+
+```
+ ERROR  reference-exists        johnson2024: Not found in any API
+                                Searched with: title="Deep Learning for Climate", author="Johnson"
+
+ ERROR  claim-support           smith2023: Cited paper does not support this claim
+                                Claim: "transformers outperform RNNs by 15% on BLEU"
+                                Verdict: paper reports 8% improvement, not 15%
+
+ WARN   reference-accuracy      lee2022: Year mismatch (bib: 2022, canonical: 2021)
+                                Source: OpenAlex (DOI: 10.1234/example)
+
+ WARN   cross-section-consistency
+                                Abstract claims "three novel contributions" but
+                                Section 5 delivers two
+
+ WARN   reference-unreliable    chen2019: Low reliability (0.35)
+                                Metadata mismatch, 2 unsupported claims,
+                                23% hallucinated bibliography entries
+
+ INFO   caption-vs-content      Figure 3: could not extract figure from PDF
+
+  SciLint Score: 0.41
+    Internal Consistency:  0.85
+    Referencing Quality:   0.48
+  (Run 'sciwrite-lint contributions' to add contribution axes)
+```
+
+Output formats: terminal (default) or `--format json`.
+
+## Documentation
+
+- `sciwrite-lint checks` — list all checks
+- `sciwrite-lint <command> --help` — detailed usage for any command
+- [docs/services.md](docs/services.md) — GROBID, vLLM, external APIs, configuration
+
+For contributors and advanced users:
+
+- [docs/evals.md](docs/evals.md) — detection evaluation framework, adding test cases
+- [docs/calibration.md](docs/calibration.md) — SciLint Score calibration against ground-truth papers
+
+## License
+
+MIT