@giacomo-ciro/paperino 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+<h1 align="center">paperino</h1>
+
+> Every new arXiv paper, every day, filtered by Claude Code down to what's actually worth your time.
+
+
+<p align="center">
+  <img src="public/paperino.png" alt="Paperino banner" width="100%">
+</p>
+
+I work on a 3D vision project. On average, ~200 new papers are published daily in the cs.CV category.
+
+Of those, ~40 look relevant from the title, and fewer than 5 are actually worth reading after scanning the abstract.
+
+Existing tools based on similarity search or embeddings (Scholar Inbox, arXiv Sanity, etc.) aren't precise enough.
+
+Claude Code delivers hyper-precise filtering tailored to your exact research project, running fresh every day.
+
+Scanning the results then takes just 5-10 minutes, and you stay up to date with the latest research.
+
+## Usage
+Paperino is a CLI utility, fully configurable via a simple .toml file. For now, it only produces an HTML digest; email delivery is coming soon.
+
+You can run it manually:
+```
+paperino
+```
+
+Useful flags:
+```
+paperino --configure    # open the config file in your default editor
+paperino --logs         # tail the log file; no pipeline run
+paperino --force        # discard the run/digest for the selected window(s) and start fresh
+paperino --only-fetch   # only fetch papers, skip the scoring pipeline
+paperino --quiet        # suppress progress output; print only the digest path
+paperino -y             # skip the confirmation prompt and run immediately
+```
+
+Or, as I do, run every weekday at 9:30 AM. Open the crontab:
+```bash
+crontab -e
+```
+and add:
+```bash
+# minute 30, hour 9, Mon-Fri
+30 9 * * 1-5 paperino -y --quiet
+```
+> **Note:** arXiv announces new submissions at 20:00 ET on Sun/Mon/Tue/Wed/Thu. Running at 9:30 AM CET (3:30 ET) ensures the run always lands after the prior evening's announcement, catching all five announcements without needing to run on weekends.
+
+## How It Works
+
+**Preliminaries:** arXiv publishes new papers 5 times a week, on Sun, Mon, Tue, Wed and Thu at 20:00 CET. Each publication includes papers submitted during the preceding submission window (14:00 CET to 14:00 the following day), except weekend submissions, which are aggregated and published Monday night. Full details on the [official page](https://info.arxiv.org/help/availability.html#Announcement%20Schedule).
+
+Paperino is minimal, built to work efficiently. It follows a 3-step process:
+
+1. **Fetching papers:** fetch all arXiv papers published in a given window (by default, the latest submission window relative to when the command is run). This step only filters by arXiv category (cs.LM, cs.CV, etc.).
+2. **Coarse filtering:** Claude receives your research context and a batch of titles per call (default 20), and outputs a binary relevant/not-relevant judgment. This step is kept coarse: Claude defaults to marking papers as potentially relevant when unsure.
+3. **Fine filtering:** Claude receives a smaller batch of title+abstract pairs per call and scores each paper on a scale of 1-10. Papers scoring above 6 get a full summary in the HTML digest; the rest get a one-line mention.
+
+All aforementioned parameters are configurable (what model to use, papers per call, max papers, threshold score etc.):
+```
+paperino --configure
+```
+
+## Acknowledgments
+This tool was initially inspired by [AlessandroMorosini/arxiv-digest](https://github.com/AlessandroMorosini/arxiv-digest). Code-wise, I took inspiration from [kunchenguid/gnhf](https://github.com/kunchenguid/gnhf).

package/dist/bootstrap-config.toml

@@ -0,0 +1,95 @@
+# Config file for paperino.
+# Required fields: RESEARCH.ARXIV_CAT and RESEARCH.RESEARCH_INTERESTS.
+# Everything else has a sensible default — edit only if you want to.
+
+# What to fetch, and what counts as relevant.
+[RESEARCH]
+# arXiv categories to fetch. Required: add at least one.
+# Browse the full taxonomy at https://arxiv.org/category_taxonomy
+# Examples:
+# "cs.LG",     # machine learning
+# "cs.CV",     # computer vision
+# "cs.CL",     # computation and language
+# "cs.AI",     # artificial intelligence
+# "cs.RO",     # robotics
+# "stat.ML",   # statistical ml
+# must be in quote: e.g., ARXIV_CAT=["cs.CV"]
+ARXIV_CAT = []
+# Describe your research so claude can judge relevance. Required.
+# Templated into both scoring prompts as {research_interests} — the more
+# specific, the better the filtering.
+# Example: "Incremental 3D object reconstruction from streamed point clouds
+# using transformer-based geometric primitive decoders."
+RESEARCH_INTERESTS = """
+"""
+# Papers scoring below this (on the 1-10 scale below) get only a one-line
+# mention in the digest instead of a full summary.
+MIN_SCORE = 6
+
+# Where results land.
+[OUTPUT]
+# Each run writes to <out-dir>/YYYY-MM-DD/{papers.json, digest.html}, where
+# YYYY-MM-DD is the submission window's cutoff date (UTC), not the run date.
+OUT_DIR = "~/.paperino/outputs"
+# Every run appends here (the file is never rotated). `paperino --logs` tails it.
+LOG_FILE = "~/.paperino/paperino.log"
+
+# Coarse pass: a cheap, fast model screens every fetched paper by title alone,
+# marking it 0 or 1 to decide whether it's worth the pricier fine pass below.
+# On error or malformed output, papers fail open (kept, not dropped).
+[STAGES.COARSE]
+MODEL = "haiku" # one of: fable, opus, sonnet, haiku
+CALL_SIZE = 20 # papers per claude call
+MAX_WORKERS = 10 # concurrent calls
+# Only describe the task here — the output shape (JSON keys/types) is
+# enforced separately via claude's structured-output schema (src/schemas.ts).
+# Don't add a JSON example; anything below is task instructions only.
+PROMPT = """
+You are screening newly announced arXiv papers for relevance to a research project.
+
+Project description:
+{research_interests}
+
+Below is a list of papers, one per line, formatted as "<paperId> — <title>".
+Judging from the title alone, mark each paper 1 if it could plausibly be
+relevant to the project, or 0 if it is clearly not relevant. This is a coarse
+first pass: when in doubt, keep the paper (mark it 1).
+
+Papers:
+{papers}
+"""
+
+# Fine pass: a stronger model scores every paper that passed the coarse pass,
+# reading title and abstract, on the 1-10 scale below. A failed call leaves
+# its papers unscored rather than guessing.
+[STAGES.FINE]
+MODEL = "sonnet" # one of: fable, opus, sonnet, haiku
+CALL_SIZE = 5 # papers per claude call
+MAX_WORKERS = 10 # concurrent calls
+PROMPT = """
+You are scoring newly announced arXiv papers for relevance to a research project.
+
+Project description:
+{research_interests}
+
+Score each paper below on this scale:
+- 9-10: Directly addresses the project's core problem or uses the same methods. Must-read.
+- 7-8: Closely related — same domain, complementary techniques, useful as baseline.
+- 5-6: Tangentially related — may contain reusable ideas or methods.
+- 3-4: Loosely connected — different problem but same general area.
+- 1-2: Not relevant to this specific project.
+
+Papers:
+{papers}
+"""
+
+# How paperino calls claude.
+[RUNTIME]
+# Absolute path to the claude CLI binary, used for every scoring call.
+# Auto-filled from `which claude` on first run. If that failed, run
+# `which claude` yourself and paste the result here.
+CLAUDE_BINARY = "claude"
+# Per-call timeout, in seconds.
+CALL_TIMEOUT_SECONDS = 300
+# Retries after a call fails, before giving up on it.
+CALL_RETRIES = 1

package/dist/cli.mjs

@@ -0,0 +1,1179 @@
+#!/usr/bin/env node
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { Command, InvalidArgumentError } from "commander";
+import pc from "picocolors";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parse } from "smol-toml";
+import { XMLParser } from "fast-xml-parser";
+import { createInterface } from "node:readline/promises";
+import cliSpinners from "cli-spinners";
+//#region src/agent/claude.ts
+function isFinalStructuredResult(event) {
+	return !event.is_error && event.subtype === "success" && !!event.structured_output;
+}
+function buildClaudeArgs(prompt, model, schema) {
+	return [
+		"--model",
+		model,
+		"-p",
+		prompt,
+		"--verbose",
+		"--output-format",
+		"stream-json",
+		"--json-schema",
+		JSON.stringify(schema),
+		"--allowedTools",
+		"StructuredOutput",
+		"--dangerously-skip-permissions"
+	];
+}
+function terminateClaudeProcess(child) {
+	if (child.pid) try {
+		process.kill(-child.pid, "SIGTERM");
+		return;
+	} catch {}
+	child.kill("SIGTERM");
+}
+/** Split a newline-delimited JSON stream into parsed events, tolerating partial chunks. */
+function readJSONLStream(stream, onEvent) {
+	let buffer = "";
+	stream.on("data", (chunk) => {
+		buffer += chunk.toString();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				onEvent(JSON.parse(trimmed));
+			} catch {}
+		}
+	});
+}
+var ClaudeAgent = class {
+	bin;
+	name = "claude";
+	constructor(bin) {
+		this.bin = bin;
+	}
+	run(prompt, opts) {
+		return new Promise((resolve, reject) => {
+			const child = spawn(this.bin, buildClaudeArgs(prompt, opts.model, opts.schema), {
+				cwd: tmpdir(),
+				detached: true,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				env: process.env
+			});
+			let stderr = "";
+			let settled = false;
+			const onAbort = () => {
+				if (settled) return;
+				settled = true;
+				terminateClaudeProcess(child);
+				reject(/* @__PURE__ */ new Error("claude call aborted"));
+			};
+			opts.signal?.addEventListener("abort", onAbort, { once: true });
+			child.stderr.on("data", (data) => {
+				stderr += data.toString();
+			});
+			child.on("error", (err) => {
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error(`Failed to spawn claude: ${err.message}`));
+			});
+			child.stdout.on("error", (err) => {
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error(`stdout stream error: ${err.message}`));
+			});
+			child.stderr.on("error", (err) => {
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error(`stderr stream error: ${err.message}`));
+			});
+			let resultEvent = null;
+			let finalStructuredResultEvent = null;
+			readJSONLStream(child.stdout, (event) => {
+				if (event.type !== "result") return;
+				const next = event;
+				if (isFinalStructuredResult(next)) finalStructuredResultEvent = next;
+				else if (!finalStructuredResultEvent) resultEvent = next;
+			});
+			child.on("close", (code) => {
+				if (settled) return;
+				settled = true;
+				opts.signal?.removeEventListener("abort", onAbort);
+				if (code !== 0) {
+					reject(/* @__PURE__ */ new Error(`claude exited with code ${code}: ${stderr}`));
+					return;
+				}
+				const terminalResultEvent = finalStructuredResultEvent ?? resultEvent;
+				if (!terminalResultEvent) {
+					reject(/* @__PURE__ */ new Error("claude returned no result event"));
+					return;
+				}
+				if (terminalResultEvent.is_error || terminalResultEvent.subtype !== "success") {
+					reject(/* @__PURE__ */ new Error(`claude reported error: ${JSON.stringify(terminalResultEvent)}`));
+					return;
+				}
+				if (!terminalResultEvent.structured_output) {
+					reject(/* @__PURE__ */ new Error("claude returned no structured_output"));
+					return;
+				}
+				resolve({ output: terminalResultEvent.structured_output });
+			});
+		});
+	}
+};
+const CONFIG_PATH = join(join(homedir(), ".paperino"), "config.toml");
+const ALLOWED_MODELS = [
+	"fable",
+	"opus",
+	"sonnet",
+	"haiku"
+];
+const ARXIV_CATEGORY_RE = /^[a-z-]+(\.[A-Z]{2,3})?$/;
+function expandTilde(path) {
+	return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
+}
+function templatePath() {
+	return new URL("./bootstrap-config.toml", import.meta.url).pathname;
+}
+function detectClaudeBinary() {
+	try {
+		return execFileSync("which", ["claude"], { encoding: "utf-8" }).trim() || null;
+	} catch {
+		return null;
+	}
+}
+/** `mkdir -p` the config dir and, on first run only, template the config from the bundled default. */
+function ensureConfig(configPath = CONFIG_PATH) {
+	mkdirSync(dirname(configPath), { recursive: true });
+	if (existsSync(configPath)) return;
+	const template = readFileSync(templatePath(), "utf-8");
+	const claudeBinary = detectClaudeBinary();
+	const rendered = claudeBinary ? template.replace("CLAUDE_BINARY = \"claude\"", `CLAUDE_BINARY = "${claudeBinary}"`) : template;
+	if (!claudeBinary) process.stderr.write("warning: claude CLI not found — set RUNTIME.CLAUDE_BINARY in the config once it's installed.\n");
+	writeFileSync(configPath, rendered, "utf-8");
+}
+var ConfigErrorCollector = class {
+	errors = [];
+	add(message) {
+		this.errors.push(message);
+	}
+	string(table, key, label = key) {
+		const value = table[key];
+		if (typeof value !== "string") {
+			this.add(`"${label}" must be a string`);
+			return "";
+		}
+		return value;
+	}
+	nonEmptyString(table, key, label = key) {
+		const value = this.string(table, key, label);
+		if (value.trim() === "") this.add(`"${label}" is empty`);
+		return value;
+	}
+	number(table, key, label = key) {
+		const value = table[key];
+		if (typeof value !== "number") {
+			this.add(`"${label}" must be a number`);
+			return 0;
+		}
+		return value;
+	}
+	stringArray(table, key, label = key) {
+		const value = table[key];
+		if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+			this.add(`"${label}" must be an array of strings`);
+			return [];
+		}
+		return value;
+	}
+	nonEmptyStringArray(table, key, label = key) {
+		const value = this.stringArray(table, key, label);
+		if (value.length === 0) this.add(`"${label}" is empty`);
+		return value;
+	}
+	/** Number already extracted via `.number()`; checks it satisfies `predicate`, else records `detail`. */
+	numberSatisfies(value, label, predicate, detail) {
+		if (!predicate(value)) this.add(`"${label}" ${detail}`);
+	}
+	/** String already extracted via `.nonEmptyString()`; checks it's one of `allowed`. */
+	oneOf(value, allowed, label) {
+		if (value !== "" && !allowed.includes(value)) this.add(`"${label}" must be one of: ${allowed.join(", ")} (got "${value}")`);
+	}
+	/** Every arXiv category must look like "cs.LG" or "stat" (see https://arxiv.org/category_taxonomy). */
+	arxivCategories(value, label) {
+		for (const cat of value) if (!ARXIV_CATEGORY_RE.test(cat)) this.add(`"${label}" contains "${cat}", which doesn't look like an arXiv category (e.g. "cs.LG")`);
+	}
+	/** Prompt already extracted via `.nonEmptyString()`; must template both placeholders it's filled with. */
+	promptHasPlaceholders(value, label) {
+		if (value === "") return;
+		for (const placeholder of ["{research_interests}", "{papers}"]) if (!value.includes(placeholder)) this.add(`"${label}" is missing the ${placeholder} placeholder`);
+	}
+	table(table, key, label = key) {
+		const value = table[key];
+		if (typeof value !== "object" || value === null) {
+			this.add(`"[${label}]" table is missing`);
+			return {};
+		}
+		return value;
+	}
+	stage(stages, key, label) {
+		const stage = this.table(stages, key, label);
+		const model = this.nonEmptyString(stage, "MODEL", `${label}.MODEL`);
+		this.oneOf(model, ALLOWED_MODELS, `${label}.MODEL`);
+		const callSize = this.number(stage, "CALL_SIZE", `${label}.CALL_SIZE`);
+		this.numberSatisfies(callSize, `${label}.CALL_SIZE`, (n) => n > 0, "must be a positive number");
+		const maxWorkers = this.number(stage, "MAX_WORKERS", `${label}.MAX_WORKERS`);
+		this.numberSatisfies(maxWorkers, `${label}.MAX_WORKERS`, (n) => n > 0, "must be a positive number");
+		const prompt = this.nonEmptyString(stage, "PROMPT", `${label}.PROMPT`);
+		this.promptHasPlaceholders(prompt, `${label}.PROMPT`);
+		return {
+			model,
+			callSize,
+			maxWorkers,
+			prompt
+		};
+	}
+	throwIfAny(configPath) {
+		if (this.errors.length === 0) return;
+		const list = this.errors.map((e) => `  - ${e}`).join("\n");
+		throw new Error(`Config error(s) in ${configPath} (run --configure to edit):\n${list}`);
+	}
+};
+/** Load, validate, and map the UPPER_SNAKE_CASE config TOML. */
+function loadConfig(configPath = CONFIG_PATH) {
+	const table = parse(readFileSync(configPath, "utf-8"));
+	const errors = new ConfigErrorCollector();
+	const runtime = errors.table(table, "RUNTIME");
+	const research = errors.table(table, "RESEARCH");
+	const output = errors.table(table, "OUTPUT");
+	const stages = errors.table(table, "STAGES");
+	const callTimeoutSeconds = errors.number(runtime, "CALL_TIMEOUT_SECONDS", "RUNTIME.CALL_TIMEOUT_SECONDS");
+	errors.numberSatisfies(callTimeoutSeconds, "RUNTIME.CALL_TIMEOUT_SECONDS", (n) => n > 0, "must be a positive number");
+	const callRetries = errors.number(runtime, "CALL_RETRIES", "RUNTIME.CALL_RETRIES");
+	errors.numberSatisfies(callRetries, "RUNTIME.CALL_RETRIES", (n) => n >= 0, "must be zero or a positive number");
+	const arxivCat = errors.nonEmptyStringArray(research, "ARXIV_CAT", "RESEARCH.ARXIV_CAT");
+	errors.arxivCategories(arxivCat, "RESEARCH.ARXIV_CAT");
+	const minScore = errors.number(research, "MIN_SCORE", "RESEARCH.MIN_SCORE");
+	errors.numberSatisfies(minScore, "RESEARCH.MIN_SCORE", (n) => n >= 1 && n <= 10, "must be between 1 and 10");
+	const config = {
+		claudeBinary: errors.nonEmptyString(runtime, "CLAUDE_BINARY", "RUNTIME.CLAUDE_BINARY"),
+		callTimeoutMs: callTimeoutSeconds * 1e3,
+		callRetries,
+		arxivCat,
+		researchInterests: errors.nonEmptyString(research, "RESEARCH_INTERESTS", "RESEARCH.RESEARCH_INTERESTS"),
+		minScore,
+		outDir: expandTilde(errors.nonEmptyString(output, "OUT_DIR", "OUTPUT.OUT_DIR")),
+		logFile: expandTilde(errors.nonEmptyString(output, "LOG_FILE", "OUTPUT.LOG_FILE")),
+		coarse: errors.stage(stages, "COARSE", "STAGES.COARSE"),
+		fine: errors.stage(stages, "FINE", "STAGES.FINE")
+	};
+	errors.throwIfAny(configPath);
+	return config;
+}
+/** Open the config file in the user's editor, falling back to `vi`. */
+function openConfigInEditor(configPath = CONFIG_PATH) {
+	const candidates = [
+		process.env.VISUAL,
+		process.env.EDITOR,
+		"vi"
+	].filter((c) => !!c);
+	for (const editor of candidates) {
+		const result = spawnSync(editor, [configPath], { stdio: "inherit" });
+		if (!result.error && result.status === 0) return;
+	}
+	process.stdout.write(`Could not open an editor. Edit the config file yourself: ${configPath}\n`);
+}
+//#endregion
+//#region src/digest.ts
+function escapeHtml(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+}
+/**
+* Build (subject, html body) from all papers that passed the coarse filter.
+* Papers scoring >= minScore get a full card; the rest (including papers left
+* unscored by a failed call) get a one-line mention at the bottom.
+*/
+function buildDigest(papers, windowDate, minScore) {
+	const kept = papers.filter((p) => p.coarse === 1).sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+	const top = kept.filter((p) => (p.score ?? 0) >= minScore);
+	const rest = kept.filter((p) => (p.score ?? 0) < minScore);
+	const subject = `arXiv digest — ${windowDate} (${top.length} papers)`;
+	if (kept.length === 0) return {
+		subject,
+		body: wrap(`<p><b>paperino:</b> submission window ${windowDate} — no relevant papers.</p>`)
+	};
+	const parts = [`<p><b>paperino:</b> submission window ${windowDate} — ${kept.length}/${papers.length} papers passed the coarse filter, ${top.length} scored ≥ ${minScore}.</p>`];
+	for (const p of top) parts.push(card(p));
+	if (rest.length > 0) {
+		const items = rest.map((p) => lineItem(p)).join("");
+		parts.push(`<h3>Lower-scored papers</h3><ul>${items}</ul>`);
+	}
+	return {
+		subject,
+		body: wrap(parts.join("\n"))
+	};
+}
+const HEART_SVG = `<svg width="12" height="12" viewBox="0 0 512 512" fill="currentColor" style="vertical-align:-1px" aria-hidden="true"><path d="M462.3 62.6C407.5 15.9 326 24.3 275.7 76.2L256 96.5l-19.7-20.3C186.1 24.3 104.5 15.9 49.7 62.6c-62.8 53.6-66.1 149.8-9.9 207.9l193.5 199.8c12.5 12.9 32.8 12.9 45.3 0l193.5-199.8c56.3-58.1 53-154.3-9.8-207.9z"/></svg>`;
+function wrap(inner) {
+	return `<div style="max-width:900px;margin:0 auto;font-family:'Lucida Grande','Helvetica Neue',Helvetica,Arial,sans-serif;">
+
+${inner}
+
+<hr style="margin-top:32px;border:none;border-top:1px solid #ddd;">
+<p style="color:#888;font-size:90%;text-align:center"><a href="https://github.com/giacomo-ciro/paperino" style="color:inherit" target="_blank">paperino</a> - built by <a href="https://giacomociro.com" style="color:inherit" target="_blank">giacomo-ciro</a>, with ${HEART_SVG}</p>
+</div>`;
+}
+function card(p) {
+	return `
+<div style="margin-bottom:28px">
+  <h3 style="margin-bottom:4px"><a href="${p.link}">${escapeHtml(p.title)}</a></h3>
+  <p><b>Score: ${p.score}/10</b> — ${escapeHtml(p.summary ?? "")}</p>
+  <p><b>Key contribution:</b> ${escapeHtml(p.keyContribution ?? "")}</p>
+  <p><b>Why it matters:</b> ${escapeHtml(p.whyItMatters ?? "")}</p>
+  <p><b>Journal/Conference:</b> ${escapeHtml(p.journalRef ?? "n/a")}</p>
+  <p><b>Comment:</b> ${escapeHtml(p.comment ?? "n/a")}</p>
+  <p style="color:#555;font-size:90%">${escapeHtml(p.abstract ?? "")}</p>
+</div>`;
+}
+function lineItem(p) {
+	const tag = p.score !== void 0 ? `score ${p.score}` : "unscored";
+	return `<li><a href="${p.link}">${escapeHtml(p.title)}</a> (${tag})</li>`;
+}
+//#endregion
+//#region src/fetch.ts
+const ARXIV_API_BASE = "https://export.arxiv.org/api/query";
+const PAGE_SIZE = 100;
+const INTER_PAGE_DELAY_MS = 3e3;
+const parser = new XMLParser({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	isArray: (name) => [
+		"entry",
+		"category",
+		"author",
+		"link"
+	].includes(name),
+	removeNSPrefix: true
+});
+function toPaper(entry) {
+	const id = entry.id.replace(/^https?:\/\/arxiv\.org\/abs\//, "").replaceAll("/", "_");
+	const link = entry.link.find((l) => l["@_rel"] === "alternate")?.["@_href"] ?? entry.id;
+	return {
+		id,
+		title: entry.title.trim(),
+		abstract: entry.summary.trim(),
+		link,
+		categories: entry.category.map((c) => c["@_term"]),
+		published: entry.published,
+		journalRef: entry.journal_ref ?? null,
+		comment: entry.comment ?? null
+	};
+}
+function formatArxivDate(d) {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}`;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+* Fetch every arXiv paper in `categories` submitted within [start, end] UTC.
+* If `maxPapers` is set, only the most recently submitted N are returned.
+*/
+async function fetchRecentPapers(categories, start, end, maxPapers) {
+	const dateFilter = `submittedDate:[${formatArxivDate(start)} TO ${formatArxivDate(end)}]`;
+	const searchQuery = `(${categories.map((c) => `cat:${c}`).join(" OR ")}) AND ${dateFilter}`;
+	const papers = [];
+	let start_ = 0;
+	let totalResults = Infinity;
+	while (start_ < totalResults && (maxPapers === void 0 || papers.length < maxPapers)) {
+		if (start_ > 0) await sleep(INTER_PAGE_DELAY_MS);
+		const url = new URL(ARXIV_API_BASE);
+		url.searchParams.set("search_query", searchQuery);
+		url.searchParams.set("start", String(start_));
+		url.searchParams.set("max_results", String(PAGE_SIZE));
+		url.searchParams.set("sortBy", "submittedDate");
+		url.searchParams.set("sortOrder", "descending");
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`arXiv API request failed: ${response.status} ${response.statusText}`);
+		const xml = await response.text();
+		const parsed = parser.parse(xml);
+		totalResults = parsed.feed.totalResults;
+		const entries = parsed.feed.entry ?? [];
+		if (entries.length === 0) break;
+		for (const entry of entries) {
+			papers.push(toPaper(entry));
+			if (maxPapers !== void 0 && papers.length >= maxPapers) break;
+		}
+		start_ += entries.length;
+	}
+	return maxPapers !== void 0 ? papers.slice(0, maxPapers) : papers;
+}
+//#endregion
+//#region src/logger.ts
+function timestamp() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${`${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`} ${`${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`}`;
+}
+function makeLogger(logPath) {
+	mkdirSync(dirname(logPath), { recursive: true });
+	closeSync(openSync(logPath, "a"));
+	function write(line) {
+		appendFileSync(logPath, `[${timestamp()}] ${line}\n`, "utf-8");
+	}
+	return {
+		pipelineStart(windowCount) {
+			write(`pipeline started (${windowCount} window(s) to process)`);
+		},
+		windowStart(label) {
+			write(`processing window ${label}`);
+		},
+		stageStart(label) {
+			write(`  stage started: ${label}`);
+		},
+		callFailed(stageLabel, error) {
+			write(`  call failed: ${stageLabel} — ${error}`);
+		},
+		stageEnd(label, metrics) {
+			write(`  stage finished: ${label} — ${metrics}`);
+		},
+		pipelineEnd() {
+			write("pipeline finished");
+		}
+	};
+}
+/** Opens the log file in `less`, jumping to the end, inheriting stdio until the user quits. */
+function viewLogs(logPath) {
+	mkdirSync(dirname(logPath), { recursive: true });
+	closeSync(openSync(logPath, "a"));
+	spawnSync("less", ["+G", logPath], { stdio: "inherit" });
+}
+//#endregion
+//#region src/progress.ts
+const STAGE_LABELS = [
+	"Fetching papers",
+	"Coarse filtering",
+	"Fine filtering"
+];
+const SPINNER = cliSpinners.dots;
+const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
+/** Visible width of a line once SGR color codes are stripped. */
+function visibleWidth(line) {
+	return line.replace(ANSI_PATTERN, "").length;
+}
+/** How many physical terminal rows a line occupies once wrapped at `columns`. */
+function wrappedRows(line, columns) {
+	return Math.max(1, Math.ceil(visibleWidth(line) / columns));
+}
+/**
+* Redraws a block of lines in place on stderr, tracking how many physical
+* rows the last frame occupied (accounting for wrapping) so it can be
+* cleared cleanly before the next frame — or erased entirely via `clear()`.
+*/
+var Frame = class {
+	linesPrinted = 0;
+	draw(lines) {
+		const columns = process.stderr.columns || 80;
+		const totalRows = lines.map((line) => wrappedRows(line, columns)).reduce((sum, n) => sum + n, 0);
+		if (this.linesPrinted > 0) {
+			process.stderr.write(`\x1b[${this.linesPrinted}A`);
+			for (let i = 0; i < this.linesPrinted; i++) process.stderr.write(i === this.linesPrinted - 1 ? "\x1B[2K" : "\x1B[2K\x1B[1B");
+			if (this.linesPrinted > 1) process.stderr.write(`\x1b[${this.linesPrinted - 1}A`);
+		}
+		for (const line of lines) process.stderr.write(`${line}\n`);
+		this.linesPrinted = totalRows;
+	}
+	/**
+	* Erase everything this frame printed, leaving the cursor where the frame started.
+	* `extraLines` accounts for rows printed after the last `draw()` outside of Frame's
+	* control (e.g. the newline a TTY echoes when the user presses Enter at a prompt).
+	*/
+	clear(extraLines = 0) {
+		const rows = this.linesPrinted + extraLines;
+		if (rows === 0) return;
+		process.stderr.write(`\x1b[${rows}A`);
+		for (let i = 0; i < rows; i++) process.stderr.write(i === rows - 1 ? "\x1B[2K" : "\x1B[2K\x1B[1B");
+		if (rows > 1) process.stderr.write(`\x1b[${rows - 1}A`);
+		this.linesPrinted = 0;
+	}
+};
+const ET_TIME_ZONE$1 = "America/New_York";
+const LOCAL_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+const weekdayFormatter = new Intl.DateTimeFormat("en-US", {
+	weekday: "short",
+	timeZone: ET_TIME_ZONE$1
+});
+const etTimeFormatter = new Intl.DateTimeFormat("en-US", {
+	timeZone: ET_TIME_ZONE$1,
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+	hour: "2-digit",
+	minute: "2-digit",
+	hourCycle: "h23"
+});
+const localTimeFormatter = new Intl.DateTimeFormat("en-US", {
+	timeZone: LOCAL_TIME_ZONE,
+	hour: "2-digit",
+	minute: "2-digit",
+	hourCycle: "h23",
+	timeZoneName: "short"
+});
+/** `YYYY-MM-DD (Ddd)` in ET, for the confirmation summary. */
+function formatETDate(d) {
+	const parts = Object.fromEntries(etTimeFormatter.formatToParts(d).map((p) => [p.type, p.value]));
+	return `${`${parts.year}-${parts.month}-${parts.day}`} (${weekdayFormatter.format(d)})`;
+}
+/** `14:00 ET (your timezone: HH:mm <zone>)` — the cutoff time shared by both window boundaries. */
+function formatCutoffTime(d) {
+	const parts = Object.fromEntries(etTimeFormatter.formatToParts(d).map((p) => [p.type, p.value]));
+	const etTime = `${parts.hour}:${parts.minute} ET`;
+	if (LOCAL_TIME_ZONE === ET_TIME_ZONE$1) return etTime;
+	const localParts = Object.fromEntries(localTimeFormatter.formatToParts(d).map((p) => [p.type, p.value]));
+	return `${etTime} (your timezone: ${`${localParts.hour}:${localParts.minute} ${localParts.timeZoneName}`})`;
+}
+/**
+* Renders the run summary (windows, config, warnings) in the same visual
+* language as the stage tracker, then prompts for confirmation. The whole
+* block is wiped from the screen right before returning, so it doesn't
+* linger once the animated stage tracker takes over.
+*/
+async function confirmRun(windows, cfg, maxPapers, force, onlyFetch) {
+	const frame = new Frame();
+	const lines = [];
+	lines.push("");
+	lines.push(`${windows.length} submission window(s) to process${onlyFetch ? " (only fetching)" : ""}:`);
+	lines.push("");
+	for (const [start, end] of windows) lines.push(`  ${pc.cyan("›")} ${formatETDate(start)} ${pc.dim("->")} ${formatETDate(end)}`);
+	if (windows.length > 0) {
+		const cutoff = formatCutoffTime(windows[windows.length - 1][1]);
+		lines.push("");
+		lines.push(pc.dim(`Each window starts and ends at ${cutoff}`));
+	}
+	lines.push("");
+	const maxProcessed = maxPapers !== void 0 ? String(maxPapers) : "all";
+	lines.push(`${pc.dim("Max papers/window")}  ${maxProcessed}`);
+	if (!onlyFetch) {
+		lines.push(`${pc.dim("Coarse model")}       ${cfg.coarse.model} (${cfg.coarse.callSize} papers per call, ${cfg.coarse.maxWorkers} concurrent calls at most)`);
+		lines.push(`${pc.dim("Fine model")}         ${cfg.fine.model} (${cfg.fine.callSize} papers per call, ${cfg.fine.maxWorkers} concurrent calls at most)`);
+	}
+	if (force) {
+		lines.push("");
+		lines.push(pc.yellow("existing runs/digests for these windows will be discarded and rerun from scratch."));
+	}
+	lines.push("");
+	lines.push(pc.dim("Press Enter to proceed (any other key to abort)"));
+	frame.draw(lines);
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	let confirmed;
+	try {
+		confirmed = (await rl.question("")).trim() === "";
+	} finally {
+		rl.close();
+	}
+	frame.clear(1);
+	return confirmed;
+}
+function makePipelineView(windowLabel, stageLabels = STAGE_LABELS) {
+	let index = 0;
+	let frameNum = 0;
+	let stopped = false;
+	const text = [...stageLabels];
+	const failedStages = /* @__PURE__ */ new Set();
+	const frame = new Frame();
+	let timer;
+	function renderLine(i) {
+		const step = pc.dim(`Step ${i + 1}`);
+		if (i < index) return `${step} ${failedStages.has(i) ? pc.yellow("✓") : pc.green("✓")} ${text[i]}`;
+		if (i === index && !stopped) return `${step} ${pc.cyan(SPINNER.frames[frameNum % SPINNER.frames.length])} ${text[i]}`;
+		return pc.dim(`Step ${i + 1} ○ ${text[i]}`);
+	}
+	function draw() {
+		frame.draw(stageLabels.map((_, i) => renderLine(i)));
+	}
+	process.stderr.write(`\nProcessing window ${windowLabel}\n\n`);
+	draw();
+	timer = setInterval(() => {
+		frameNum++;
+		draw();
+	}, SPINNER.interval);
+	return {
+		update(newText) {
+			text[index] = newText;
+		},
+		complete(finalText, failed = false) {
+			text[index] = finalText;
+			if (failed) failedStages.add(index);
+			index++;
+			if (index < stageLabels.length) text[index] = stageLabels[index];
+		},
+		stop() {
+			if (timer) clearInterval(timer);
+			stopped = true;
+			draw();
+			process.stderr.write("\n");
+		}
+	};
+}
+/** Non-interactive fallback (--quiet or non-TTY stderr): no animation, no output at all. */
+function makeSilentPipelineView() {
+	return {
+		update() {},
+		complete() {},
+		stop() {}
+	};
+}
+//#endregion
+//#region src/agent/pool.ts
+async function runOnce(agent, prompt, opts) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+	try {
+		const { output } = await agent.run(prompt, {
+			model: opts.model,
+			schema: opts.schema,
+			timeoutMs: opts.timeoutMs,
+			signal: controller.signal
+		});
+		return output;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function runWithRetries(agent, prompt, index, opts) {
+	const totalAttempts = opts.retries + 1;
+	let lastError;
+	for (let attempt = 1; attempt <= totalAttempts; attempt++) try {
+		return await runOnce(agent, prompt, opts);
+	} catch (err) {
+		lastError = err;
+		if (attempt < totalAttempts) opts.onAttemptFailed?.(err instanceof Error ? err.message : String(err), index, attempt, totalAttempts);
+	}
+	return lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+/**
+* Fan `prompts` out over a concurrency-limited pool. Returns one entry per prompt,
+* in order: the parsed output, or an Error if that prompt ultimately failed after
+* retries (so one bad call can't abort the run).
+*/
+async function runPool(agent, prompts, opts) {
+	const results = new Array(prompts.length);
+	let next = 0;
+	let completed = 0;
+	async function worker() {
+		while (true) {
+			const index = next++;
+			if (index >= prompts.length) return;
+			const result = await runWithRetries(agent, prompts[index], index, opts);
+			results[index] = result;
+			completed++;
+			opts.onProgress?.(result, index, completed, prompts.length);
+		}
+	}
+	const workerCount = Math.min(opts.maxWorkers, prompts.length);
+	await Promise.all(Array.from({ length: workerCount }, () => worker()));
+	return results;
+}
+//#endregion
+//#region src/schemas.ts
+const COARSE_SCHEMA = {
+	type: "object",
+	properties: { verdicts: {
+		type: "array",
+		items: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				coarse: {
+					type: "integer",
+					enum: [0, 1]
+				}
+			},
+			required: ["id", "coarse"],
+			additionalProperties: false
+		}
+	} },
+	required: ["verdicts"],
+	additionalProperties: false
+};
+const FINE_SCHEMA = {
+	type: "object",
+	properties: { papers: {
+		type: "array",
+		items: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				score: {
+					type: "integer",
+					minimum: 1,
+					maximum: 10
+				},
+				summary: { type: "string" },
+				key_contribution: { type: "string" },
+				why_it_matters: { type: "string" }
+			},
+			required: [
+				"id",
+				"score",
+				"summary",
+				"key_contribution",
+				"why_it_matters"
+			],
+			additionalProperties: false
+		}
+	} },
+	required: ["papers"],
+	additionalProperties: false
+};
+/**
+* Replace only the two exact tokens `{research_interests}` and `{papers}` in `template`.
+* Every other brace (e.g. the prompt's inline JSON examples) is left untouched.
+*/
+function fillPrompt(template, values) {
+	return template.replaceAll("{research_interests}", values.research_interests).replaceAll("{papers}", values.papers);
+}
+//#endregion
+//#region src/scoring.ts
+/** Group items into chunks of `size`, one chunk per claude call. */
+function groupForCalls(items, size) {
+	const groups = [];
+	for (let i = 0; i < items.length; i += size) groups.push(items.slice(i, i + size));
+	return groups;
+}
+function coarseFlag(verdicts, paperId) {
+	const raw = verdicts.get(paperId);
+	const parsed = typeof raw === "number" ? raw : Number(raw);
+	return Number.isFinite(parsed) && parsed === 0 ? 0 : 1;
+}
+/** Title-only screening: mark each paper coarse: 0|1. Fail-open on errors. */
+async function coarseFilter(papers, cfg, agent, onProgress, onCallFailed) {
+	const pending = papers.filter((p) => p.coarse === void 0);
+	if (pending.length === 0) return;
+	const calls = groupForCalls(pending, cfg.coarse.callSize);
+	const prompts = calls.map((c) => fillPrompt(cfg.coarse.prompt, {
+		research_interests: cfg.researchInterests,
+		papers: c.map((p) => `${p.id} — ${p.title}`).join("\n")
+	}));
+	let papersDone = 0;
+	let kept = 0;
+	let failed = 0;
+	onProgress?.({
+		papersDone: 0,
+		papersTotal: pending.length,
+		passed: 0,
+		callsDone: 0,
+		callsTotal: calls.length,
+		failed: 0
+	});
+	await runPool(agent, prompts, {
+		model: cfg.coarse.model,
+		schema: COARSE_SCHEMA,
+		maxWorkers: cfg.coarse.maxWorkers,
+		timeoutMs: cfg.callTimeoutMs,
+		retries: cfg.callRetries,
+		onAttemptFailed: (error, _index, attempt, totalAttempts) => {
+			onCallFailed?.(`attempt ${attempt}/${totalAttempts} failed, retrying — ${error}`);
+		},
+		onProgress: (output, index, callsDone, callsTotal) => {
+			const c = calls[index];
+			const entries = output && typeof output === "object" && !Array.isArray(output) && !(output instanceof Error) ? output.verdicts : void 0;
+			const callFailed = output instanceof Error || !Array.isArray(entries);
+			if (callFailed) {
+				failed++;
+				onCallFailed?.(output instanceof Error ? output.message : "malformed output shape");
+			}
+			const verdicts = /* @__PURE__ */ new Map();
+			if (!callFailed) {
+				for (const entry of entries) if (entry && typeof entry === "object" && "id" in entry) verdicts.set(String(entry.id), entry.coarse);
+			}
+			for (const p of c) {
+				p.coarse = callFailed ? 1 : coarseFlag(verdicts, p.id);
+				if (p.coarse === 1) kept++;
+			}
+			papersDone += c.length;
+			onProgress?.({
+				papersDone,
+				papersTotal: pending.length,
+				passed: kept,
+				callsDone,
+				callsTotal,
+				failed
+			});
+		}
+	});
+}
+/** Score coarse-passed papers on title+abstract; failed calls stay unscored. */
+async function fineScoring(papers, cfg, agent, onProgress, onCallFailed) {
+	const pending = papers.filter((p) => p.coarse === 1 && p.score === void 0);
+	if (pending.length === 0) return;
+	const calls = groupForCalls(pending, cfg.fine.callSize);
+	const prompts = calls.map((c) => fillPrompt(cfg.fine.prompt, {
+		research_interests: cfg.researchInterests,
+		papers: c.map((p) => `id: ${p.id}\ntitle: ${p.title}\nabstract: ${p.abstract}`).join("\n\n")
+	}));
+	let papersDone = 0;
+	let scored = 0;
+	let failed = 0;
+	onProgress?.({
+		papersDone: 0,
+		papersTotal: pending.length,
+		passed: 0,
+		callsDone: 0,
+		callsTotal: calls.length,
+		failed: 0
+	});
+	await runPool(agent, prompts, {
+		model: cfg.fine.model,
+		schema: FINE_SCHEMA,
+		maxWorkers: cfg.fine.maxWorkers,
+		timeoutMs: cfg.callTimeoutMs,
+		retries: cfg.callRetries,
+		onAttemptFailed: (error, _index, attempt, totalAttempts) => {
+			onCallFailed?.(`attempt ${attempt}/${totalAttempts} failed, retrying — ${error}`);
+		},
+		onProgress: (output, index, callsDone, callsTotal) => {
+			const c = calls[index];
+			const entries = output && typeof output === "object" && !Array.isArray(output) && !(output instanceof Error) ? output.papers : void 0;
+			if (!(output instanceof Error) && Array.isArray(entries)) {
+				const byId = /* @__PURE__ */ new Map();
+				for (const entry of entries) if (entry && typeof entry === "object" && "id" in entry) byId.set(String(entry.id), entry);
+				for (const p of c) {
+					const entry = byId.get(p.id);
+					if (!entry) continue;
+					const score = Number(entry.score);
+					if (!Number.isFinite(score)) continue;
+					p.score = score;
+					p.summary = String(entry.summary ?? "");
+					p.keyContribution = String(entry.key_contribution ?? "");
+					p.whyItMatters = String(entry.why_it_matters ?? "");
+					scored++;
+				}
+			} else {
+				failed++;
+				onCallFailed?.(output instanceof Error ? output.message : "malformed output shape");
+			}
+			papersDone += c.length;
+			onProgress?.({
+				papersDone,
+				papersTotal: pending.length,
+				passed: scored,
+				callsDone,
+				callsTotal,
+				failed
+			});
+		}
+	});
+}
+//#endregion
+//#region src/store.ts
+/** `YYYY-MM-DD` for a UTC instant (matches Python's `strftime("%Y-%m-%d")`). */
+function formatUTCDate(d) {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+/** One directory per submission window, named by its end date (idempotent across re-runs). */
+function runDir(outDir, windowEnd) {
+	const dir = join(outDir, formatUTCDate(windowEnd));
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+/** Delete a window's run directory (papers.json, digest.html) so it reruns from scratch. */
+function clearRunDir(outDir, windowEnd) {
+	rmSync(join(outDir, formatUTCDate(windowEnd)), {
+		recursive: true,
+		force: true
+	});
+}
+function papersPath(dir) {
+	return join(dir, "papers.json");
+}
+function loadPapers(dir) {
+	const path = papersPath(dir);
+	if (!existsSync(path)) return [];
+	return JSON.parse(readFileSync(path, "utf-8"));
+}
+function savePapers(dir, papers) {
+	writeFileSync(papersPath(dir), `${JSON.stringify(papers, null, 2)}\n`, "utf-8");
+}
+/**
+* Merge freshly-fetched papers into the existing store, keyed by id.
+* Existing records (which may already carry `coarse`/`score`) win on conflict;
+* records no longer returned by fetch are kept (never deleted).
+*/
+function mergePapers(existing, fetched) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const p of existing) byId.set(p.id, p);
+	for (const p of fetched) if (!byId.has(p.id)) byId.set(p.id, p);
+	return [...byId.values()];
+}
+function writeDigest(dir, html) {
+	const path = join(dir, "digest.html");
+	writeFileSync(path, html, "utf-8");
+	return path;
+}
+//#endregion
+//#region src/window.ts
+const ET_TIME_ZONE = "America/New_York";
+const CUTOFF_HOUR = 14;
+const etFormatter = new Intl.DateTimeFormat("en-US", {
+	timeZone: ET_TIME_ZONE,
+	year: "numeric",
+	month: "2-digit",
+	day: "2-digit",
+	hour: "2-digit",
+	minute: "2-digit",
+	second: "2-digit",
+	hourCycle: "h23"
+});
+/** Convert a UTC instant to its ET wall-clock parts. */
+function utcToEtWallClock(instant) {
+	const parts = etFormatter.formatToParts(instant);
+	const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+	return {
+		year: get("year"),
+		month: get("month"),
+		day: get("day"),
+		hour: get("hour"),
+		minute: get("minute"),
+		second: get("second")
+	};
+}
+/**
+* Convert ET wall-clock parts to the UTC instant they represent.
+* Uses the offset-via-two-formatters trick: guess UTC == the wall-clock parts
+* verbatim, see how far that guess's ET rendering drifts, and correct for it.
+* One correction pass is sufficient since ET offsets only take integer-hour values.
+*/
+function etWallClockToUtc(wall) {
+	const guessMs = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second);
+	const guessAsEt = utcToEtWallClock(new Date(guessMs));
+	const driftMs = Date.UTC(guessAsEt.year, guessAsEt.month - 1, guessAsEt.day, guessAsEt.hour, guessAsEt.minute, guessAsEt.second) - guessMs;
+	return new Date(guessMs - driftMs);
+}
+/** Weekday of a wall-clock date, Mon=0 ... Sun=6 (matches Python's `date.weekday()`). */
+function weekday(wall) {
+	return (new Date(Date.UTC(wall.year, wall.month - 1, wall.day)).getUTCDay() + 6) % 7;
+}
+/** Add (or subtract, for negative n) whole calendar days to a wall-clock moment. */
+function addDays(wall, n) {
+	const d = new Date(Date.UTC(wall.year, wall.month - 1, wall.day));
+	d.setUTCDate(d.getUTCDate() + n);
+	return {
+		year: d.getUTCFullYear(),
+		month: d.getUTCMonth() + 1,
+		day: d.getUTCDate(),
+		hour: wall.hour,
+		minute: wall.minute,
+		second: wall.second
+	};
+}
+function atCutoff(wall) {
+	return {
+		...wall,
+		hour: CUTOFF_HOUR,
+		minute: 0,
+		second: 0
+	};
+}
+function addHours(wall, hours) {
+	const totalMinutes = wall.hour * 60 + wall.minute + hours * 60;
+	const dayOffset = Math.floor(totalMinutes / 1440);
+	const minutesInDay = (totalMinutes % 1440 + 1440) % 1440;
+	return {
+		...addDays(wall, dayOffset),
+		hour: Math.floor(minutesInDay / 60),
+		minute: minutesInDay % 60,
+		second: wall.second
+	};
+}
+function compareWallClock(a, b) {
+	return Date.UTC(a.year, a.month - 1, a.day, a.hour, a.minute, a.second) - Date.UTC(b.year, b.month - 1, b.day, b.hour, b.minute, b.second);
+}
+/**
+* Find the most recent submission window already announced, as of `now`.
+*
+* arXiv's daily submission-window cutoff is 14:00 ET; results are announced 20:00 ET
+* the same day, except Friday's cutoff (which covers the whole weekend) is announced
+* the following Sunday 20:00. Sat/Sun are never a window's end. A window ending on
+* Monday spans 3 days (it absorbs the weekend); every other window spans 1 day.
+*
+* Returns [start, end] as UTC Dates.
+*/
+function submissionWindow(now) {
+	const nowEt = utcToEtWallClock(now);
+	let windowEnd = atCutoff(nowEt);
+	if (compareWallClock(nowEt, windowEnd) < 0) windowEnd = addDays(windowEnd, -1);
+	for (;;) {
+		const wd = weekday(windowEnd);
+		if (wd === 5 || wd === 6) {
+			windowEnd = addDays(windowEnd, -1);
+			continue;
+		}
+		if (compareWallClock(nowEt, wd === 4 ? addHours(addDays(windowEnd, 2), 6) : addHours(windowEnd, 6)) >= 0) break;
+		windowEnd = addDays(windowEnd, -1);
+	}
+	const daysBack = weekday(windowEnd) === 0 ? 3 : 1;
+	return [etWallClockToUtc(addDays(windowEnd, -daysBack)), etWallClockToUtc(windowEnd)];
+}
+/**
+* Enumerate the windows to process for `--start-from`/`--windows`, both 1-indexed.
+* Window #1 is the latest announced window, #2 the one before it, etc.
+* `startFrom` anchors backward in time; `limit` walks forward (toward more recent)
+* from the anchor, clamped at #1 (never into the future).
+*
+* Returns windows oldest-first.
+*/
+function windowsToProcess(now, startFrom, limit) {
+	const newestIndex = Math.max(1, startFrom - (limit - 1));
+	const windows = [];
+	let [start, end] = submissionWindow(now);
+	for (let index = 1; index <= startFrom; index++) {
+		if (index >= newestIndex) windows.push([start, end]);
+		[start, end] = submissionWindow(/* @__PURE__ */ new Date(start.getTime() - 1));
+	}
+	return windows.reverse();
+}
+//#endregion
+//#region src/cli.ts
+const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8")).version;
+const program = new Command();
+function parsePositiveInteger(value) {
+	if (!/^\d+$/.test(value)) throw new InvalidArgumentError("must be a positive integer");
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isSafeInteger(parsed) || parsed < 1) throw new InvalidArgumentError("must be a positive integer (1-indexed)");
+	return parsed;
+}
+/** Most recently submitted N papers (all of them if `maxPapers` is unset). */
+function capMostRecent(papers, maxPapers) {
+	if (maxPapers === void 0 || papers.length <= maxPapers) return papers;
+	return [...papers].sort((a, b) => b.published.localeCompare(a.published)).slice(0, maxPapers);
+}
+function formatProgress(stage, p) {
+	const stageName = stage === "coarse" ? "Coarse" : "Fine";
+	const detail = stage === "coarse" ? `${p.passed}/${p.papersTotal} papers kept, ` : "";
+	return `${stageName} filtering: ${p.papersDone}/${p.papersTotal} papers processed (${detail}${p.callsDone}/${p.callsTotal} calls done, ${p.failed} failed)`;
+}
+/** Progress snapshot for a stage that had nothing pending (all papers already screened/scored). */
+function alreadyDoneProgress(papers, stage) {
+	const passed = stage === "coarse" ? papers.filter((p) => p.coarse === 1).length : papers.filter((p) => p.score !== void 0).length;
+	return {
+		papersDone: papers.length,
+		papersTotal: papers.length,
+		passed,
+		callsDone: 0,
+		callsTotal: 0,
+		failed: 0
+	};
+}
+function renderDigestHtml(subject, body) {
+	return `<!doctype html>
+<html>
+<head><meta charset="utf-8"><title>${subject}</title></head>
+<body>
+${body}
+</body>
+</html>
+`;
+}
+program.name("paperino").description("Every new arXiv paper, every day, filtered by Claude Code down to what's actually worth your time.").version(packageVersion).option("--configure", `open ${CONFIG_PATH} in your default editor.`, false).option("--email", "get the digest directly to your inbox (coming soon).", false).option("--force", "discard any existing run/digest for the given windows and rerun from scratch.", false).option("--logs", "page through the log file with less; no pipeline run.", false).option("--max-papers <n>", "cap papers processed per window, most recently submitted first (default: unlimited).", parsePositiveInteger).option("--only-fetch", "only fetch the papers from arXiv. Do NOT run the relevance-scoring pipeline.", false).option("--quiet", "suppress progress output; only print the path to the output file.", false).option("--start-from <n>", "1-indexed window to start from, most recent first .", parsePositiveInteger, 1).option("--windows <n>", "number of windows to process, walking forward from --start-from toward the present.", parsePositiveInteger, 1).option("-y, --yes", "skip the confirmation prompt and run immediately.", false).action(async (options) => {
+	if (options.email) throw new Error("email delivery is not implemented yet");
+	ensureConfig();
+	if (options.configure) {
+		openConfigInEditor();
+		return;
+	}
+	const cfg = loadConfig();
+	if (options.logs) {
+		viewLogs(cfg.logFile);
+		return;
+	}
+	const logger = makeLogger(cfg.logFile);
+	const windows = windowsToProcess(/* @__PURE__ */ new Date(), options.startFrom, options.windows);
+	const maxPapers = options.maxPapers;
+	if (!options.yes && !await confirmRun(windows, cfg, maxPapers, options.force ?? false, options.onlyFetch ?? false)) {
+		process.stderr.write(pc.dim("aborted.\n"));
+		return;
+	}
+	const agent = new ClaudeAgent(cfg.claudeBinary);
+	const outputPaths = [];
+	let hadFailures = false;
+	logger.pipelineStart(windows.length);
+	for (const [start, end] of windows) {
+		if (options.force) clearRunDir(cfg.outDir, end);
+		const dir = runDir(cfg.outDir, end);
+		const label = formatUTCDate(end);
+		logger.windowStart(label);
+		const view = options.quiet ? makeSilentPipelineView() : makePipelineView(label, options.onlyFetch ? ["Fetching papers"] : void 0);
+		logger.stageStart("Fetching papers");
+		const existing = loadPapers(dir);
+		const fetched = await fetchRecentPapers(cfg.arxivCat, start, end, maxPapers);
+		const papers = mergePapers(existing, fetched);
+		savePapers(dir, papers);
+		const toProcess = capMostRecent(papers, maxPapers);
+		const cappedNote = maxPapers !== void 0 && toProcess.length < papers.length ? ` (only scoring most recent ${toProcess.length})` : "";
+		const fetchMetrics = `Fetched ${fetched.length} papers, ${papers.length} total in store${cappedNote}`;
+		view.complete(fetchMetrics);
+		logger.stageEnd("Fetching papers", fetchMetrics);
+		if (options.onlyFetch) {
+			view.stop();
+			outputPaths.push(`${dir}/papers.json`);
+			continue;
+		}
+		logger.stageStart("Coarse filtering");
+		let lastCoarse;
+		await coarseFilter(toProcess, cfg, agent, (p) => {
+			lastCoarse = p;
+			view.update(formatProgress("coarse", p));
+		}, (err) => logger.callFailed("Coarse filtering", err));
+		const coarseProgress = lastCoarse ?? alreadyDoneProgress(toProcess, "coarse");
+		const coarseMetrics = formatProgress("coarse", coarseProgress);
+		view.complete(coarseMetrics, coarseProgress.failed > 0);
+		logger.stageEnd("Coarse filtering", coarseMetrics);
+		savePapers(dir, papers);
+		logger.stageStart("Fine filtering");
+		let lastFine;
+		await fineScoring(toProcess, cfg, agent, (p) => {
+			lastFine = p;
+			view.update(formatProgress("fine", p));
+		}, (err) => logger.callFailed("Fine filtering", err));
+		const fineProgress = lastFine ?? alreadyDoneProgress(toProcess, "fine");
+		const fineMetrics = formatProgress("fine", fineProgress);
+		view.complete(fineMetrics, fineProgress.failed > 0);
+		logger.stageEnd("Fine filtering", fineMetrics);
+		savePapers(dir, papers);
+		view.stop();
+		const { subject, body } = buildDigest(papers, label, cfg.minScore);
+		const htmlPath = writeDigest(dir, renderDigestHtml(subject, body));
+		if (coarseProgress.failed > 0 || fineProgress.failed > 0) {
+			hadFailures = true;
+			const failedCalls = coarseProgress.failed + fineProgress.failed;
+			if (!options.quiet) process.stderr.write(`${pc.yellow("⚠ Done with errors.")} ${pc.dim(`Digest may be incomplete: ${failedCalls} call(s) failed. Run`)} paperino --logs ${pc.dim("for details.")}\n${pc.dim("Digest ready at")} ${htmlPath}\n\n`);
+		} else if (!options.quiet) process.stderr.write(`${pc.green("Done.")} ${pc.dim("Digest ready at")} ${htmlPath}\n\n`);
+		outputPaths.push(htmlPath);
+	}
+	logger.pipelineEnd();
+	if (options.quiet) for (const path of outputPaths) process.stdout.write(`${path}\n`);
+	if (hadFailures) process.exitCode = 1;
+});
+program.parseAsync().catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`error: ${message}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@giacomo-ciro/paperino",
+  "version": "0.1.0",
+  "description": "",
+  "author": "giacomo-ciro",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "paperino": "dist/cli.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "node dist/cli.mjs",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "cli-spinners": "^3.4.0",
+    "commander": "^15.0.0",
+    "fast-xml-parser": "^5.10.1",
+    "ora": "^9.4.1",
+    "picocolors": "^1.1.1",
+    "smol-toml": "^1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsdown": "^0.22.9",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/giacomo-ciro/paperino"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}