fh-library 0.2.11 → 0.2.13

package/CHANGELOG.md

@@ -1,7 +1,15 @@
 # FH Library — Change Log
 
+### v0.2.12 — 2026-11-08
+
+* **`library_pubmed_search_articles(query, max_results?, sort?, years?)`:** a PubMed search in PubMed's own syntax — esearch for the total and the IDs, one esummary for the rows (PMID, title, first author, year, journal, publication types, PMCID, library level), cached under `search/`. With the batch fetch and `library_read` this covers what the AI4L models used of the PubMed MCP server (#27).
+* **`FH_LIBRARY_SEARCH_CACHE_DAYS` (7):** days a PubMed or registry search is cached; was a constant.
+* **An ID no service knows is remembered** for `FH_LIBRARY_RETRY_AFTER_DAYS` (1): a PMID PubMed has no record for, a DOI neither Crossref nor doi.org resolves, a set ID without a label, an NCT ID without a study. A marker (`<entry>-missing.md`, date and reason, no meta) in the entry's directory; `library_add`, `library_status`, `library_read`, `library_verify` and the batch tool answer from it ("pmid not found (checked 2026-11-08; asked again after 1 day)"), the service is asked again after the cooldown, a real entry replaces the marker. Network errors are never remembered. The same cooldown a failed page or a transient tier failure already had.
+* **`library_pubmed_fetch_articles(pmids)`:** title, first author, year, publication types, retracted and level for up to 200 PMIDs in one call, rows in `columns` order (~120 characters a paper against the PubMed MCP server's ~2,500). Stored PMIDs from disk; the rest in one efetch, stored at abstract level as `library_add`'s first stage, so the cascade runs later as on an untried entry. The first of the PubMed tools (#27); `library_info`'s `cache` and `.servers/` count `pubmed` hits and misses per PMID.
+
 ### v0.2.9 — 2026-11-08
 
+* TUI v82: the `url` row shows library_fetch hits and misses from the servers' counters; `/status` carries `fetches`. Counts right-aligned in a 5-character column.
 * TUI v80: a `search` row — cached registry searches, hits and misses from the servers' counters; the decision-model row is labelled `decider`; `/status` carries `searches`.
 * ClinicalTrials tool descriptions and server instructions one statement each.
 

package/README.md

@@ -1,4 +1,4 @@
-![Version 0.1.3](https://img.shields.io/badge/Version-0.2.11-green.svg)
+![Version 0.1.3](https://img.shields.io/badge/Version-0.2.13-green.svg)
 ![License MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 [![Forever Healthy](https://img.shields.io/badge/(c)_2026-Forever_Healthy-573D7D.svg)](https://forever-healthy.org)
 [![npm](https://img.shields.io/badge/npm-fh--library-cb3837.svg)](https://www.npmjs.com/package/fh-library)
@@ -23,6 +23,8 @@ A [Model Context Protocol](https://modelcontextprotocol.io) server that builds a
 * `library_info(ids?)` → the whole library, everything the TUI shows: the library directory and host, the decision model with its endpoint and whether it answers right now (`verify`), this server's cache hits and misses since it started (`cache`), the entries and their size on disk (`size`), per entry type (`types`: pmid, doi, dailymed, nct) the entries with their levels — `full_text`, `abstract`, `title` — and retractions; entry counts by type and level, counts of retracted and not-citable entries and of entries with errata, expressions of concern and updates, the configured tiers, library directory and host; `ids: true` also lists every entry ID
 * `library_verify(claim, id)` → is one finding of a review stated by one paper it cites? `claim` is the finding alone, verbatim, without its citations; `id` one paper (`pmid:`, or any `doi:`), drug label or trial record the review cites for it — a finding cited to three papers is three calls with the same claim; a claim that names a source or carries citations is refused. The server reads the paper (full text, else abstract) and asks a decision model; nothing of the paper enters the model's context. `verdict` **pass** (`score` the probability), **fail** (the full text does not state it; or only the title is in the library — `reason` says so), **unverifiable** (only the abstract is in the library and does not state it — `reason`) or **error**; `basis` full_text, abstract or title. See "Verifying claims" below.
 * `library_read(id, section?, query?, max_chars?, max_hits?)` → one small piece of a stored paper's Markdown, never the whole paper: without `section`/`query` the **outline** (headings with word counts, and whether the full text or only the abstract is stored; a heading the paper uses several times is listed as `Participants [3/12]`); `section` → that section's **own text** (heading matched as case-insensitive substring, capped at `max_chars`, default 6000, with `returned_words` against `words` when cut) and, for a parent heading, its `subsections` with word counts to pick from — a duplicated heading named bare lists the candidates instead; `query` — two or three distinctive terms the paper itself would use (a measure and a unit, an outcome and a group, a compound name), not the claim — → **passages** holding every term, each a window of at most 1000 chars around the matches (`clipped: true` when cut; a table row with its header row), with its section, best first (at most `max_hits`, default 5); matching forgives case, accents, hyphens, Markdown markup, plural and -ed/-ing forms; when no passage holds every term the best **partial** matches come back (`partial: true`, the `matched` terms per passage, the rare term first), and `missing_terms` names the terms the text never uses in any form — those are the ones to rephrase. `section` and `query` together search inside that section. `section: "Abstract"` on a full text without one answers from the stored abstract. Every full text converted from JATS XML (PMC, Europe PMC, Elsevier) has a **Declarations** section — funding, conflicts of interest, author notes, gathered from wherever the XML keeps them — and on a text without one `section: "Declarations"` assembles the sections headed funding, conflicts, acknowledgements, ethics, contributions, so it answers who paid and who declares what on every source alike; a paper with neither states nothing. Outline first, then pick. A paper not in the library is added first, as `library_add` would (its lines in the log), then library_read; the answer carries `added: true`. Reads may run in parallel.
+* `library_pubmed_search_articles(query, max_results?, sort?, years?)` → a PubMed search in PubMed's own syntax (see "PubMed in batches"): the total and rows in `columns` order, with the library level of a paper already stored, cached for `FH_LIBRARY_SEARCH_CACHE_DAYS`
+* `library_pubmed_fetch_articles(pmids)` → title, first author, year, publication types, retracted and level for up to 200 PMIDs in one call (see "PubMed in batches"); PMIDs the library lacks are fetched in one PubMed request and stored at abstract level
 * `library_clinicaltrials_search_studies(query | intervention | condition, status?, sort?, max_results?)` → a ClinicalTrials.gov search (see "Trial search"): the total count and compact rows, cached for a week
 * `library_clinicaltrials_get_study_record(nct)` → one trial as a review needs it (title, status, phase, design, enrollment, dates, sponsor, conditions, interventions, primary outcomes, eligibility, sites, result publications, has_results, brief summary), from the stored record
 * `library_clinicaltrials_get_study_results(nct, max_chars?)` → a trial's posted results as Markdown, capped, with the outcome measure titles for `library_read`
@@ -58,7 +60,7 @@ Downloads are plain HTTP with a desktop Chrome User-Agent (API calls identify th
 
 * **Which tiers run, in which order:** `FH_LIBRARY_TIERS=pmc,tdm,unpaywall,openalex` — exactly these, in this order; a tier not listed is off. Unset, every tier runs in the order of the table above, the proxy last.
 * **Keys:** `FH_LIBRARY_ELSEVIER_API_KEY` and `FH_LIBRARY_WILEY_TDM_TOKEN` for `tdm`, `FH_LIBRARY_CORE_API_KEY` for `core`, `FH_LIBRARY_NCBI_API_KEY` (10 instead of 3 requests/s), `FH_LIBRARY_BRIGHTDATA_API_TOKEN` and `FH_LIBRARY_BRIGHTDATA_ZONE` for the unlocker. `FH_LIBRARY_CONTACT_EMAIL` is the one address sent to every service (NCBI `tool`/`email`, Unpaywall and OpenAlex polite pools, Crossref, the User-Agent).
-* **Retries:** `FH_LIBRARY_RETRY_AFTER_DAYS` (default 1) is the cooldown before a transient tier failure is retried; `FH_LIBRARY_REFRESH_AFTER_DAYS` (30) the age of an entry's PubMed record after which `library_add` re-reads it for new correction notices and retractions. A tdm link behind a token that is not configured is recorded as `needs elsevier token` and not re-checked; after adding the token, remove those attempts from the entries to give them a go. `FH_LIBRARY_RETRY_BLOCKED` (false) decides whether a browser challenge that did not clear, or a Bright Data refusal, is final: with the same method tomorrow ends the same way, so set it true only after a change of method (a new browser rung, a new service).
+* **Retries:** `FH_LIBRARY_RETRY_AFTER_DAYS` (default 1) is the cooldown before a transient tier failure is retried, before a page `library_fetch` could not get is fetched again, and before an ID no service knew (a PMID, DOI, set ID or NCT ID that is not found) is asked for again — meanwhile every tool answers "not found" from a marker in the entry's directory, with the date it was checked; `FH_LIBRARY_SEARCH_CACHE_DAYS` (7) how long a PubMed or registry search is answered from disk; `FH_LIBRARY_REFRESH_AFTER_DAYS` (30) the age of an entry's PubMed record after which `library_add` re-reads it for new correction notices and retractions. A tdm link behind a token that is not configured is recorded as `needs elsevier token` and not re-checked; after adding the token, remove those attempts from the entries to give them a go. `FH_LIBRARY_RETRY_BLOCKED` (false) decides whether a browser challenge that did not clear, or a Bright Data refusal, is final: with the same method tomorrow ends the same way, so set it true only after a change of method (a new browser rung, a new service).
 * **Browsers and verify:** `FH_LIBRARY_PLAYWRIGHT_n` and `FH_LIBRARY_CHROME_n` (hostnames; above) and `FH_LIBRARY_PLAYWRIGHT_HEADLESS`; `FH_LIBRARY_VERIFY_*` ("Verifying claims"). A Playwright server must run the **same `playwright-core` version** as the package — `library_info` shows the required one as `download.playwright.version`, `browser/Dockerfile` builds a server at it, and a server of another version is refused by Playwright itself (the log then carries the alert `!! browser <host>: Playwright version mismatch — server … must run playwright-core <version>`). Moving the version is one release: the pin in `package.json`, the tag in `browser/Dockerfile`, every server rebuilt. The library never launches a browser itself: every rung is a browser somebody runs.
 
 `library_info` reports the tiers in run order and, per variable, whether its value came from the environment, `.env` or the default — never the value.
@@ -147,7 +149,9 @@ PubMed's book records — National Academies reports, NTP monographs, StatPearls
 
 **Clinical trial records.** `library_add("nct:05173896")` stores the current record of one trial from [ClinicalTrials.gov](https://clinicaltrials.gov/): the ID is the eight digits of the NCT number in the review's link (`…/study/NCT05173896`); `nct:NCT05173896` and a bare `NCT05173896` are accepted and read the same. The API's JSON is converted to Markdown, one section per module: identification with secondary IDs such as EudraCT, status with every date and its actual/estimated type, sponsor and collaborators, description, conditions, design (phase, allocation, masking, enrollment with its type), arms and interventions with doses, primary and secondary outcomes with time frames, eligibility, locations as a country list, references; and, when results are posted, the participant flow, baseline characteristics, every outcome measure with its group values and analyses, and the adverse events, all as tables. Values are written in plain words, "Phase 2", "Active, not recruiting", "100 (estimated)", so a figure the review states can be found as stated. The status carries `nctid`, `publications` (the results publications the record lists, as `pmid:…`, so whether a trial has been published is one status away), the brief title, the lead sponsor as `first_author`, the first-posted year as `year`, the last-update-posted date as `version`, and `publication_types` `["Trial Registration"]`. `library_read` and `library_verify` work on a record as on a paper. An entry older than `FH_LIBRARY_REFRESH_AFTER_DAYS` is re-fetched and rewritten when the record was updated since; a status the review states that has moved on then fails, which is right. Entries live under `nct/<digits 1–2>/<digits 1–4>/<digits>/` with the JSON and the Markdown as `nct-<digits>-fulltext.json` and `-fulltext.md`; the log line reads `library_add nct:05173896 ctgov fetched level=full_text updated 2024-12-09 active, not recruiting ETLAS2`.
 
-**Trial search.** `library_clinicaltrials_search_studies(query?, intervention?, condition?, status?, sort?, max_results?)` asks the ClinicalTrials.gov API (v2, no key) what a review needs from the registry: the trials of an intervention, the ongoing ones (`status: "ongoing"` is recruiting, not yet recruiting, active not recruiting, enrolling by invitation), a free-text or condition search, sorted by relevance, newest, largest or completion date, up to 100 rows. The rows are arrays in the order of `columns` — the field names once, not per row — shaped for the review's Emerging Research item (what AI4L's prompt asks about an ongoing trial; the link is `https://clinicaltrials.gov/study/<NCT ID>`): NCT ID, title, status with why a trial stopped, phase, enrollment as "100 (estimated)", start and primary completion dates (whether "ongoing" still holds), the primary outcome with its time frame, conditions, interventions, `has_results`; the full detail of one row is `library_clinicaltrials_get_study_record`; `total` is the registry's count, for a "no trials found" statement. The same search is answered from `search/<2>/<4>/<key>.json` for 7 days — a registry listing a week old is current enough for a review, and an audit that runs again reads from disk. Two thin tools answer from the stored record of any row (added first when missing): `library_clinicaltrials_get_study_record(nct)` is the review's detail of one trial — official title, design, enrollment, dates, eligibility, sites, result publications as `pmid:` IDs, the brief summary — and `library_clinicaltrials_get_study_results(nct, max_chars?)` is the posted results part of the stored Markdown (participant flow, baseline, outcome measures, adverse events), with the outcome titles listed so `library_read("nct:…", section)` can return one measure whole. Together with the search they cover what the AI4L models asked the ClinicalTrials.gov MCP server for.
+**PubMed in batches.** `library_pubmed_fetch_articles(pmids)` answers what an auditor asks of a list of PubMed IDs — does each resolve, what is its title, year and type, is it retracted, does the library hold its full text — as rows in `columns` order, about 120 characters per paper. A PMID already in the library is read from disk. The others go to PubMed in one efetch request (up to 200), and each record is stored exactly as `library_add` stores its first stage: the XML, the abstract Markdown, the meta with its correction and retraction notices, no retrieval attempts yet — so a later `library_add` or `library_read` runs the full-text cascade as on an untried entry, and the library fills at abstract level in batches instead of one paper at a time. An entry is checked again right before writing, so a concurrent `library_add` that already stored a full text is never overwritten. Level `not found` marks a PMID PubMed does not know, `invalid` a value that is not a PMID. `library_pubmed_search_articles(query, max_results?, sort?, years?)` is the search: the query goes to PubMed as written, field tags and all; esearch gives the total and the IDs, one esummary the rows — PMID, title, first author, year, journal, publication types (Journal Article left out), PMCID when a free full text exists, and the library's level when the paper is already stored, so the model knows what `library_read` can answer at once. Cached under `search/` like the trial search.
+
+**Trial search.** `library_clinicaltrials_search_studies(query?, intervention?, condition?, status?, sort?, max_results?)` asks the ClinicalTrials.gov API (v2, no key) what a review needs from the registry: the trials of an intervention, the ongoing ones (`status: "ongoing"` is recruiting, not yet recruiting, active not recruiting, enrolling by invitation), a free-text or condition search, sorted by relevance, newest, largest or completion date, up to 100 rows. The rows are arrays in the order of `columns` — the field names once, not per row — shaped for the review's Emerging Research item (what AI4L's prompt asks about an ongoing trial; the link is `https://clinicaltrials.gov/study/<NCT ID>`): NCT ID, title, status with why a trial stopped, phase, enrollment as "100 (estimated)", start and primary completion dates (whether "ongoing" still holds), the primary outcome with its time frame, conditions, interventions, `has_results`; the full detail of one row is `library_clinicaltrials_get_study_record`; `total` is the registry's count, for a "no trials found" statement. The same search is answered from `search/<2>/<4>/<key>.json` for `FH_LIBRARY_SEARCH_CACHE_DAYS` (7) — a registry listing a week old is current enough for a review, and an audit that runs again reads from disk. Two thin tools answer from the stored record of any row (added first when missing): `library_clinicaltrials_get_study_record(nct)` is the review's detail of one trial — official title, design, enrollment, dates, eligibility, sites, result publications as `pmid:` IDs, the brief summary — and `library_clinicaltrials_get_study_results(nct, max_chars?)` is the posted results part of the stored Markdown (participant flow, baseline, outcome measures, adverse events), with the outcome titles listed so `library_read("nct:…", section)` can return one measure whole. Together with the search they cover what the AI4L models asked the ClinicalTrials.gov MCP server for.
 
 **Web pages.** `library_fetch(url, max_length?, start_index?, raw?)` is the standard MCP [fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) tool, served from the library, for every link a review carries that is not a paper, label or trial record: a guideline, a product page, a news item. Its description tells the model to prefer it over a plain fetch or a browser tool, and says why: a page anyone fetched in the last 30 days comes from disk in milliseconds, and a page a plain fetch cannot get climbs the ladder in the same call. The answer is what `fetch` returns, so a model keeps its habits: `Contents of <url>:` and the page as Markdown with the page's title as the first heading, cut at `max_length` (default 5000) with the note `Content truncated. Call the fetch tool with a start_index of N to get more content`; `raw` gives the HTML; a `text/markdown` body comes back as is, any other non-HTML body with the `Content type … cannot be simplified to markdown` prefix; a failure is `Failed to fetch <url> - status code 404` or `Failed to fetch <url>: <reason>`. Two things happen underneath. The page is fetched up the same ladder as a paper — the plain fetch, then the browser rungs on a 403, 429 or bot wall, then Bright Data — so a page a plain fetch cannot reach is still read. And it is stored: `url/<2>/<4>/<16 hex of the URL's SHA-1>/url-<hash>-{meta.md, page.md, page.html|pdf|txt}`, the URL normalised first (host lowercased, fragment and tracking parameters dropped). The same URL within `FH_LIBRARY_REFRESH_AFTER_DAYS` (30) is served from disk, a failed fetch is not repeated within `FH_LIBRARY_RETRY_AFTER_DAYS` (1) — an audit that runs twice over one review reads its links once. A PDF comes back as Markdown (`fetch` would return its bytes as text). `title_only` returns `Contents of <url>:` and the title line alone — the page is still fetched and stored in full — so a link check costs a few tokens instead of a page. The log says which — `fetch example.com/… cached html … https://example.com/drugs/x` or `fetched 02.3s html retrieved_by=browser hetzner … <url>` (the ID column holds the URL without scheme, cut to a PubMed ID's width; the full URL ends the line); `library_info` counts the pages under `url`, a failed fetch as level `title`.
 

package/dist/index.js

@@ -1725,6 +1725,7 @@ var VARIABLES = [
   "FH_LIBRARY_RETRY_AFTER_DAYS",
   "FH_LIBRARY_RETRY_BLOCKED",
   "FH_LIBRARY_REFRESH_AFTER_DAYS",
+  "FH_LIBRARY_SEARCH_CACHE_DAYS",
   "FH_LIBRARY_NCBI_API_KEY",
   "FH_LIBRARY_BRIGHTDATA_API_TOKEN",
   "FH_LIBRARY_BRIGHTDATA_ZONE"
@@ -1734,7 +1735,8 @@ function settings(env = process.env) {
   return {
     retry_after_days: num("FH_LIBRARY_RETRY_AFTER_DAYS", 1, env),
     retry_blocked: bool("FH_LIBRARY_RETRY_BLOCKED", false, env),
-    refresh_after_days: num("FH_LIBRARY_REFRESH_AFTER_DAYS", 30, env)
+    refresh_after_days: num("FH_LIBRARY_REFRESH_AFTER_DAYS", 30, env),
+    search_cache_days: num("FH_LIBRARY_SEARCH_CACHE_DAYS", 7, env)
   };
 }
 function proxyHeaders(spec) {
@@ -1809,11 +1811,11 @@ function log(tool, id, message) {
 }
 
 // src/stats.ts
-import { mkdirSync as mkdirSync4, readdirSync as readdirSync3, readFileSync as readFileSync5, statSync as statSync2, unlinkSync as unlinkSync2 } from "fs";
+import { mkdirSync as mkdirSync4, readdirSync as readdirSync3, readFileSync as readFileSync5, statSync as statSync2, unlinkSync as unlinkSync3 } from "fs";
 import { join as join7 } from "path";
 
 // src/entry.ts
-import { copyFileSync, existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, writeFileSync } from "fs";
+import { copyFileSync, existsSync as existsSync5, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, unlinkSync as unlinkSync2, writeFileSync } from "fs";
 import { join as join6 } from "path";
 import { basename, dirname } from "path";
 
@@ -2017,11 +2019,11 @@ function inline(nodes) {
   return out;
 }
 function table(n) {
-  const row2 = (x) => kids2(x).filter((c) => ["td", "th"].includes(tagOf2(c))).map((c) => squash2(inline(kids2(c))).replace(/\|/g, "\\|"));
+  const row3 = (x) => kids2(x).filter((c) => ["td", "th"].includes(tagOf2(c))).map((c) => squash2(inline(kids2(c))).replace(/\|/g, "\\|"));
   const collect = (nodes, into) => {
     for (const x of nodes) {
       if ("#text" in x) continue;
-      if (tagOf2(x) === "tr") into.push(row2(x));
+      if (tagOf2(x) === "tr") into.push(row3(x));
       else if (!["thead", "tfoot"].includes(tagOf2(x))) collect(kids2(x), into);
     }
   };
@@ -2030,7 +2032,7 @@ function table(n) {
     const t = tagOf2(x);
     if (t === "thead") collect(kids2(x), head);
     else if (t === "tfoot") collect(kids2(x), foot);
-    else if (t === "tr") body.push(row2(x));
+    else if (t === "tr") body.push(row3(x));
     else if (!("#text" in x) && t !== "caption") collect(kids2(x), body);
   }
   const rows = [...head, ...body];
@@ -2636,6 +2638,10 @@ function writeAtomic(file2, data) {
 }
 function writeMeta(p, m) {
   writeAtomic(p.meta, renderMeta(m));
+  try {
+    unlinkSync2(join6(p.entryDir, `${p.entry}-missing.md`));
+  } catch {
+  }
 }
 function copyEntry(from, to) {
   const tmp = `${to.entryDir}.${process.pid}.tmp`, old = `${to.entryDir}.${process.pid}.old`;
@@ -2917,14 +2923,14 @@ var STALE_MS = 20 * 6e4;
 var stats = null;
 var file = null;
 function startStats(pkg2, libraryDir = FH_LIBRARY_DIR) {
-  stats = { host: HOST, pid: process.pid, package: pkg2.name, version: pkg2.version, started: (/* @__PURE__ */ new Date()).toISOString(), verify: { hits: 0, misses: 0 }, fetch: { hits: 0, misses: 0 }, search: { hits: 0, misses: 0 } };
+  stats = { host: HOST, pid: process.pid, package: pkg2.name, version: pkg2.version, started: (/* @__PURE__ */ new Date()).toISOString(), verify: { hits: 0, misses: 0 }, fetch: { hits: 0, misses: 0 }, search: { hits: 0, misses: 0 }, pubmed: { hits: 0, misses: 0 } };
   file = join7(libraryDir, ".servers", `${HOST}-${process.pid}.json`);
   sweep(join7(libraryDir, ".servers"));
   publish();
   setInterval(publish, HEARTBEAT_MS).unref();
   const stop = () => {
     try {
-      if (file) unlinkSync2(file);
+      if (file) unlinkSync3(file);
     } catch {
     }
   };
@@ -2945,7 +2951,7 @@ function sweep(dir, staleMs = STALE_MS) {
     const p = join7(dir, name);
     try {
       if (Date.now() - statSync2(p).mtimeMs > staleMs) {
-        unlinkSync2(p);
+        unlinkSync3(p);
         n++;
       }
     } catch {
@@ -2953,9 +2959,9 @@ function sweep(dir, staleMs = STALE_MS) {
   }
   return n;
 }
-function bump(kind, hit) {
+function bump(kind, hit, n = 1) {
   if (!stats) return;
-  stats[kind][hit ? "hits" : "misses"]++;
+  stats[kind][hit ? "hits" : "misses"] += n;
   publish();
 }
 var currentStats = () => stats;
@@ -2969,7 +2975,7 @@ function publish() {
 }
 
 // src/tools.ts
-import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync13 } from "fs";
 import { z } from "zod";
 
 // src/cascade.ts
@@ -3999,7 +4005,7 @@ async function verifyCached(claim, id, cfg, decide, libraryDir = FH_LIBRARY_DIR,
 var DROP = /* @__PURE__ */ new Set(["entry_dir", "library_dir", "files"]);
 var compact2 = (o) => JSON.stringify(o);
 function lean(o) {
-  if (Array.isArray(o)) return o.map((row2) => row2 && typeof row2 === "object" && !Array.isArray(row2) ? leanObject(row2) : row2);
+  if (Array.isArray(o)) return o.map((row3) => row3 && typeof row3 === "object" && !Array.isArray(row3) ? leanObject(row3) : row3);
   if (o && typeof o === "object") return leanObject(o);
   return o;
 }
@@ -4017,7 +4023,7 @@ var leanJson = (o) => compact2(lean(o));
 import { createHash as createHash4 } from "crypto";
 import { existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync10 } from "fs";
 import { dirname as dirname4, join as join11 } from "path";
-var SEARCH_AFTER_DAYS = 7;
+var searchCacheDays = () => settings().search_cache_days;
 var API2 = "https://clinicaltrials.gov/api/v2/studies";
 var FIELDS = ["NCTId", "BriefTitle", "OverallStatus", "WhyStopped", "Phase", "StudyType", "EnrollmentCount", "EnrollmentType", "StartDate", "PrimaryCompletionDate", "CompletionDate", "LastUpdatePostDate", "PrimaryOutcomeMeasure", "PrimaryOutcomeTimeFrame", "Condition", "InterventionName", "LeadSponsorName", "HasResults"];
 var ONGOING = ["RECRUITING", "NOT_YET_RECRUITING", "ACTIVE_NOT_RECRUITING", "ENROLLING_BY_INVITATION"];
@@ -4109,7 +4115,7 @@ async function searchTrials(raw, libraryDir = FH_LIBRARY_DIR, fetchImpl = liveFe
   if (existsSync10(file2)) {
     try {
       const r = JSON.parse(readFileSync10(file2, "utf8"));
-      if (daysSince(r.searched) < SEARCH_AFTER_DAYS) return { ok: true, result: r, cached: true };
+      if (daysSince(r.searched) < searchCacheDays()) return { ok: true, result: r, cached: true };
     } catch {
     }
   }
@@ -4138,6 +4144,123 @@ function trialsLogId(q) {
   return s.length > 10 ? s.slice(0, 9) + "\u2026" : s || "-";
 }
 
+// src/pubmedsearch.ts
+import { createHash as createHash5 } from "crypto";
+import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync11 } from "fs";
+import { dirname as dirname5 } from "path";
+var MAX_RESULTS2 = 100;
+var DEFAULT_RESULTS2 = 20;
+var COLUMNS2 = ["pmid", "title", "first_author", "year", "journal", "publication_types", "pmcid", "level"];
+var EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
+var ident = (u) => {
+  if (process.env.FH_LIBRARY_NCBI_API_KEY) u.searchParams.set("api_key", process.env.FH_LIBRARY_NCBI_API_KEY);
+  u.searchParams.set("tool", "fh-library");
+  u.searchParams.set("email", contactEmail());
+  return u.toString();
+};
+function yearRange(years) {
+  const t = (years ?? "").replace(/\s+/g, "");
+  if (!t) return null;
+  const m = /^(\d{4})?(-)?(\d{4})?$/.exec(t);
+  if (!m || !m[1] && !m[3]) return { error: `years must be "2020-2026", "2022-", "-2019" or "2022", not "${years}"` };
+  const min = m[1] ?? "1000", max = m[3] ?? (m[2] ? String((/* @__PURE__ */ new Date()).getFullYear()) : m[1]);
+  return { min, max };
+}
+function normalizeQuery2(q) {
+  const query = (q.query ?? "").replace(/\s+/g, " ").trim();
+  if (!query) return { error: "empty query" };
+  const sort = q.sort ?? "relevance";
+  if (!["relevance", "newest"].includes(sort)) return { error: `sort must be relevance or newest, not "${String(q.sort)}"` };
+  const yr = yearRange(q.years);
+  if (yr && "error" in yr) return yr;
+  const out = { query, sort, max_results: Math.min(MAX_RESULTS2, Math.max(1, Math.floor(q.max_results ?? DEFAULT_RESULTS2))) };
+  if (yr) out.years = `${yr.min === "1000" ? "" : yr.min}-${yr.max}`;
+  return out;
+}
+var searchKey2 = (q) => createHash5("sha1").update(JSON.stringify(["pubmed", q.query, q.sort, q.years ?? "", q.max_results])).digest("hex").slice(0, 16);
+function esearchUrl(q) {
+  const u = new URL(`${EUTILS}/esearch.fcgi`);
+  u.searchParams.set("db", "pubmed");
+  u.searchParams.set("term", q.query);
+  u.searchParams.set("retmax", String(q.max_results));
+  u.searchParams.set("retmode", "json");
+  u.searchParams.set("sort", q.sort === "newest" ? "pub_date" : "relevance");
+  const yr = yearRange(q.years);
+  if (yr && !("error" in yr)) {
+    u.searchParams.set("datetype", "pdat");
+    u.searchParams.set("mindate", yr.min);
+    u.searchParams.set("maxdate", yr.max);
+  }
+  return ident(u);
+}
+function esummaryUrl(pmids) {
+  const u = new URL(`${EUTILS}/esummary.fcgi`);
+  u.searchParams.set("db", "pubmed");
+  u.searchParams.set("id", pmids.join(","));
+  u.searchParams.set("retmode", "json");
+  return ident(u);
+}
+function parseEsearch(json2) {
+  const d = JSON.parse(json2);
+  const r = d?.esearchresult ?? {};
+  return { total: Number(r.count ?? 0) || 0, ids: Array.isArray(r.idlist) ? r.idlist.map(String) : [] };
+}
+function parseEsummary(json2, ids, libraryDir) {
+  const d = JSON.parse(json2);
+  const res = d?.result ?? {};
+  const rows = [];
+  for (const id of ids) {
+    const s = res[id];
+    if (!s || s.error) continue;
+    const year = /\b(\d{4})\b/.exec(String(s.pubdate ?? ""))?.[1] ?? null;
+    const first = String(s.sortfirstauthor ?? (Array.isArray(s.authors) && s.authors[0]?.name) ?? "").replace(/\s+[A-Z]{1,3}$/, "").trim() || null;
+    const pmc2 = (Array.isArray(s.articleids) ? s.articleids : []).find((a) => a.idtype === "pmc")?.value ?? null;
+    const types = Array.isArray(s.pubtype) ? s.pubtype.filter((t) => t !== "Journal Article").join("; ") : "";
+    const paths = entryPaths(libraryDir, "pmid", id);
+    const level = entryExists(paths) ? String(readStatus(paths, emptyStatus(`pmid:${id}`, "pmid", id, libraryDir)).level) : null;
+    rows.push([id, String(s.title ?? "").replace(/\.$/, "") || null, first, year, s.source ? String(s.source) : null, types || null, pmc2 ? String(pmc2) : null, level]);
+  }
+  return rows;
+}
+var live = (url) => fetchText(url, { "User-Agent": "fh-library", Accept: "application/json" });
+async function searchArticles(raw, libraryDir = FH_LIBRARY_DIR, fetchImpl = live) {
+  const q = normalizeQuery2(raw);
+  if ("error" in q) return { ok: false, error: q.error };
+  const file2 = searchFile(libraryDir, searchKey2(q));
+  if (existsSync11(file2)) {
+    try {
+      const r = JSON.parse(readFileSync11(file2, "utf8"));
+      if (daysSince(r.searched) < searchCacheDays()) return { ok: true, result: r, cached: true };
+    } catch {
+    }
+  }
+  let total, ids;
+  try {
+    ({ total, ids } = parseEsearch(await fetchImpl(esearchUrl(q))));
+  } catch (e) {
+    return { ok: false, error: `pubmed: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  let rows = [];
+  if (ids.length) {
+    try {
+      rows = parseEsummary(await fetchImpl(esummaryUrl(ids)), ids, libraryDir);
+    } catch (e) {
+      return { ok: false, error: `pubmed: ${e instanceof Error ? e.message : String(e)}` };
+    }
+  }
+  const result = { source: "pubmed", query: q, total, columns: COLUMNS2, rows, searched: today() };
+  try {
+    mkdirSync8(dirname5(file2), { recursive: true });
+    writeAtomic(file2, JSON.stringify(result, null, 2) + "\n");
+  } catch {
+  }
+  return { ok: true, result, cached: false };
+}
+function logId2(q) {
+  const s = q.query.replace(/\s+/g, " ");
+  return s.length > 10 ? s.slice(0, 9) + "\u2026" : s;
+}
+
 // src/trialrecord.ts
 var list3 = (a) => Array.isArray(a) ? a : [];
 var para2 = (s, max = Infinity) => {
@@ -4209,10 +4332,120 @@ function resultsText(nct, md, maxChars) {
   return { nct, has_results: true, text: truncated ? part.slice(0, maxChars).trimEnd() + "\n\n[truncated]" : part, truncated, outcomes, note: truncated ? "cut at max_chars; library_read(id, section: <an outcome title>) returns one measure whole" : null };
 }
 
+// src/missing.ts
+import { existsSync as existsSync12, mkdirSync as mkdirSync9, readFileSync as readFileSync12 } from "fs";
+import { join as join12 } from "path";
+var missingFile = (p) => join12(p.entryDir, `${p.entry}-missing.md`);
+function readMissing(p) {
+  const f = missingFile(p);
+  if (!existsSync12(f)) return null;
+  const md = readFileSync12(f, "utf8");
+  const get = (k) => /^$/.test(k) ? "" : (new RegExp(`^${k}:[ \\t]*(.*)$`, "m").exec(md)?.[1] ?? "").trim();
+  const checked = get("checked"), reason = get("reason");
+  return checked ? { checked, reason: reason || "not found" } : null;
+}
+function freshMissing(p, retryDays) {
+  const m = readMissing(p);
+  return m && daysSince(m.checked) < retryDays ? m : null;
+}
+function rememberMissing(p, reason) {
+  const m = { checked: today(), reason };
+  mkdirSync9(p.entryDir, { recursive: true });
+  writeAtomic(missingFile(p), `checked: ${m.checked}
+reason: ${m.reason}
+`);
+  return m;
+}
+var missingNote = (m, retryDays) => `${m.reason} (checked ${m.checked}; asked again after ${retryDays} day${retryDays === 1 ? "" : "s"})`;
+
+// src/pubmedbatch.ts
+var MAX_PMIDS = 200;
+var COLUMNS3 = ["pmid", "title", "first_author", "year", "publication_types", "retracted", "level"];
+var EFETCH2 = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi";
+function efetchBatchUrl(pmids) {
+  const u = new URL(EFETCH2);
+  u.searchParams.set("db", "pubmed");
+  u.searchParams.set("id", pmids.join(","));
+  u.searchParams.set("retmode", "xml");
+  if (process.env.FH_LIBRARY_NCBI_API_KEY) u.searchParams.set("api_key", process.env.FH_LIBRARY_NCBI_API_KEY);
+  u.searchParams.set("tool", "fh-library");
+  u.searchParams.set("email", contactEmail());
+  return u.toString();
+}
+function splitArticles(xml) {
+  const out = /* @__PURE__ */ new Map();
+  for (const m of xml.matchAll(/<(PubmedArticle|PubmedBookArticle)\b[\s\S]*?<\/\1>/g)) {
+    const pmid = /<PMID[^>]*>(\d+)<\/PMID>/.exec(m[0])?.[1];
+    if (pmid && !out.has(pmid)) out.set(pmid, `<?xml version="1.0" ?>
+<PubmedArticleSet>${m[0]}</PubmedArticleSet>
+`);
+  }
+  return out;
+}
+var row2 = (pmid, s, level) => s ? [pmid, s.title, s.first_author, s.year, s.publication_types.length ? s.publication_types.join("; ") : null, s.retracted, level] : [pmid, null, null, null, null, null, level];
+async function fetchArticles(ids, libraryDir = FH_LIBRARY_DIR, converter = "fh-library", fetchImpl = fetchText) {
+  const result = { columns: COLUMNS3, rows: [], stored: 0, cached: 0, not_found: 0, invalid: 0 };
+  const order2 = [];
+  const invalid = /* @__PURE__ */ new Map();
+  for (const raw of ids.slice(0, MAX_PMIDS)) {
+    const p = parseId(String(raw));
+    if (p.error || p.type !== "pmid" || !/^\d{1,8}$/.test(p.id)) {
+      const k = String(raw).trim();
+      if (!invalid.has(k)) {
+        invalid.set(k, "invalid");
+        order2.push(k);
+      }
+      continue;
+    }
+    if (!order2.includes(p.id)) order2.push(p.id);
+  }
+  const status = (pmid) => {
+    const paths = entryPaths(libraryDir, "pmid", pmid);
+    return entryExists(paths) ? readStatus(paths, emptyStatus(`pmid:${pmid}`, "pmid", pmid, libraryDir)) : null;
+  };
+  const retry = settings().retry_after_days;
+  const known = (pmid) => !!freshMissing(entryPaths(libraryDir, "pmid", pmid), retry);
+  const missing = order2.filter((k) => !invalid.has(k) && !status(k) && !known(k));
+  let records = /* @__PURE__ */ new Map();
+  if (missing.length) records = splitArticles(await fetchImpl(efetchBatchUrl(missing)));
+  for (const k of order2) {
+    if (invalid.has(k)) {
+      result.rows.push(row2(k, null, "invalid"));
+      result.invalid++;
+      continue;
+    }
+    let s = status(k);
+    if (s) {
+      result.rows.push(row2(k, s, String(s.level)));
+      result.cached++;
+      continue;
+    }
+    const paths = entryPaths(libraryDir, "pmid", k);
+    if (known(k)) {
+      result.rows.push(row2(k, null, "not found"));
+      result.not_found++;
+      continue;
+    }
+    const xml = records.get(k);
+    const record = xml ? parsePubmedXml(xml) : null;
+    if (!record) {
+      rememberMissing(paths, "pmid not found");
+      result.rows.push(row2(k, null, "not found"));
+      result.not_found++;
+      continue;
+    }
+    if (!entryExists(paths)) writeEntry(paths, record, xml, converter);
+    s = status(k);
+    result.rows.push(row2(k, s, String(s.level)));
+    result.stored++;
+  }
+  return result;
+}
+
 // src/tools.ts
 var pkg = (() => {
   try {
-    return JSON.parse(readFileSync11(new URL("../package.json", import.meta.url), "utf8"));
+    return JSON.parse(readFileSync13(new URL("../package.json", import.meta.url), "utf8"));
   } catch {
     return { name: "fh-library", version: "0.0.0" };
   }
@@ -4232,6 +4465,8 @@ Tools
 - library_status(id) \u2014 the status of one record without downloading; level "missing" when it is not stored.
 - library_read(id, section?, query?, max_chars?, max_hits?) \u2014 one small piece of a stored document: its outline, one section, or the passages matching a query.
 - library_verify(claim, id) \u2014 does this one source state this one finding? A decision model judges the stored text and returns a verdict.
+- library_pubmed_fetch_articles(pmids) \u2014 title, first author, year, publication types, retracted and level for up to 200 PMIDs at once; faster and far smaller than asking PubMed, known papers from disk, the rest in one request and stored. For abstract or full text: library_read.
+- library_pubmed_search_articles(query, max_results?, sort?, years?) \u2014 search PubMed in its own syntax: the total and rows in columns order (PMID, title, first author, year, journal, publication types, PMCID, library level); faster and far smaller than asking PubMed. Cached a week.
 - library_clinicaltrials_search_studies(query | intervention | condition, status?, sort?, max_results?) \u2014 search ClinicalTrials.gov: the total and rows in columns order (NCT ID, title, status, phase, enrollment, dates, primary outcome, conditions, interventions, has_results). Cached a week.
 - library_clinicaltrials_get_study_record(nct) \u2014 one trial as a review needs it (status, design, enrollment, dates, outcomes, eligibility, result publications, summary), from the stored record; added first when missing.
 - library_clinicaltrials_get_study_results(nct, max_chars?) \u2014 a trial's posted results as Markdown, capped; the outcome titles listed for library_read.
@@ -4241,7 +4476,7 @@ Hints
 - library_read and library_verify store a missing record themselves; the library_read answer then carries added: true. No library_add necessary first.
 - citable false \u2014 the paper is retracted (a retraction notice, or PubMed's publication type), or holds nothing to read: no abstract and no full text. comment says which; corrections lists the notices as {type, pmid, source}.
 - level \u2014 what is stored: "full_text", "abstract" (no full text could be found; attempts names each source tried and why it failed) or "title" (not even an abstract; citable false).
-- error "pmid not found" or "invalid id" \u2014 the ID itself is wrong; the same call gives the same answer.
+- error "pmid not found", "doi not found", "ctgov: not a study record", "dailymed: not an SPL document" \u2014 no service knows the ID. Remembered for a day (FH_LIBRARY_RETRY_AFTER_DAYS): the same call answers from disk with the date it was checked; after that the service is asked again. "invalid id" \u2014 the ID itself is malformed; the same call gives the same answer.
 - Calls may run in parallel: library_add, library_read and library_verify. Two calls on the same missing record share one add.
 - library_fetch takes any URL that is not a paper, label or trial record; those have IDs, and library_add, library_read and library_verify work on the stored document. A second pass over the same review reads every page from disk; a failed fetch is remembered for a day.
 - To verify that a web page exists and what it is: library_fetch(url, title_only: true). The answer is "Contents of <url>:" and the page's title line \u2014 a few tokens \u2014 or the fetch error; the page itself is stored in full, so a later library_fetch of the same URL reads from disk.
@@ -4337,7 +4572,8 @@ function registerTools(server2) {
       const xml = await fetchSpl(setid);
       const s = parseSpl(xml);
       if (!s) {
-        log("library_add", requested, "dailymed failed: not an SPL document");
+        rememberMissing(paths, "dailymed: not an SPL document");
+        log("library_add", requested, "dailymed failed: not an SPL document (remembered)");
         return { ...status, error: "dailymed: not an SPL document" };
       }
       const meta = writeLabelEntry(paths, s, xml, `${pkg.name} ${pkg.version}`);
@@ -4345,7 +4581,9 @@ function registerTools(server2) {
       return statusFromMeta(paths, meta, status);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      log("library_add", requested, `dailymed failed: ${msg}`);
+      const gone = /not an SPL document|^HTTP 404\b/.test(msg);
+      if (gone) rememberMissing(paths, msg.startsWith("HTTP 404") ? "dailymed: no label for this set ID (HTTP 404)" : msg);
+      log("library_add", requested, `dailymed failed: ${msg}${gone ? " (remembered)" : ""}`);
       return { ...status, error: msg };
     }
   }
@@ -4378,7 +4616,8 @@ function registerTools(server2) {
       const json2 = await fetchStudy(nctid);
       const s = parseStudy(json2);
       if (!s) {
-        log("library_add", requested, "ctgov failed: not a study record");
+        rememberMissing(paths, "ctgov: not a study record");
+        log("library_add", requested, "ctgov failed: not a study record (remembered)");
         return { ...status, error: "ctgov: not a study record" };
       }
       const meta = writeStudyEntry(paths, s, json2, `${pkg.name} ${pkg.version}`);
@@ -4386,7 +4625,9 @@ function registerTools(server2) {
       return statusFromMeta(paths, meta, status);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      log("library_add", requested, `ctgov failed: ${msg}`);
+      const gone = /not a study record|^HTTP 404\b/.test(msg);
+      if (gone) rememberMissing(paths, msg.startsWith("HTTP 404") ? "ctgov: no study for this NCT ID (HTTP 404)" : msg);
+      log("library_add", requested, `ctgov failed: ${msg}${gone ? " (remembered)" : ""}`);
       return { ...status, error: msg };
     }
   }
@@ -4409,6 +4650,14 @@ function registerTools(server2) {
   async function addEntryNow(id) {
     const t0 = Date.now();
     let parsed = parseId(id);
+    if (!parsed.error) {
+      const mp = entryPaths(FH_LIBRARY_DIR, parsed.type, parsed.id);
+      const miss2 = entryExists(mp) ? null : freshMissing(mp, settings().retry_after_days);
+      if (miss2) {
+        log("library_add", parsed.requested, `missing cached: ${miss2.reason} (${miss2.checked})`);
+        return json({ ...emptyStatus(parsed.requested, parsed.type, parsed.id, FH_LIBRARY_DIR), entry: mp.entry, level: "missing", error: missingNote(miss2, settings().retry_after_days) });
+      }
+    }
     if (parsed.error) {
       log("library_add", parsed.requested, `error ${parsed.error}`);
       return json({ ...emptyStatus(parsed.requested, parsed.type, parsed.id, FH_LIBRARY_DIR), error: parsed.error });
@@ -4503,7 +4752,8 @@ function registerTools(server2) {
         }
       }
       if (!record) {
-        log("library_add", parsed.requested, "crossref failed: doi not found at Crossref or doi.org");
+        rememberMissing(paths, "doi not found");
+        log("library_add", parsed.requested, "crossref failed: doi not found at Crossref or doi.org (remembered)");
         return json({ ...status, error: "doi not found" });
       }
       if (!record.doi) record.doi = parsed.id;
@@ -4528,7 +4778,8 @@ function registerTools(server2) {
       }
       const record = parsePubmedXml(xml);
       if (!record) {
-        log("library_add", parsed.requested, "pubmed failed: pmid not found");
+        rememberMissing(paths, "pmid not found");
+        log("library_add", parsed.requested, "pubmed failed: pmid not found (remembered)");
         return json({ ...status, error: "pmid not found" });
       }
       meta = writeEntry(paths, record, xml, `${pkg.name} ${pkg.version}`);
@@ -4557,8 +4808,9 @@ function registerTools(server2) {
         log("library_status", parsed.requested, `level=${s.level}`);
         return json(s);
       }
-      log("library_status", parsed.requested, "level=missing");
-      return json({ ...status, entry: paths.entry, entry_dir: paths.entryDir, level: "missing" });
+      const miss2 = freshMissing(paths, settings().retry_after_days);
+      log("library_status", parsed.requested, miss2 ? `level=missing (${miss2.reason}, ${miss2.checked})` : "level=missing");
+      return json({ ...status, entry: paths.entry, level: "missing", ...miss2 ? { error: missingNote(miss2, settings().retry_after_days) } : {} });
     }
   );
   server2.tool(
@@ -4589,8 +4841,8 @@ function registerTools(server2) {
         }
         added = true;
       }
-      const full = existsSync11(paths.fulltextMd);
-      const md = readFileSync11(full ? paths.fulltextMd : paths.md, "utf8");
+      const full = existsSync13(paths.fulltextMd);
+      const md = readFileSync13(full ? paths.fulltextMd : paths.md, "utf8");
       const text3 = full ? "full_text" : "abstract";
       const base = added ? { requested: parsed.requested, entry: paths.entry, text: text3, added: true } : { requested: parsed.requested, entry: paths.entry, text: text3 };
       const headings2 = () => outline(md, text3).sections;
@@ -4610,8 +4862,8 @@ function registerTools(server2) {
         const cap = max_chars ?? 6e3;
         let sec = readSection(md, section2, cap);
         let via = "";
-        if (!sec && /abstract/i.test(section2) && full && existsSync11(paths.md)) {
-          sec = readSection(readFileSync11(paths.md, "utf8"), "abstract", cap);
+        if (!sec && /abstract/i.test(section2) && full && existsSync13(paths.md)) {
+          sec = readSection(readFileSync13(paths.md, "utf8"), "abstract", cap);
           via = " (from the abstract file)";
         }
         if (!sec && /declaration/i.test(section2)) {
@@ -4680,7 +4932,7 @@ function registerTools(server2) {
       }
       log("library_info", null, `entries=${info.entries}${info.verify ? ` verify ${info.verify.model} ${info.verify.ok ? `ok ${info.verify.ms} ms` : `down: ${info.verify.error}`}` : " verify not configured"}`);
       const s = currentStats();
-      const cache = s ? { since: s.started, verify: s.verify, fetch: s.fetch, search: s.search } : null;
+      const cache = s ? { since: s.started, verify: s.verify, fetch: s.fetch, search: s.search, pubmed: s.pubmed } : null;
       return { content: [{ type: "text", text: compact2({ ...info, cache }) }] };
     }
   );
@@ -4711,9 +4963,46 @@ function registerTools(server2) {
       return { content: [{ type: "text", text: r.error }], isError: true };
     }
   );
+  server2.tool(
+    "library_pubmed_fetch_articles",
+    `Title, first author, year, publication types, retracted and library level for up to ${MAX_PMIDS} PubMed IDs in one call. Faster and far smaller than asking PubMed: known papers come from disk, the rest in one request, stored for every later call; rows as arrays in columns order, ~120 characters a paper. Level "not found": PubMed has no such record. For abstract or full text: library_read.`,
+    { pmids: z.array(z.string()).min(1).max(MAX_PMIDS).describe('PubMed IDs, "30955454" or "pmid:30955454", up to 200.') },
+    async ({ pmids }) => {
+      const t0 = Date.now();
+      const r = await fetchArticles(pmids, FH_LIBRARY_DIR, `${pkg.name} ${pkg.version}`);
+      if (r.cached) bump("pubmed", true, r.cached);
+      if (r.stored) bump("pubmed", false, r.stored);
+      const secs = ((Date.now() - t0) / 1e3).toFixed(1).padStart(4, "0") + "s";
+      log("library_pubmed", `pmids:${r.rows.length}`, `fetch_articles ${secs} cached=${r.cached} stored=${r.stored}${r.not_found ? ` not_found=${r.not_found}` : ""}${r.invalid ? ` invalid=${r.invalid}` : ""}`);
+      return { content: [{ type: "text", text: leanJson(r) }] };
+    }
+  );
+  server2.tool(
+    "library_pubmed_search_articles",
+    `Search PubMed with its own query syntax (AND / OR, field tags like [pt], [ti], [mesh]); sort relevance | newest; years "2020-2026". Faster and far smaller than asking PubMed: the total and up to ${MAX_RESULTS2} rows as arrays in columns order \u2014 PMID, title, first author, year, journal, publication types, PMCID when free full text exists, and the library level when the paper is already stored. The same search is answered from disk for ${searchCacheDays()} days. For a batch of PMIDs: library_pubmed_fetch_articles; for abstract or full text: library_read.`,
+    {
+      query: z.string().describe('PubMed query, full syntax: "tadalafil AND (systematic review[pt] OR meta-analysis[pt])".'),
+      max_results: z.number().int().min(1).max(MAX_RESULTS2).default(20).describe("Rows to return (1\u2013100)."),
+      sort: z.enum(["relevance", "newest"]).default("relevance").describe("relevance (PubMed's ranking) or newest (publication date, latest first)."),
+      years: z.string().optional().describe('Publication years: "2020-2026", "2022-", "-2019" or "2022".')
+    },
+    async (args) => {
+      const t0 = Date.now();
+      const r = await searchArticles(args, FH_LIBRARY_DIR);
+      const secs = ((Date.now() - t0) / 1e3).toFixed(1).padStart(4, "0") + "s";
+      if (!r.ok) {
+        log("library_search", "pm:-", `error: ${r.error}`);
+        return { content: [{ type: "text", text: compact2({ error: r.error }) }], isError: true };
+      }
+      bump("search", r.cached);
+      const q = r.result.query;
+      log("library_search", `pm:${logId2(q)}`, `${r.cached ? "cached" : `searched ${secs}`} rows=${r.result.rows.length} total=${r.result.total}${q.sort !== "relevance" ? ` sort=${q.sort}` : ""}${q.years ? ` years=${q.years}` : ""} | ${q.query}`);
+      return { content: [{ type: "text", text: leanJson(r.result) }] };
+    }
+  );
   server2.tool(
     "library_clinicaltrials_search_studies",
-    `Search ClinicalTrials.gov by free text, intervention or condition; status ongoing | completed | all; sort relevance | newest | largest | completion. Returns the total and up to ${MAX_RESULTS} rows as arrays in columns order: NCT ID, title, status, phase, enrollment, start, primary completion, primary outcome, conditions, interventions, has_results. Link: https://clinicaltrials.gov/study/<NCT ID>. Cached ${SEARCH_AFTER_DAYS} days. One trial in detail: library_clinicaltrials_get_study_record.`,
+    `Search ClinicalTrials.gov by free text, intervention or condition; status ongoing | completed | all; sort relevance | newest | largest | completion. Returns the total and up to ${MAX_RESULTS} rows as arrays in columns order: NCT ID, title, status, phase, enrollment, start, primary completion, primary outcome, conditions, interventions, has_results. Link: https://clinicaltrials.gov/study/<NCT ID>. Cached ${searchCacheDays()} days. One trial in detail: library_clinicaltrials_get_study_record.`,
     {
       query: z.string().optional().describe("Free-text search across all fields (title, conditions, interventions, summary, \u2026); AND / OR / NOT allowed."),
       intervention: z.string().optional().describe('Intervention or treatment, e.g. "tadalafil", "cognitive behavioral therapy".'),
@@ -4760,7 +5049,7 @@ function registerTools(server2) {
         return { content: [{ type: "text", text: compact2({ error: e.error }) }], isError: true };
       }
       const raw = e.paths.fulltextRaw("json");
-      const r = existsSync11(raw) ? recordSummary(readFileSync11(raw, "utf8")) : null;
+      const r = existsSync13(raw) ? recordSummary(readFileSync13(raw, "utf8")) : null;
       if (!r) {
         log("library_trials", e.requested, "record error: no stored record");
         return { content: [{ type: "text", text: compact2({ error: "no stored record" }) }], isError: true };
@@ -4779,7 +5068,7 @@ function registerTools(server2) {
         log("library_trials", nct, `results error: ${e.error}`);
         return { content: [{ type: "text", text: compact2({ error: e.error }) }], isError: true };
       }
-      const md = existsSync11(e.paths.fulltextMd) ? readFileSync11(e.paths.fulltextMd, "utf8") : "";
+      const md = existsSync13(e.paths.fulltextMd) ? readFileSync13(e.paths.fulltextMd, "utf8") : "";
       const r = resultsText(e.requested.replace(/^nct:/, "NCT"), md, max_chars);
       log("library_trials", e.requested, `results ${r.has_results ? `${r.outcomes.length} outcomes${r.truncated ? " truncated" : ""}` : "none"}`);
       return { content: [{ type: "text", text: leanJson(r) }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fh-library",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "mcpName": "io.github.forever-healthy/fh-library",
   "description": "MCP Server that builds a local Markdown library of the scientific papers cited by evidence reviews — fetches metadata, abstract and full text per PubMed ID through a configurable cascade of retrieval services",
   "type": "module",