citefinder 0.3.0__tar.gz

citefinder-0.3.0/.claude/settings.local.json

@@ -0,0 +1,69 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(date:*)",
+      "Bash(diff:*)",
+      "Bash(du:*)",
+      "Bash(file:*)",
+      "Bash(find:*)",
+      "Bash(gh api:*)",
+      "Bash(gh issue:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr merge:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh repo:*)",
+      "Bash(git add:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git commit:*)",
+      "Bash(git config:*)",
+      "Bash(git diff:*)",
+      "Bash(git fetch:*)",
+      "Bash(git log:*)",
+      "Bash(git merge:*)",
+      "Bash(git mv:*)",
+      "Bash(git pull:*)",
+      "Bash(git remote:*)",
+      "Bash(git show:*)",
+      "Bash(git stash:*)",
+      "Bash(git status:*)",
+      "Bash(git switch:*)",
+      "Bash(git tag:*)",
+      "Bash(grep:*)",
+      "Bash(head:*)",
+      "Bash(jq:*)",
+      "Bash(ls:*)",
+      "Bash(sqlite3:*)",
+      "Bash(stanza:*)",
+      "Bash(test:*)",
+      "Bash(tree:*)",
+      "Bash(uv add:*)",
+      "Bash(uv build:*)",
+      "Bash(uv lock:*)",
+      "Bash(uv pip:*)",
+      "Bash(uv remove:*)",
+      "Bash(uv run python:*)",
+      "Bash(uv run:*)",
+      "Bash(uv sync:*)",
+      "Bash(wc:*)",
+      "Bash(which:*)",
+      "Bash(xxd:*)",
+      "Edit(.claude/**)"
+    ],
+    "deny": [
+      "Bash(git clean:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(rm -rf:*)"
+    ],
+    "ask": [
+      "Bash(git checkout .:*)",
+      "Bash(git push:*)",
+      "Bash(git rebase:*)",
+      "Bash(git restore:*)",
+      "Bash(rm:*)"
+    ]
+  }
+}

citefinder-0.3.0/.claude/skills/use-citefinder/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: use-citefinder
+description: Look up DOIs, search Crossref or OpenAlex, and resolve book chapters with `citefinder` — a small Crossref + OpenAlex client with a JSONL cache that survives sessions and remembers 404s. Use this whenever the user wants to verify a DOI, find a paper by author + title, check whether a citation is real, resolve a chapter DOI, look up an arXiv/preprint DOI Crossref doesn't index, or generate canonical metadata for a reference list — even when they don't say "Crossref" or "DOI" explicitly. Phrases like "is this paper real?", "find the published version", "look up this citation", "the subagent gave me these papers — verify them", or "what's the DOI for X?" should trigger it.
+---
+
+# Use citefinder
+
+`citefinder` (https://github.com/gitronald/citefinder) is a small Python library + CLI for Crossref **and OpenAlex** lookups, with a JSONL-backed cache. Use it instead of raw `curl https://api.crossref.org/...` because:
+
+- The cache survives sessions, so re-running verification is cheap.
+- 404s are cached, so known-missing DOIs don't get re-queried.
+- The cache is JSONL (one record per line) — `grep`-able, diffable, and crash-safe.
+- It exposes both a Python API (for batch work, scripts, notebooks) and a CLI (for ad-hoc lookups).
+
+## When to use this skill
+
+- Verifying that a DOI resolves to the paper the user expects (the most common need).
+- Finding the canonical / published DOI from an arxiv ID, SSRN URL, preprint title, or an `(Author Year)` inline citation.
+- Resolving a book chapter DOI when you only have the book's DOI and a chapter number.
+- Sanity-checking a list of references produced by a research subagent or extracted from a PDF.
+- Building or enriching a bibliography (`.bib`, CSV) from an outline.
+
+If the user describes a multi-step Zotero/bibliography workflow, also load the `resolve-zotero-references` skill — it composes citefinder with Zotero matching and a verification loop.
+
+## Install / availability check
+
+If citefinder isn't already a dependency:
+
+```bash
+uv add citefinder  # or: uv add git+https://github.com/gitronald/citefinder
+```
+
+Confirm it's wired:
+
+```bash
+uv run citefinder --help
+```
+
+## Three core operations
+
+### 1. Verify a single DOI
+
+```python
+from citefinder import CrossrefClient
+
+client = CrossrefClient(cache_path="~/.cache/citefinder/crossref.jsonl")
+work = client.lookup_doi("10.1126/science.aap9559")
+if work is None:
+    # 404 — the DOI doesn't resolve. May be fabricated, mistyped, or too new for Crossref's index.
+    ...
+else:
+    print(work["title"][0])
+```
+
+CLI:
+
+```bash
+citefinder doi 10.1126/science.aap9559
+```
+
+**Always compare the returned title to the title you expected.** This is the single most important habit. Subagents and PDF extractors regularly produce DOIs that are *off by a few characters* in the suffix (e.g., `psrm.2025.14` vs `psrm.2025.10063`) — those wrong suffixes often resolve to a real-but-different paper in the same journal. The DOI lookup itself returns 200; only a title comparison catches it.
+
+### 2. Search bibliographically
+
+When you don't have a DOI (or the DOI you have is suspect), search by free-form text:
+
+```python
+hits = client.search_bibliographic(
+    f"{first_author_last_name} {distinctive_title_words}",
+    rows=3,
+)
+for hit in hits:
+    print(hit["DOI"], "-", hit["title"][0])
+```
+
+CLI:
+
+```bash
+citefinder search "Wolfowicz hate speech meta-analysis" --rows 3
+```
+
+Tips for good queries:
+
+- First author's last name plus 2–4 distinctive title words is usually enough.
+- Avoid generic words ("study", "analysis", "the") — they dilute the relevance score.
+- For preprints, both an SSRN/arxiv DOI and a published DOI may come back. Prefer the published one unless the user wants the preprint.
+
+### 3. Look up a book chapter
+
+Many edited volumes follow the convention `{book_doi}.{NNN}` for chapter DOIs (e.g., `10.1017/9781108890960.005` for chapter 5).
+
+```python
+chapter = client.lookup_book_chapter("10.1017/9781108890960", 5)
+```
+
+CLI:
+
+```bash
+citefinder chapter 10.1017/9781108890960 5
+```
+
+`lookup_book_chapter` zero-pads numeric chapters to 3 digits. Pass a string instead (`client.lookup_book_chapter(book_doi, "ch1a")`) for publishers using a different format.
+
+## Key behaviors to know
+
+- **Cache path:** defaults to `~/.cache/citefinder/crossref.jsonl`. Use a project-local path (e.g., `data/crossref-cache.jsonl`) when you want results committed alongside an outline so collaborators don't re-query.
+- **Latest value wins on replay.** Re-querying after a fix transparently overwrites — no manual cache invalidation needed.
+- **`None` is a real cache value.** A cached `None` means "Crossref returned 404 for this DOI" — citefinder uses it to avoid re-hitting known-missing DOIs. If you suspect Crossref has now indexed a paper it didn't before, delete that line from the JSONL or use a fresh cache path.
+- **`lookup_doi` returns the `message` payload directly,** not the full Crossref envelope. So you access `work["title"][0]`, not `work["message"]["title"][0]`.
+- **`title` is a list, not a string.** Crossref returns titles as arrays. Use `work["title"][0]`.
+- **`search_bibliographic` returns the items list,** which may be empty. Always handle the empty case.
+
+## OpenAlex fallback for arXiv / preprint / thin-metadata DOIs
+
+Crossref doesn't index arXiv DOIs (`10.48550/arXiv.*`) and many repository deposits — those return 404 from `lookup_doi`. Crossref also frequently has thin metadata (missing abstract, abbreviated title, no affiliations) on records that exist. Use OpenAlex as the second source in those cases:
+
+```python
+from citefinder import CrossrefClient, OpenAlexClient, is_arxiv_doi
+
+crossref = CrossrefClient(cache_path="~/.cache/citefinder/crossref.jsonl")
+openalex = OpenAlexClient(
+    cache_path="~/.cache/citefinder/openalex.jsonl",
+    mailto="you@example.com",  # opts into OpenAlex's polite pool — faster, higher daily quota
+)
+
+doi = "10.48550/arXiv.2410.21554"
+if is_arxiv_doi(doi):
+    work = openalex.lookup_doi(doi)  # arXiv DOIs go straight to OpenAlex
+else:
+    work = crossref.lookup_doi(doi) or openalex.lookup_doi(doi)  # Crossref-first, OpenAlex fallback
+```
+
+CLI:
+
+```bash
+citefinder openalex doi 10.48550/arXiv.2410.21554
+citefinder openalex search "fact-checking large language models"
+```
+
+OpenAlex's schema differs from Crossref — different keys for the same data:
+
+| Crossref | OpenAlex |
+|---|---|
+| `work["title"][0]` (+ `subtitle[0]`) | `work["display_name"]` |
+| `work["author"][0]["family"]` | `work["authorships"][0]["author"]["display_name"]` |
+| `work["container-title"][0]` | `work["primary_location"]["source"]["display_name"]` |
+| `work["published-print"]["date-parts"][0][0]` | `work["publication_year"]` |
+
+OpenAlex stores abstracts as an `abstract_inverted_index` (`{word: [positions]}`), not a string. Use the helper:
+
+```python
+from citefinder import reconstruct_abstract
+abstract = reconstruct_abstract(work)  # returns plain string or None
+```
+
+### OpenAlex API key (optional, for higher rate limits)
+
+`OpenAlexClient` reads the API key in this order: explicit `api_key=...` arg → `OPENALEX_API_KEY` env var → (CLI only) `.env` in CWD or any parent. The key is sent as `Authorization: Bearer ...`, never in the URL or cache key.
+
+For ad-hoc lookups, no key is needed — common-pool requests work fine. If the user has a key set in their env or `.env`, the CLI picks it up automatically:
+
+```bash
+# .env in the project (gitignored)
+OPENALEX_API_KEY=oa_pk_...
+
+citefinder openalex doi 10.48550/arXiv.2410.21554  # uses key from .env automatically
+```
+
+For programmatic library use, `.env` is *not* auto-loaded — pass `api_key=...` explicitly or set the env var before constructing the client.
+
+### Picking `mailto`
+
+Use a project alias (e.g. the `authors` email in `pyproject.toml`) or omit entirely. Don't drop the user's personal email into `mailto` without asking — it's an outbound identifier, and a project/noreply address is the right default.
+
+## When citefinder isn't enough
+
+For **generating formatted BibTeX strings** from a DOI or query, use [`fetchbib`](https://github.com/mr-devs/fetchbib) (`fbib`) instead — it handles doi.org content negotiation, arXiv routing, and BibTeX-flavored config (protect titles, exclude ISSN, etc.). citefinder returns raw JSON for verification; fetchbib emits paste-ready BibTeX for citation lists.
+
+Drop down to raw HTTP (`requests.get("https://api.crossref.org/...")`) only if you need:
+
+- Crossref or OpenAlex endpoints citefinder doesn't wrap (Crossref `/funders`, `/journals`, `/types`; OpenAlex `/authors`, `/institutions`, `/sources`).
+- A one-off query you specifically don't want cached.
+- Streaming through large result sets via `cursor` pagination.
+
+For everything else, prefer citefinder so the cache stays the single source of truth across sessions.

citefinder-0.3.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly

citefinder-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Summary
+<!-- What does this PR do and why? -->
+
+## Test plan
+<!-- How was this tested? -->

citefinder-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

citefinder-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: Tests
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.1.0
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-groups --python ${{ matrix.python-version }}
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyrefly check
+      - run: uv run pytest --cov --cov-report=term-missing

citefinder-0.3.0/.gitignore

@@ -0,0 +1,9 @@
+.archive/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+
+.DS_Store
+
+!.claude/settings.local.json

citefinder-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.5
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]
+  - repo: local
+    hooks:
+      - id: pyrefly-check
+        name: pyrefly check
+        entry: uv run pyrefly check
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
+        require_serial: true

citefinder-0.3.0/.python-version

@@ -0,0 +1 @@
+3.14

citefinder-0.3.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security

citefinder-0.3.0/CLAUDE.md

@@ -0,0 +1,28 @@
+# Claude Settings
+
+This file provides guidance to [Claude Code](claude.ai/code).
+
+## Package Structure
+
+```
+citefinder/
+├── cli.py              # Typer CLI entry point
+└── __init__.py
+```
+
+## Development
+
+- Install: `uv sync --all-groups`
+- Tests: `uv run pytest`
+- Linting: pre-commit hooks run ruff format + lint on commit
+- Type checking: pre-commit hooks run pyrefly on commit
+- CI: GitHub Actions runs lint + type check + test matrix (Python 3.11–3.14) on push/PR to dev/main
+
+## Release Automation
+
+Use [stanza](https://github.com/gitronald/stanza) for release workflows:
+
+```bash
+stanza release [patch|minor|major|prerelease]
+stanza init
+```

citefinder-0.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ronald E. Robertson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

citefinder-0.3.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: citefinder
+Version: 0.3.0
+Project-URL: repository, https://github.com/gitronald/citefinder
+Author-email: gitronald <gitronald@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: requests>=2.33.1
+Requires-Dist: typer>=0.25.0
+Description-Content-Type: text/markdown
+
+# citefinder
+
+OpenAlex (default) + Crossref reference lookups with local JSONL caching.
+
+A small Python library + CLI for verifying academic references against the
+OpenAlex and Crossref APIs. Every lookup is appended to an append-only JSONL
+log so repeated queries (across verification passes or sessions) are served
+from the cache. Negative results (404s) are cached too, so known-missing DOIs
+aren't re-hit.
+
+OpenAlex is the default source: it merges Crossref + Unpaywall + ORCID + ROR
++ repository sources, so it covers what Crossref alone is missing — arXiv
+DOIs (`10.48550/arXiv.*`), other preprints, repository deposits — and
+frequently has richer metadata (abstracts, full author lists, affiliations)
+for records that exist in both. Crossref is still available via the
+`crossref` subcommand for its own workflows (book-chapter lookup, the
+canonical published-deposit metadata).
+
+### OpenAlex API key (optional)
+
+OpenAlex works without authentication, but a free API key gives you higher
+limits and tier-specific endpoints.
+
+- Docs: https://developers.openalex.org/
+- Sign up / generate a key: https://openalex.org/login?redirect=/settings/api-key
+
+The key is read in this order:
+
+1. `api_key=...` argument to `OpenAlexClient(...)` (or `--api-key` on the CLI).
+2. `OPENALEX_API_KEY` environment variable.
+3. A `.env` file in the current working directory or any parent (loaded by
+   the CLI; library users can opt in via `from dotenv import load_dotenv`).
+
+```bash
+# .env
+OPENALEX_API_KEY=oa_pk_...
+```
+
+The key is sent as `Authorization: Bearer ...`, never as a URL parameter, so
+it doesn't land in cache keys, logs, or referer headers.
+
+
+## Install
+
+```bash
+uv add citefinder
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/gitronald/citefinder
+cd citefinder
+uv sync
+```
+
+## Library usage
+
+### OpenAlex (default)
+
+```python
+from citefinder import OpenAlexClient, is_arxiv_doi, reconstruct_abstract
+
+openalex = OpenAlexClient(
+    cache_path="~/.cache/citefinder/openalex.jsonl",
+    mailto="you@example.com",  # opts into OpenAlex's polite pool — faster, higher quota
+)
+
+# Single DOI (works for arXiv DOIs that Crossref doesn't index)
+work = openalex.lookup_doi("10.48550/arXiv.2410.21554")
+
+# Title-only search — tuned for citation verification. Handles OpenAlex's
+# curly-apostrophe quirk and strips filter-reserved punctuation that would
+# 400 the request, so straight ASCII inputs match curly-quoted indexed titles.
+hits = openalex.search_title("Backstabber's Knife Collection", rows=3)
+
+# Free-text search across titles + abstracts (noisier; prefer search_title
+# for citation lookup)
+hits = openalex.search("fact-checking large language models", rows=3)
+
+# OpenAlex stores abstracts as an inverted index — reconstruct to plain text
+abstract = reconstruct_abstract(work) if work else None
+
+# Helper for routing logic
+assert is_arxiv_doi("10.48550/arXiv.2410.21554")
+```
+
+The `mailto` argument is optional but recommended: it puts requests into
+OpenAlex's [polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool)
+for faster responses. The cache key strips `mailto` so changing it doesn't
+invalidate prior entries.
+
+### Crossref
+
+```python
+from citefinder import CrossrefClient
+
+client = CrossrefClient(
+    cache_path="~/.cache/citefinder/crossref.jsonl",
+    mailto="you@example.com",  # opts into Crossref's polite pool — faster, higher quota
+)
+
+# Single DOI
+work = client.lookup_doi("10.1126/science.aap9559")
+print(work["title"][0])
+
+# Bibliographic search (author + title + year)
+hits = client.search_bibliographic("Wolfowicz hate speech meta-analysis", rows=3)
+
+# Book chapter via {book_doi}.{NNN} pattern
+chapter = client.lookup_book_chapter("10.1017/9781108890960", 5)
+```
+
+Crossref and OpenAlex both honor `mailto` for their polite pools; the cache
+key strips it on either side, so rotating the email doesn't invalidate prior
+entries.
+
+OpenAlex's schema differs from Crossref. Quick map:
+
+| Field | Crossref | OpenAlex |
+|---|---|---|
+| Title | `work["title"][0]` (+ optional `subtitle[0]`) | `work["display_name"]` |
+| First author | `work["author"][0]["family"]` (surname only) | `work["authorships"][0]["author"]["display_name"]` (**full name** — parse for surname) |
+| Container | `work["container-title"][0]` (+ `short-container-title`) | `work["primary_location"]["source"]["display_name"]` (+ `host_venue` on older records) |
+| Year | `published-print` / `published-online` / `issued` / `created` → `["date-parts"][0][0]` | `work["publication_year"]` (int) |
+
+## CLI usage
+
+```bash
+# OpenAlex (default)
+citefinder doi 10.48550/arXiv.2410.21554 --mailto you@example.com
+citefinder search "Backstabber's Knife Collection" --rows 3
+
+# Crossref
+citefinder crossref doi 10.1126/science.aap9559 --mailto you@example.com
+citefinder crossref search "Wolfowicz hate speech meta-analysis" --rows 3
+citefinder crossref chapter 10.1017/9781108890960 5
+```
+
+### CLI arguments
+
+- `--cache PATH` — JSONL cache path. Defaults to
+  `~/.cache/citefinder/openalex.jsonl` for top-level commands and
+  `~/.cache/citefinder/crossref.jsonl` for `crossref` subcommands. Separate
+  files so sources don't mix; override per command if you want
+  per-project caches (e.g., `--cache ./data/refs.jsonl`).
+- `--rows N` *(search only)* — Number of results to return. Default `3`.
+- `--mailto EMAIL` — Opts the request into the source's polite pool (both
+  OpenAlex and Crossref honor it): faster responses and a higher quota.
+  Sent as a `?mailto=…` query param; stripped from the cache key, so
+  rotating the email doesn't invalidate prior entries.
+- `--api-key KEY` *(OpenAlex only)* — OpenAlex API key for higher
+  rate limits and tier-specific endpoints. Also read from `OPENALEX_API_KEY`
+  in the env or a `.env` file (loaded from cwd or any parent). Sent as
+  `Authorization: Bearer <key>` so it never lands in cache keys, URL logs,
+  or referer headers.
+
+## Why JSONL?
+
+The cache is an append-only log: every lookup is one JSON object per line.
+Benefits:
+
+- **Auditable**: `cat`/`grep` to see every query that ever ran.
+- **Diffable**: plays nicely with git if you want to commit a project's cache.
+- **Crash-safe**: an interrupted write loses at most the last line.
+- **Recoverable**: rebuild the in-memory dict by replaying the log.
+
+Latest value wins on replay, so over-writes are a no-op semantic.
+
+**SQLite alternative.** A SQLite-backed cache is another reasonable
+implementation — it would trade the audit log and `grep`-ability for faster
+random access on very large caches (millions of entries) and concurrent
+writers. The current scale of citefinder use (per-project bibs, tens of
+thousands of entries at most) doesn't need it, and replaying a JSONL on
+startup is fast enough that the simplicity wins. If a future workload pushes
+past those limits, swapping the storage layer is a single class — `JsonlCache`
+in `citefinder/cache.py` — behind the same `get` / `put` / `__contains__`
+interface.
+
+## Tests
+
+```bash
+uv run pytest
+```