lumina-wiki 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-06-16
+
+### Added
+
+- **Advanced paper ranking** via the new research-pack skill
+  `/lumi-research-rank`. It scores an already-ingested paper and records the
+  results on its source page, both as a machine-readable `ranking:` frontmatter
+  block and a human-readable `## Ranking` scorecard. Re-running refreshes the
+  ranking and preserves any notes inside `<!-- user-edited -->` markers.
+- **Citation influence signal**: surfaces Semantic Scholar's influential-citation
+  count alongside the raw citation count (reuses the existing `fetch_s2.py`; no
+  new key required).
+- **4C qualitative rubric** (Correctness, Clarity, Contribution, Context, each
+  scored 1-5) produced with a three-pass reading method to keep the assessment
+  efficient. Scores are explicitly recorded as LLM-assessed with a timestamp.
+- **Venue prestige** recorded from the agent's own knowledge and explicitly
+  flagged as an estimate (`venue_source: llm-estimated`) — no live API or
+  bundled dataset.
+- **Optional, key-gated influence fetchers** `fetch_scite.py` (Scite.ai Smart
+  Citation tallies) and `fetch_altmetric.py` (Altmetric attention score). Both
+  degrade gracefully: with no key set they exit with a clear message and the
+  skill simply skips that signal. New `.env` keys `SCITE_API_KEY` and
+  `ALTMETRIC_API_KEY`.
+
+### Changed
+
+- Source page schema gains an optional `ranking` frontmatter object (no change
+  required for existing un-ranked pages).
+
 ## [1.6.2] - 2026-06-15
 
 ### Fixed

package/README.md

@@ -185,6 +185,7 @@ These are the commands you can use when chatting with your AI agent.
 | | `/lumi-research-survey` | Create a survey or summary from existing knowledge. |
 | | `/lumi-research-prefill` | Seed foundational concepts to avoid duplicates. |
 | | `/lumi-research-topic` | Create a topic page at `wiki/topics/<slug>.md` by gathering related concepts and sources already in your wiki. The AI proposes what to include and you confirm before anything is written. Use this after several `/lumi-ingest` runs when you want to give a theme its own page. |
+| | `/lumi-research-rank` | Score a paper you have already ingested so you know what to read first. It looks up how influential the paper is (citation signals), estimates how respected its venue is, and rates its quality on four points — Correctness, Clarity, Contribution, and Context — then adds a clear scorecard to the paper's page. Measured numbers and the AI's own estimates are always kept separate. |
 | | `/lumi-research-setup` | Help configure API keys for research tools. |
 | | `/lumi-research-watch-run` | Run one scheduled-discovery pass over your watchlist (topics + RSS / Atom feeds). Polls only when you ask. |
 | **Reading** | `/lumi-reading-chapter-ingest` | Ingest a book chapter by chapter. |
@@ -209,7 +210,7 @@ Lumina-Wiki is evolving rapidly. Here is our user-facing roadmap:
 - [x] **Improved CI/CD:** Native support for Bun and Node 22 environments. *(shipped in v1.2)*
 - [x] **Global Source Expansion:** Direct integration with OpenAlex, CORE, and Unpaywall for reliable DOI-to-PDF resolution. *(shipped in v1.6)*
 - [x] **RSS & Blog Monitoring:** Automatically surface new papers from your favorite lab blogs and journals via `type: feed` watchlist items. *(shipped in v1.6)*
-- [ ] **Advanced Paper Ranking:** See influence scores and quality signals for your research papers.
+- [x] **Advanced Paper Ranking:** See influence scores and quality signals for your research papers via `/lumi-research-rank`. *(shipped in v1.7)*
 
 **Long-term (Deep Research & Integration)**
 - [ ] **Image OCR & Scanned PDFs:** Ingest screenshots and scanned PDFs into your wiki.

package/README.vi.md

@@ -185,6 +185,7 @@ Xem [Hướng dẫn Nâng cao](docs/user-guide/advanced-qmd.vi.md) để biết
 | | `/lumi-research-survey` | Tạo một bài tổng quan/khảo sát từ kiến thức hiện có. |
 | | `/lumi-research-prefill` | Tạo trước các khái niệm nền tảng để tránh trùng lặp. |
 | | `/lumi-research-topic` | Gom các khái niệm và nguồn liên quan trong wiki thành một trang chủ đề tại `wiki/topics/<slug>.md`. AI đề xuất danh sách để bạn xem và xác nhận trước khi trang được tạo. Dùng sau khi đã nạp nhiều tài liệu và muốn tổng hợp một nhóm ý tưởng thành trang riêng. |
+| | `/lumi-research-rank` | Chấm điểm một bài báo bạn đã nạp để biết nên đọc gì trước. Nó tra mức độ ảnh hưởng của bài (tín hiệu trích dẫn), ước lượng uy tín nơi công bố, và đánh giá chất lượng theo bốn tiêu chí — Tính đúng đắn, Sự rõ ràng, Đóng góp, và Bối cảnh — rồi thêm một bảng điểm rõ ràng vào trang của bài báo. Các con số đo được và ước lượng của AI luôn được tách bạch. |
 | | `/lumi-research-setup` | Giúp cấu hình API key cho các công cụ nghiên cứu. |
 | | `/lumi-research-watch-run` | Chạy một lượt khám phá theo lịch dựa trên watchlist (chủ đề + nguồn RSS / Atom). Chỉ chạy khi bạn yêu cầu. |
 | **Reading** | `/lumi-reading-chapter-ingest`| Nạp kiến thức sách theo từng chương. |
@@ -209,7 +210,7 @@ Lumina-Wiki đang phát triển nhanh chóng. Dưới đây là lộ trình hư
 - [x] **Cải thiện CI/CD:** Hỗ trợ chính thức cho môi trường Bun và Node 22. *(đã phát hành trong v1.2)*
 - [x] **Mở rộng nguồn dữ liệu toàn cầu:** Tích hợp trực tiếp với OpenAlex, CORE và Unpaywall để tra cứu DOI-to-PDF đáng tin cậy. *(ra mắt trong v1.6)*
 - [x] **Theo dõi RSS & Blog:** Tự động phát hiện bài báo mới từ các blog phòng thí nghiệm và tạp chí yêu thích qua các mục `type: feed` trong watchlist. *(ra mắt trong v1.6)*
-- [ ] **Xếp hạng bài báo nâng cao:** Xem điểm số ảnh hưởng và tín hiệu chất lượng cho các nghiên cứu của bạn.
+- [x] **Xếp hạng bài báo nâng cao:** Xem điểm số ảnh hưởng và tín hiệu chất lượng cho các nghiên cứu của bạn qua `/lumi-research-rank`. *(ra mắt ở v1.7)*
 
 **Dài hạn (Nghiên cứu sâu & Tích hợp)**
 - [ ] **OCR ảnh & PDF scan:** Nạp ảnh chụp màn hình và PDF dạng scan vào wiki.

package/README.zh.md

@@ -186,6 +186,7 @@ npx skills add https://github.com/tobi/qmd --skill qmd
 | | `/lumi-research-survey` | 从现有知识创建综述/调研。 |
 | | `/lumi-research-prefill` | 预先生成基础概念，避免重复。 |
 | | `/lumi-research-topic` | 把 wiki 中已有的相关概念和来源汇聚成一个主题页，保存在 `wiki/topics/<slug>.md`。AI 会提议收录哪些内容，由你确认后再生成页面。多次 `/lumi-ingest` 之后，用它把一组相关想法整理成独立的主题页。 |
+| | `/lumi-research-rank` | 给已经纳入的论文打分，帮你决定先读哪一篇。它会查询论文的影响力（引用信号）、估计发表场所的声望，并从四个方面评估质量——正确性、清晰度、贡献、背景——然后在论文页面上加上一份清晰的评分卡。实测数据与 AI 的估计始终分开标注。 |
 | | `/lumi-research-setup` | 帮助配置研究工具的 API key。 |
 | | `/lumi-research-watch-run` | 基于 watchlist 运行一次计划式发现（主题 + RSS / Atom 源）。仅在你要求时才运行。 |
 | **Reading** | `/lumi-reading-chapter-ingest`| 按章节导入书籍知识。 |
@@ -210,7 +211,7 @@ Lumina-Wiki 正在快速演进。这是我们的用户路线图：
 - [x] **改进的 CI/CD：** 正式支持 Bun 和 Node 22 环境。*（v1.2 已发布）*
 - [x] **全球数据源扩展：** 直接集成 OpenAlex、CORE 和 Unpaywall，实现可靠的 DOI-to-PDF 解析。*（在 v1.6 中发布）*
 - [x] **RSS 与博客监控：** 通过 watchlist 中的 `type: feed` 项，自动从您喜爱的实验室博客和期刊中发现新论文。*（在 v1.6 中发布）*
-- [ ] **高级论文排名：** 查看研究论文的影响力评分和质量信号。
+- [x] **高级论文排名：** 通过 `/lumi-research-rank` 查看研究论文的影响力评分和质量信号。*（在 v1.7 中发布）*
 
 **长期计划（深度研究与集成）**
 - [ ] **图片 OCR 与扫描 PDF：** 将截图与扫描版 PDF 导入维基。

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "lumina-wiki",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.",
   "keywords": [
     "llm-wiki",
@@ -69,6 +69,8 @@
     "src/tools/fetch_core.py",
     "src/tools/resolve_pdf.py",
     "src/tools/fetch_rss.py",
+    "src/tools/fetch_scite.py",
+    "src/tools/fetch_altmetric.py",
     "src/tools/id_utils.py",
     "src/tools/requirements.txt",
     "CHANGELOG.md",

package/src/installer/commands.js

@@ -131,7 +131,7 @@ const RESEARCH_TOOL_FILES = [
   '_env.py', '_cache.py', 'discover.py', 'init_discovery.py', 'prepare_source.py',
   'fetch_arxiv.py', 'fetch_wikipedia.py', 'fetch_s2.py', 'fetch_deepxiv.py',
   'fetch_openalex.py', 'fetch_unpaywall.py', 'fetch_core.py', 'resolve_pdf.py',
-  'fetch_rss.py',
+  'fetch_rss.py', 'fetch_scite.py', 'fetch_altmetric.py',
 ];
 
 async function findEnclosingWorkspace(startDir) {
@@ -1234,6 +1234,7 @@ function getSkillDefs(packs) {
       { name: 'prefill',  canonicalId: 'lumi-research-prefill',  displayName: '/lumi-research-prefill' },
       { name: 'setup',    canonicalId: 'lumi-research-setup',    displayName: '/lumi-research-setup' },
       { name: 'topic',     canonicalId: 'lumi-research-topic',     displayName: '/lumi-research-topic' },
+      { name: 'rank',      canonicalId: 'lumi-research-rank',      displayName: '/lumi-research-rank' },
       { name: 'watchlist', canonicalId: 'lumi-research-watchlist', displayName: '/lumi-research-watchlist' },
       { name: 'watch-run', canonicalId: 'lumi-research-watch-run', displayName: '/lumi-research-watch-run' },
     ];
@@ -1322,6 +1323,10 @@ async function renderEnvExample(projectRoot) {
       `OPENALEX_API_KEY=\n\n` +
       `# DeepXiv token (optional; enables full-text PDF access)\n` +
       `DEEPXIV_TOKEN=\n\n` +
+      `# Scite.ai API key (optional; enables Smart Citation tallies in /lumi-research-rank)\n` +
+      `SCITE_API_KEY=\n\n` +
+      `# Altmetric API key (optional; enables attention scores in /lumi-research-rank)\n` +
+      `ALTMETRIC_API_KEY=\n\n` +
       `# arXiv does not require an API key in v0.1\n`;
   }
   await atomicWrite(destPath, content);

package/src/scripts/schemas.mjs

@@ -283,6 +283,7 @@ export const REQUIRED_FRONTMATTER = {
     { key: 'findings',     type: 'array', required: false },
     { key: 'external_ids', type: 'object', required: false },
     { key: 'sources',      type: 'array',  required: false },
+    { key: 'ranking',      type: 'object', required: false },
   ],
 
   // Concept page

package/src/skills/packs/research/rank/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: lumi-research-rank
+description: >
+  Score an already-ingested paper's influence and quality. Fetches citation
+  influence (and optional Scite/Altmetric signals when keys are set), estimates
+  venue prestige, and runs a structured 4C quality assessment, then writes a
+  transparent ranking block onto the source page. Helps prioritize what to read
+  next.
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+---
+
+# /lumi-research-rank
+
+## Role
+
+You are the wiki's paper-ranking assistant. For one or more source pages the
+user names, you gather influence signals and produce a short quality scorecard,
+then record them on the source page so the user can prioritize their reading.
+You score papers; you never change a paper's summary, claims, or other content.
+
+## Context
+
+Read `README.md` first. This skill is available only when the research pack is
+installed. It works on papers already in `wiki/sources/`; if a paper has not
+been ingested yet, suggest `/lumi-ingest` first.
+
+Every figure you record must say where it came from and when. Influence numbers
+come from APIs (Semantic Scholar always; Scite and Altmetric only when the user
+has set keys). Venue prestige and the 4C quality scores come from your own
+judgment — always mark those as estimates, never as authoritative facts.
+
+References:
+- Read `references/three-pass.md` before reading the paper, to keep the
+  assessment efficient.
+- Read `references/4c-rubric.md` before scoring quality.
+
+## Instructions
+
+1. **Resolve the target.** Take the slug(s) the user named. To confirm a slug
+   exists and read its identifiers:
+
+   ```bash
+   node _lumina/scripts/wiki.mjs read-meta <slug>
+   ```
+
+   Note the `external_ids` block. You need an `s2` id, `doi`, or `arxiv` id for
+   the influence lookup, and a `doi` for the optional Scite/Altmetric lookups.
+   If none are present, you can still do the qualitative 4C assessment — just
+   tell the user the influence numbers are unavailable.
+
+2. **Fetch citation influence (uses the optional Semantic Scholar key).**
+
+   ```bash
+   python3 _lumina/tools/fetch_s2.py paper <s2-id|arXiv:ID|DOI:ID>
+   ```
+
+   From the result, keep `influentialCitationCount`, `citationCount`, and the
+   `journal` name. These become `influential_citations`, `citation_count`, and
+   the venue hint, with `citation_source: semantic-scholar`.
+
+   This tool needs `SEMANTIC_SCHOLAR_API_KEY`. If it is not set, the tool exits
+   with a clear "no key set" message (exit code 2) — treat this exactly like the
+   optional signals in step 3: skip the citation-influence numbers, continue
+   with the qualitative assessment, and tell the user that influence figures are
+   unavailable until they add the key (offer `/lumi-research-setup`). Do not
+   abort the ranking over a missing S2 key.
+
+3. **Optional key-gated signals.** Only attempt these when the paper has a DOI.
+   Each tool exits with a clear "no key set" message (exit code 2) when the key
+   is missing — if that happens, skip the signal silently and continue; do not
+   treat it as an error or ask the user to add a key unless they want it.
+
+   ```bash
+   python3 _lumina/tools/fetch_scite.py tally <doi>
+   python3 _lumina/tools/fetch_altmetric.py doi <doi>
+   ```
+
+   A `found: false` result means the service has no data for that paper — record
+   nothing for that signal rather than zeros.
+
+4. **Estimate venue prestige from your own knowledge.** Using the journal or
+   conference name, state a tier such as "CORE A*", "SJR Q1", or "top-tier
+   workshop" if you are reasonably confident. This is your estimate, not a
+   looked-up fact: always set `venue_source: llm-estimated`. If you are unsure,
+   leave the venue tier out rather than guess.
+
+5. **Assess quality (4C rubric).** Follow `references/three-pass.md` to read the
+   paper efficiently, then score Correctness, Clarity, Contribution, and Context
+   from 1 to 5 each per `references/4c-rubric.md`. Keep a one-line rationale for
+   each score.
+
+6. **Write the ranking block.** Assemble a flat object of the values you have
+   (omit keys you do not) and store it on the page. Use `--json-value`:
+
+   ```bash
+   node _lumina/scripts/wiki.mjs set-meta <slug> ranking '{
+     "influential_citations": 42,
+     "citation_count": 318,
+     "citation_source": "semantic-scholar",
+     "citation_fetched": "YYYY-MM-DD",
+     "venue_name": "NeurIPS",
+     "venue_tier": "CORE A*",
+     "venue_source": "llm-estimated",
+     "venue_estimated": "YYYY-MM-DD",
+     "scite_supporting": 12,
+     "scite_contrasting": 1,
+     "scite_mentioning": 64,
+     "scite_fetched": "YYYY-MM-DD",
+     "altmetric_score": 287,
+     "altmetric_fetched": "YYYY-MM-DD",
+     "quality_correctness": 4,
+     "quality_clarity": 5,
+     "quality_contribution": 4,
+     "quality_context": 3,
+     "quality_source": "llm",
+     "quality_assessed": "YYYY-MM-DD"
+   }' --json-value
+   ```
+
+   Use today's date (`node _lumina/scripts/wiki.mjs read-meta` output or the
+   system date) for the `_fetched` / `_assessed` / `_estimated` fields. The
+   `ranking` field is a one-level map of plain values — do not nest objects
+   inside it.
+
+7. **Write the human-readable scorecard.** The `## Ranking` section holds a
+   **managed region** bounded by marker comments:
+
+   ```markdown
+   ## Ranking
+
+   <!-- lumina:ranking -->
+   (influence numbers and the 4C scorecard with one-line rationales go here)
+   <!-- /lumina:ranking -->
+   ```
+
+   Refresh rules, so re-running is safe in any session:
+   - If the markers already exist, **replace only the text between them** with
+     the new scorecard. Use `Edit` with the whole marked block (markers
+     included) as the search target so you never create a second `## Ranking`.
+   - If the section does not exist yet, add it once, with both markers.
+   - **Never write inside or remove `<!-- user-edited -->` blocks**, and keep any
+     user prose that sits *outside* the `lumina:ranking` markers untouched.
+
+   Put the influence figures and their dates inside the managed region so the
+   provenance is visible to a reader who never opens the frontmatter.
+
+8. **Log the activity.**
+
+   ```bash
+   node _lumina/scripts/wiki.mjs log lumi-research-rank "ranked <slug>: infl=<n>, 4C=<c/c/c/c>"
+   ```
+
+9. **Report to the user in plain language.** Summarize what you found — how
+   influential the paper is, any quality concerns from the 4C pass, and where it
+   sits relative to other ranked papers if you know. Clearly separate measured
+   numbers from your own estimates. Do not present your venue guess or 4C scores
+   as hard facts.
+
+## Boundaries
+
+- Ranking is **additive metadata**. Do not edit the summary, key claims,
+  evidence, links, or any other section of the source page.
+- Do not create new pages, graph edges, or index entries.
+- Do not invent citation numbers. If an API returns nothing, say the number is
+  unavailable rather than recording a zero.
+- Re-running on the same paper refreshes the ranking; it must not duplicate the
+  `## Ranking` section or clobber user notes.

package/src/skills/packs/research/rank/references/4c-rubric.md

@@ -0,0 +1,62 @@
+# The 4C Quality Rubric
+
+Score each of the four dimensions from **1 to 5**. These are *your* qualitative
+judgments, not measured facts — record them with `quality_source: llm` and keep
+one short rationale per score. When the evidence for a dimension is thin (e.g.
+you only read the abstract), score conservatively and say so.
+
+| Score | Meaning            |
+|-------|--------------------|
+| 5     | Exceptional        |
+| 4     | Strong             |
+| 3     | Adequate / typical |
+| 2     | Weak               |
+| 1     | Poor / unreliable  |
+
+## Correctness — *Is the work sound?*
+
+Methodological integrity and the absence of obvious flaws. Look for: sensible
+experimental design, appropriate baselines and ablations, honest treatment of
+limitations, claims that are actually supported by the evidence presented,
+reproducibility signals (released code/data, clear hyperparameters).
+
+Lower the score for: overclaiming beyond the evidence, missing baselines,
+cherry-picked results, statistical weaknesses, or unaddressed confounds.
+
+## Clarity — *Can a reader follow it?*
+
+Logical flow and presentation quality. Look for: a clear problem statement, a
+readable structure, well-labeled figures and tables, defined notation, and a
+contribution that is easy to state in one sentence.
+
+Lower the score for: disorganized structure, undefined terms, figures that do
+not support the text, or a thesis you have to reconstruct yourself.
+
+## Contribution — *Does it matter?*
+
+Novelty and impact on the field. Look for: a genuinely new idea, method, result,
+dataset, or synthesis; a meaningful improvement over prior work; usefulness to
+other researchers or practitioners.
+
+Lower the score for: incremental tweaks framed as breakthroughs, results already
+well established elsewhere, or a contribution that is hard to identify.
+
+## Context — *Is it well situated?*
+
+Quality of citations and relationship to prior work. Look for: fair and
+reasonably complete related-work coverage, accurate characterization of what
+came before, and a clear positioning of this work against it.
+
+Lower the score for: thin or one-sided citations, ignoring obvious prior art, or
+mischaracterizing competing approaches.
+
+## Recording
+
+The four scores go into the `ranking` frontmatter as
+`quality_correctness`, `quality_clarity`, `quality_contribution`,
+`quality_context`, plus `quality_source: llm` and `quality_assessed: <date>`.
+The rationales go into the human-readable `## Ranking` section, not the
+frontmatter.
+
+Do **not** invent a single "overall" number. The four dimensions are reported
+separately so a reader can weigh them for their own purpose.

package/src/skills/packs/research/rank/references/three-pass.md

@@ -0,0 +1,40 @@
+# Three-Pass Reading for Efficient Assessment
+
+Do not read a whole paper end-to-end before scoring it. Use the three-pass
+method to spend context budget where it matters and to stop early when the paper
+clearly does not warrant a deep read.
+
+## Pass 1 — Shallow overview (always)
+
+Read only: title, abstract, section headings, figures/tables captions, and the
+conclusion. Goal: understand the claimed contribution and the shape of the
+evidence.
+
+After Pass 1 you should be able to draft a *provisional* Contribution and
+Clarity score and decide whether a deeper read is worthwhile. If the paper is
+clearly out of scope for the user's interest, stop here and tell them — record
+only the influence numbers and a note that quality was not deeply assessed.
+
+## Pass 2 — Targeted read (usual depth)
+
+Read the introduction, the method/approach, the main results, and the
+related-work section. Skim proofs and appendices. Goal: judge whether the claims
+are supported and whether prior work is fairly situated.
+
+Pass 2 is normally enough to finalize all four 4C scores with confidence.
+
+## Pass 3 — Deep read (only when needed)
+
+Reserve for papers that are central to the user's work, surprising, or where
+correctness is in doubt. Re-derive key arguments, scrutinize assumptions, and
+check whether the experiments actually test the claims. Goal: a defensible
+Correctness score for a paper that matters.
+
+## Budgeting
+
+- Most papers: Pass 1 + Pass 2.
+- Skip to a Pass-1-only verdict for clearly off-topic or low-relevance papers.
+- Escalate to Pass 3 sparingly — it is the most expensive.
+
+If you only completed Pass 1, say so in your report and score conservatively;
+do not present a shallow read as a thorough evaluation.

package/src/templates/.env.example

@@ -14,5 +14,13 @@ OPENALEX_API_KEY=
 # Obtain at: https://deepxiv.com
 DEEPXIV_TOKEN=
 
+# Scite.ai API key (optional; enables Smart Citation tallies in /lumi-research-rank)
+# Obtain at: https://scite.ai/apis
+SCITE_API_KEY=
+
+# Altmetric API key (optional; enables attention scores in /lumi-research-rank)
+# Obtain at: https://www.altmetric.com/products/altmetric-api/
+ALTMETRIC_API_KEY=
+
 # arXiv does not require an API key in v0.1.
 # The fetcher uses the public XML API at export.arxiv.org.

package/src/templates/README.md

@@ -197,7 +197,7 @@ Skills live in `.agents/skills/` and are invoked via slash commands. Active inst
 
 {{#if pack_research}}### Pack: research
 
-Adds `/lumi-research-discover` (ranked candidate shortlist), `/lumi-research-watchlist` (choose topics for scheduled discovery with AI help), `/lumi-research-watch-run` (run one scheduled-discovery pass over the watchlist — topics + RSS / Atom feeds — only when you ask), `/lumi-research-survey` (narrative synthesis), `/lumi-research-prefill` (seed foundations/ to prevent concept duplication), `/lumi-research-topic` (cluster existing concepts and sources into a thematic topic page; AI proposes the cluster from the graph, you confirm before anything is written), `/lumi-research-setup` (interactive API key configuration).
+Adds `/lumi-research-discover` (ranked candidate shortlist), `/lumi-research-watchlist` (choose topics for scheduled discovery with AI help), `/lumi-research-watch-run` (run one scheduled-discovery pass over the watchlist — topics + RSS / Atom feeds — only when you ask), `/lumi-research-survey` (narrative synthesis), `/lumi-research-prefill` (seed foundations/ to prevent concept duplication), `/lumi-research-topic` (cluster existing concepts and sources into a thematic topic page; AI proposes the cluster from the graph, you confirm before anything is written), `/lumi-research-rank` (score an already-ingested paper's citation influence and 4C quality, recorded on its source page; optional Scite/Altmetric signals when keys are set), `/lumi-research-setup` (interactive API key configuration).
 {{/if}}
 {{#if pack_reading}}### Pack: reading
 

package/src/templates/README.vi.md

@@ -196,7 +196,7 @@ Các skill nằm trong `.agents/skills/` và được gọi qua lệnh slash. C
 
 {{#if pack_research}}### Gói: research
 
-Thêm `/lumi-research-discover` (danh sách ứng viên được xếp hạng), `/lumi-research-watchlist` (chọn chủ đề để khám phá theo lịch với sự hỗ trợ AI), `/lumi-research-watch-run` (chạy một lượt khám phá theo lịch trên watchlist — chủ đề + nguồn RSS / Atom — chỉ khi bạn yêu cầu), `/lumi-research-survey` (tổng hợp dạng tường thuật), `/lumi-research-prefill` (tạo nền tảng để ngăn trùng lặp khái niệm), `/lumi-research-topic` (nhóm các khái niệm và nguồn hiện có thành trang chủ đề; AI đề xuất cụm từ đồ thị, bạn xác nhận trước khi ghi bất cứ thứ gì), `/lumi-research-setup` (cấu hình API key tương tác).
+Thêm `/lumi-research-discover` (danh sách ứng viên được xếp hạng), `/lumi-research-watchlist` (chọn chủ đề để khám phá theo lịch với sự hỗ trợ AI), `/lumi-research-watch-run` (chạy một lượt khám phá theo lịch trên watchlist — chủ đề + nguồn RSS / Atom — chỉ khi bạn yêu cầu), `/lumi-research-survey` (tổng hợp dạng tường thuật), `/lumi-research-prefill` (tạo nền tảng để ngăn trùng lặp khái niệm), `/lumi-research-topic` (nhóm các khái niệm và nguồn hiện có thành trang chủ đề; AI đề xuất cụm từ đồ thị, bạn xác nhận trước khi ghi bất cứ thứ gì), `/lumi-research-rank` (chấm điểm mức độ ảnh hưởng trích dẫn và chất lượng 4C của một bài báo đã nạp, ghi vào trang nguồn của nó; có thêm tín hiệu Scite/Altmetric khi đã đặt key), `/lumi-research-setup` (cấu hình API key tương tác).
 {{/if}}
 {{#if pack_reading}}### Gói: reading
 

package/src/templates/README.zh.md

@@ -197,7 +197,7 @@
 
 {{#if pack_research}}### 包：research
 
-添加 `/lumi-research-discover`（排名候选人简短列表）、`/lumi-research-watchlist`（借助 AI 为定期发现选择主题）、`/lumi-research-watch-run`（基于 watchlist 运行一次计划式发现——主题 + RSS / Atom 源——仅在您要求时执行）、`/lumi-research-survey`（叙事综合）、`/lumi-research-prefill`（播种基础知识以防止概念重复）、`/lumi-research-topic`（将现有概念和来源聚类为主题页面；AI 从图谱中提出聚类，您在写入任何内容之前确认）、`/lumi-research-setup`（交互式 API 密钥配置）。
+添加 `/lumi-research-discover`（排名候选人简短列表）、`/lumi-research-watchlist`（借助 AI 为定期发现选择主题）、`/lumi-research-watch-run`（基于 watchlist 运行一次计划式发现——主题 + RSS / Atom 源——仅在您要求时执行）、`/lumi-research-survey`（叙事综合）、`/lumi-research-prefill`（播种基础知识以防止概念重复）、`/lumi-research-topic`（将现有概念和来源聚类为主题页面；AI 从图谱中提出聚类，您在写入任何内容之前确认）、`/lumi-research-rank`（为已纳入的论文评估引用影响力和 4C 质量，记录到其来源页面；设置密钥后还可加入 Scite/Altmetric 信号）、`/lumi-research-setup`（交互式 API 密钥配置）。
 {{/if}}
 {{#if pack_reading}}### 包：reading
 

package/src/templates/_lumina/schema/lumi-help.csv

@@ -14,6 +14,7 @@ lumi-research-watchlist,RW,research,anytime,,lumi-research-discover,false,,_lumi
 lumi-research-watch-run,RWR,research,anytime,lumi-research-watchlist,,false,,raw/discovered/**,run one scheduled-discovery pass over the watchlist (topics + RSS / Atom feeds)
 lumi-research-survey,RV,research,3-query,lumi-ingest,,false,,wiki/summary/**,narrative synthesis across a topic's sources
 lumi-research-topic,RT,research,3-query,lumi-ingest,,false,,wiki/topics/**,cluster concepts and sources into a thematic topic page
+lumi-research-rank,RR,research,3-query,lumi-ingest,,false,[source-slug],wiki/sources/**,"score a paper's citation influence and 4C quality, recorded on its source page"
 lumi-research-setup,RSS,research,anytime,,,false,,.env,interactive API key configuration
 {{/if}}
 {{#if pack_reading}}

package/src/templates/_lumina/schema/page-templates.md

@@ -19,6 +19,28 @@ source_type: paper   # paper | article | book | podcast | note | other
 importance: 3        # 1=niche  2=useful  3=field-standard  4=influential  5=seminal
 confidence: high     # high | medium | low
 tags: []
+ranking:             # optional; written by /lumi-research-rank. Omit until the paper is ranked.
+  # Flat map of scalars (one level only, like external_ids). Only include keys you have.
+  influential_citations: 42   # Semantic Scholar influentialCitationCount
+  citation_count: 318         # Semantic Scholar citationCount
+  citation_source: semantic-scholar
+  citation_fetched: YYYY-MM-DD
+  venue_name: "NeurIPS"
+  venue_tier: "CORE A*"       # free-form; agent-estimated, NOT authoritative
+  venue_source: llm-estimated
+  venue_estimated: YYYY-MM-DD
+  scite_supporting: 12        # only when SCITE_API_KEY is set
+  scite_contrasting: 1
+  scite_mentioning: 64
+  scite_fetched: YYYY-MM-DD
+  altmetric_score: 287        # only when ALTMETRIC_API_KEY is set
+  altmetric_fetched: YYYY-MM-DD
+  quality_correctness: 4      # 4C rubric, 1-5 each (LLM-assessed)
+  quality_clarity: 5
+  quality_contribution: 4
+  quality_context: 3
+  quality_source: llm
+  quality_assessed: YYYY-MM-DD
 ---
 ```
 
@@ -30,6 +52,7 @@ tags: []
 - `## Related sources` — wikilinks to other source pages
 - `## People` — wikilinks to person pages
 - `## Open questions` — unanswered questions this source raises
+- `## Ranking` — *(optional; managed by `/lumi-research-rank`)* human-readable influence signals and the 4C quality scorecard (Correctness, Clarity, Contribution, Context) with one-line rationales. Each figure states its source and date. The scorecard lives inside a managed region bounded by `<!-- lumina:ranking -->` and `<!-- /lumina:ranking -->`; only that region is rewritten on refresh. Free-text notes you add outside those markers (or inside `<!-- user-edited -->` markers) are preserved.
 - `## Notes` — free-form notes (user-owned; mark with `<!-- user-edited -->` to preserve on upgrade)
 
 ---

package/src/tools/fetch_altmetric.py

@@ -0,0 +1,229 @@
+"""
+fetch_altmetric.py — Altmetric attention-score wrapper.
+
+CLI:
+    python fetch_altmetric.py doi <doi>
+
+Surfaces the Altmetric attention score and the broad social/news engagement
+counts for a publication, used by /lumi-research-rank as a non-citation
+influence signal.
+
+Requires ALTMETRIC_API_KEY in the environment (via _env.load_env()). The signal
+is key-gated: when the key is absent the tool exits 2 with an actionable message
+so the skill can skip this signal and continue. JSON emitted to stdout on
+success.
+
+Exit codes:
+    0  success (includes the "no Altmetric data for this DOI" case, found=false)
+    2  user error (missing key, bad/empty DOI) — actionable
+    3  internal/transient error (network, API 5xx) — includes retry hint
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+# Import HTTP cache helper at module load (before any test patches requests.Session)
+from _cache import wrap_session
+from id_utils import normalize_external_id
+
+# Import env loader using relative path for portability when installed
+try:
+    from _env import load_env
+except ImportError:
+    import importlib.util
+    _spec = importlib.util.spec_from_file_location(
+        "_env", Path(__file__).parent / "_env.py"
+    )
+    _mod = importlib.util.module_from_spec(_spec)  # type: ignore[arg-type]
+    _spec.loader.exec_module(_mod)  # type: ignore[union-attr]
+    load_env = _mod.load_env
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+ALTMETRIC_API_BASE = "https://api.altmetric.com/v1"
+REQUEST_TIMEOUT = 30
+
+ENV_KEY_NAME = "ALTMETRIC_API_KEY"
+KEY_OBTAIN_URL = "https://www.altmetric.com/products/altmetric-api/"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _get_api_key() -> str:
+    """Load and return the Altmetric API key.
+
+    Raises SystemExit(2) with an actionable message if missing.
+    """
+    env = load_env()
+    key = env.get(ENV_KEY_NAME, "").strip()
+    if not key:
+        _err(
+            f"Error: {ENV_KEY_NAME} is not set.\n"
+            f"Altmetric attention is an optional, key-gated ranking signal.\n"
+            f"Set it in your project .env file or ~/.env:\n"
+            f"  {ENV_KEY_NAME}=<your-key>\n"
+            f"Obtain an API key at: {KEY_OBTAIN_URL}"
+        )
+        sys.exit(2)
+    return key
+
+
+def _clean_doi(raw: str) -> str:
+    """Validate and normalize a DOI; SystemExit(2) on an invalid value."""
+    r = normalize_external_id("doi", raw)
+    if not r["valid"] or not r["id"]:
+        _err(f"Error: {raw!r} is not a valid DOI (expected form like 10.1234/abcd).")
+        sys.exit(2)
+    return r["id"]
+
+
+def _make_session() -> requests.Session:
+    session = requests.Session()
+    session.headers.update({
+        "User-Agent": "lumina-wiki/0.1 (research-pack; altmetric fetcher)",
+    })
+    # Strip the secret `key` query param from the cache key so the credential is
+    # never part of the on-disk cache slot and rotating the key still hits the
+    # same cache entry (mirrors fetch_openalex.py / fetch_unpaywall.py).
+    return wrap_session(session, namespace="altmetric", strip_params=["key"])
+
+
+def _handle_response_errors(resp: requests.Response, context: str) -> None:
+    """Check for API-level errors and raise appropriate exceptions.
+
+    404 is NOT raised here — a DOI with no Altmetric attention is a normal
+    "no data" outcome handled by the caller, not an error.
+
+    ValueError -> exit 2 (request problem); RuntimeError -> exit 3 (transient).
+    """
+    if resp.status_code == 404:
+        return
+    if resp.status_code in (401, 403):
+        raise ValueError(f"Altmetric rejected the API key (HTTP {resp.status_code}). Check ALTMETRIC_API_KEY.")
+    if resp.status_code == 429:
+        raise RuntimeError("Rate limit exceeded. Wait before retrying.")
+    if resp.status_code >= 500:
+        raise RuntimeError(f"Altmetric API returned HTTP {resp.status_code}")
+    if 400 <= resp.status_code < 500:
+        # Any other 4xx is a request-shape problem, not a transient one.
+        raise ValueError(f"Altmetric rejected the request for {context} (HTTP {resp.status_code}).")
+    resp.raise_for_status()
+
+
+def _parse_json(resp: requests.Response, context: str) -> dict[str, Any] | None:
+    """Parse a JSON object body. Returns None when the body is JSON but not an
+    object (treated as "no usable data"). A non-JSON body is a server-side
+    problem and is raised as RuntimeError -> exit 3, not mislabeled exit 2.
+    """
+    try:
+        data = resp.json()
+    except ValueError as exc:
+        raise RuntimeError(f"Altmetric returned a non-JSON body for {context}: {exc}") from exc
+    return data if isinstance(data, dict) else None
+
+
+# ---------------------------------------------------------------------------
+# Core fetch
+# ---------------------------------------------------------------------------
+
+def fetch_doi(doi: str, api_key: str, session: requests.Session) -> dict[str, Any]:
+    """Fetch the Altmetric record for a single DOI.
+
+    Returns a normalized dict. When the DOI has no Altmetric attention, returns
+    {"found": False, "doi": doi} rather than raising.
+    """
+    url = f"{ALTMETRIC_API_BASE}/doi/{quote(doi, safe='/')}"
+    resp = session.get(url, params={"key": api_key}, timeout=REQUEST_TIMEOUT)
+    _handle_response_errors(resp, f"attention for '{doi}'")
+    if resp.status_code == 404:
+        return {"found": False, "doi": doi}
+
+    raw = _parse_json(resp, f"attention for '{doi}'")
+    if raw is None:
+        # 200 with no usable attention object — treat as no data, not zeros.
+        return {"found": False, "doi": doi}
+
+    result: dict[str, Any] = {
+        "found": True,
+        "doi": raw.get("doi", doi),
+        "source": "altmetric.com",
+    }
+    # Only surface fields the API actually returned — never fabricate zeros that
+    # the ranking skill would record as provenance-bearing facts.
+    for key in (
+        "score", "readers_count", "cited_by_posts_count",
+        "cited_by_tweeters_count", "cited_by_msm_count", "details_url",
+    ):
+        if raw.get(key) is not None:
+            result[key] = raw[key]
+    return result
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="fetch_altmetric.py",
+        description="Fetch Altmetric attention data. Requires ALTMETRIC_API_KEY.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    d = subparsers.add_parser("doi", help="Fetch attention data for a DOI.")
+    d.add_argument("doi", help="DOI of the publication (e.g. 10.1234/abcd).")
+
+    args = parser.parse_args(argv)
+
+    if not args.doi.strip():
+        _err("Error: DOI must not be empty.")
+        sys.exit(2)
+    doi = _clean_doi(args.doi.strip())
+
+    api_key = _get_api_key()
+    session = _make_session()
+
+    try:
+        result = fetch_doi(doi, api_key, session)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        sys.exit(0)
+    except ValueError as exc:
+        _err(f"Error: {exc}")
+        sys.exit(2)
+    except RuntimeError as exc:
+        _err(f"API error: {exc}")
+        _err("Retry hint: wait a few seconds and try again.")
+        sys.exit(3)
+    except requests.exceptions.ConnectionError as exc:
+        _err(f"Network error: {exc}")
+        _err("Retry hint: check your internet connection and try again.")
+        sys.exit(3)
+    except requests.exceptions.Timeout:
+        _err("Request timed out while contacting Altmetric.")
+        _err("Retry hint: Altmetric may be slow; try again in a few minutes.")
+        sys.exit(3)
+    except requests.exceptions.HTTPError as exc:
+        code = exc.response.status_code if exc.response is not None else "unknown"
+        _err(f"HTTP error {code} from Altmetric.")
+        _err("Retry hint: try again later.")
+        sys.exit(3)
+
+
+if __name__ == "__main__":
+    main()

package/src/tools/fetch_scite.py

@@ -0,0 +1,236 @@
+"""
+fetch_scite.py — Scite.ai citation-tally wrapper.
+
+CLI:
+    python fetch_scite.py tally <doi>
+
+Surfaces the Smart Citation tallies (supporting / contrasting / mentioning)
+that Scite.ai computes for a publication, used by /lumi-research-rank as a
+quality signal beyond raw citation counts.
+
+Requires SCITE_API_KEY in the environment (via _env.load_env()). The signal is
+key-gated: when the key is absent the tool exits 2 with an actionable message
+so the skill can skip this signal and continue. JSON emitted to stdout on
+success.
+
+Exit codes:
+    0  success (includes the "no Scite data for this DOI" case, found=false)
+    2  user error (missing key, bad/empty DOI) — actionable
+    3  internal/transient error (network, API 5xx) — includes retry hint
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+# Import HTTP cache helper at module load (before any test patches requests.Session)
+from _cache import wrap_session
+from id_utils import normalize_external_id
+
+# Import env loader using relative path for portability when installed
+try:
+    from _env import load_env
+except ImportError:
+    import importlib.util
+    _spec = importlib.util.spec_from_file_location(
+        "_env", Path(__file__).parent / "_env.py"
+    )
+    _mod = importlib.util.module_from_spec(_spec)  # type: ignore[arg-type]
+    _spec.loader.exec_module(_mod)  # type: ignore[union-attr]
+    load_env = _mod.load_env
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+SCITE_API_BASE = "https://api.scite.ai"
+REQUEST_TIMEOUT = 30
+
+ENV_KEY_NAME = "SCITE_API_KEY"
+KEY_OBTAIN_URL = "https://scite.ai/apis"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr)
+
+
+def _get_api_key() -> str:
+    """Load and return the Scite API key.
+
+    Raises SystemExit(2) with an actionable message if missing.
+    """
+    env = load_env()
+    key = env.get(ENV_KEY_NAME, "").strip()
+    if not key:
+        _err(
+            f"Error: {ENV_KEY_NAME} is not set.\n"
+            f"Scite tallies are an optional, key-gated ranking signal.\n"
+            f"Set it in your project .env file or ~/.env:\n"
+            f"  {ENV_KEY_NAME}=<your-key>\n"
+            f"Obtain an API key at: {KEY_OBTAIN_URL}"
+        )
+        sys.exit(2)
+    return key
+
+
+def _clean_doi(raw: str) -> str:
+    """Validate and normalize a DOI; SystemExit(2) on an invalid value."""
+    r = normalize_external_id("doi", raw)
+    if not r["valid"] or not r["id"]:
+        _err(f"Error: {raw!r} is not a valid DOI (expected form like 10.1234/abcd).")
+        sys.exit(2)
+    return r["id"]
+
+
+def _make_session(api_key: str) -> requests.Session:
+    session = requests.Session()
+    session.headers.update({
+        "User-Agent": "lumina-wiki/0.1 (research-pack; scite fetcher)",
+        "Authorization": f"Bearer {api_key}",
+    })
+    return wrap_session(session, namespace="scite")
+
+
+def _handle_response_errors(resp: requests.Response, context: str) -> None:
+    """Check for API-level errors and raise appropriate exceptions.
+
+    404 is NOT raised here — a DOI absent from the Scite index is a normal
+    "no data" outcome handled by the caller, not an error.
+
+    ValueError -> exit 2 (request problem); RuntimeError -> exit 3 (transient).
+    """
+    if resp.status_code == 404:
+        return
+    if resp.status_code in (401, 403):
+        raise ValueError(f"Scite rejected the API key (HTTP {resp.status_code}). Check SCITE_API_KEY.")
+    if resp.status_code == 429:
+        raise RuntimeError("Rate limit exceeded. Wait before retrying.")
+    if resp.status_code >= 500:
+        raise RuntimeError(f"Scite API returned HTTP {resp.status_code}")
+    if 400 <= resp.status_code < 500:
+        # Any other 4xx is a request-shape problem, not a transient one.
+        raise ValueError(f"Scite rejected the request for {context} (HTTP {resp.status_code}).")
+    resp.raise_for_status()
+
+
+def _parse_json(resp: requests.Response, context: str) -> dict[str, Any] | None:
+    """Parse a JSON object body. Returns None when the body is JSON but not an
+    object (treated as "no usable data"). A non-JSON body is a server-side
+    problem raised as RuntimeError -> exit 3, not mislabeled exit 2.
+    """
+    try:
+        data = resp.json()
+    except ValueError as exc:
+        raise RuntimeError(f"Scite returned a non-JSON body for {context}: {exc}") from exc
+    return data if isinstance(data, dict) else None
+
+
+# ---------------------------------------------------------------------------
+# Core fetch
+# ---------------------------------------------------------------------------
+
+def fetch_tally(doi: str, session: requests.Session) -> dict[str, Any]:
+    """Fetch the Smart Citation tally for a single DOI.
+
+    Returns a normalized dict. When the DOI is not indexed by Scite, returns
+    {"found": False, "doi": doi} rather than raising.
+    """
+    url = f"{SCITE_API_BASE}/tallies/{quote(doi, safe='/')}"
+    resp = session.get(url, timeout=REQUEST_TIMEOUT)
+    _handle_response_errors(resp, f"tally for '{doi}'")
+    if resp.status_code == 404:
+        return {"found": False, "doi": doi}
+
+    raw = _parse_json(resp, f"tally for '{doi}'")
+    if raw is None:
+        # 200 with no usable tally object — treat as no data, not zeros.
+        return {"found": False, "doi": doi}
+    # Scite returns either a flat tally object or {"tally": {...}}.
+    nested = raw.get("tally")
+    tally = nested if isinstance(nested, dict) else raw
+
+    result: dict[str, Any] = {
+        "found": True,
+        "doi": tally.get("doi", doi),
+        "source": "scite.ai",
+    }
+    # Only surface fields the API actually returned — never fabricate zeros.
+    # `contradicting` is Scite's name for what the wiki records as `contrasting`.
+    field_aliases = {
+        "supporting": ("supporting",),
+        "contrasting": ("contradicting", "contrasting"),
+        "mentioning": ("mentioning",),
+        "unclassified": ("unclassified",),
+        "total": ("total",),
+    }
+    for out_key, candidates in field_aliases.items():
+        for name in candidates:
+            if tally.get(name) is not None:
+                result[out_key] = tally[name]
+                break
+    return result
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="fetch_scite.py",
+        description="Fetch Scite.ai Smart Citation tallies. Requires SCITE_API_KEY.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    t = subparsers.add_parser("tally", help="Fetch supporting/contrasting/mentioning tallies for a DOI.")
+    t.add_argument("doi", help="DOI of the publication (e.g. 10.1234/abcd).")
+
+    args = parser.parse_args(argv)
+
+    if not args.doi.strip():
+        _err("Error: DOI must not be empty.")
+        sys.exit(2)
+    doi = _clean_doi(args.doi.strip())
+
+    api_key = _get_api_key()
+    session = _make_session(api_key)
+
+    try:
+        result = fetch_tally(doi, session)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        sys.exit(0)
+    except ValueError as exc:
+        _err(f"Error: {exc}")
+        sys.exit(2)
+    except RuntimeError as exc:
+        _err(f"API error: {exc}")
+        _err("Retry hint: wait a few seconds and try again.")
+        sys.exit(3)
+    except requests.exceptions.ConnectionError as exc:
+        _err(f"Network error: {exc}")
+        _err("Retry hint: check your internet connection and try again.")
+        sys.exit(3)
+    except requests.exceptions.Timeout:
+        _err("Request timed out while contacting Scite.")
+        _err("Retry hint: Scite may be slow; try again in a few minutes.")
+        sys.exit(3)
+    except requests.exceptions.HTTPError as exc:
+        code = exc.response.status_code if exc.response is not None else "unknown"
+        _err(f"HTTP error {code} from Scite.")
+        _err("Retry hint: try again later.")
+        sys.exit(3)
+
+
+if __name__ == "__main__":
+    main()