paper-search-cli 0.1.1 → 0.1.3

package/.env.example

@@ -1,11 +1,12 @@
 # ==============================================================================
 # Paper Search CLI - Environment Variables
 # ==============================================================================
-# Supports 20 academic sources/platforms with a unified CLI interface
+# Supports 25 academic sources/platforms with a unified CLI interface
 # Platforms: Crossref, OpenAlex, PubMed, PubMed Central, Europe PMC, arXiv,
 # bioRxiv, medRxiv, Semantic Scholar, CORE, OpenAIRE, Web of Science,
-# Google Scholar, IACR ePrint, Sci-Hub, ScienceDirect, Springer, Wiley,
-# Scopus, Unpaywall
+# Google Scholar, DBLP, ACM metadata, USENIX metadata, OpenReview,
+# IACR ePrint, Sci-Hub, IEEE Xplore, ScienceDirect, Springer/SpringerLink,
+# Wiley, Scopus, Unpaywall
 #
 # For global installs, prefer:
 #   paper-search config set KEY VALUE
@@ -26,6 +27,15 @@
 WOS_API_KEY=your_web_of_science_api_key_here
 WOS_API_VERSION=v1
 
+# ------------------------------------------------------------------------------
+# IEEE Xplore Metadata API - REQUIRED for IEEE search
+# ------------------------------------------------------------------------------
+# Official metadata search API for IEEE Xplore
+# Get API key: https://developer.ieee.org/
+# Documentation: https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API
+# Pricing/access: Requires IEEE API access; entitlements may vary
+IEEE_API_KEY=your_ieee_api_key_here
+
 # ------------------------------------------------------------------------------
 # PubMed/NCBI E-utilities - OPTIONAL (but recommended)
 # ------------------------------------------------------------------------------
@@ -140,9 +150,14 @@ WILEY_TDM_TOKEN=your_wiley_tdm_token_here
 # Semantic Scholar  | 🟡 Optional| AI-powered search, citations  | CS, AI research
 # CORE              | 🟡 Optional| Repository PDFs               | Open repositories
 # OpenAIRE          | 🟡 Optional| Repository discovery          | Open repositories
+# DBLP              | ✅ Free    | CS bibliography metadata      | CS literature
+# ACM metadata      | ✅ Free    | Crossref DOI-prefix metadata  | ACM papers
+# USENIX metadata   | ✅ Free    | DBLP-backed proceedings data  | Systems/security
+# OpenReview        | ✅ Free    | Notes/search metadata         | ML conferences
 # Unpaywall         | 📧 Email   | DOI OA resolution             | Fallback downloads
 # IACR ePrint       | ✅ Free    | Cryptography papers, PDF      | Cryptography
 # Sci-Hub          | ✅ Free    | Universal DOI access          | Any paper by DOI
+# IEEE Xplore       | 🔴 Required| IEEE metadata                 | Engineering
 # ScienceDirect     | 🔴 Required| Elsevier journals             | Full-text search
 # Springer          | 🔴 Required| Dual API (Meta+OpenAccess)    | Books & journals
 # Wiley             | 🔴 Required| TDM API, full text mining     | Data mining

package/README-sc.md

@@ -9,8 +9,8 @@ Paper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学
 ![Node.js](https://img.shields.io/badge/node.js->=18.0.0-green.svg)
 ![TypeScript](https://img.shields.io/badge/typescript-^5.5.3-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Platforms](https://img.shields.io/badge/platforms-20-brightgreen.svg)
-![Version](https://img.shields.io/badge/version-0.1.1-blue.svg)
+![Platforms](https://img.shields.io/badge/platforms-25-brightgreen.svg)
+![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)
 [![LinuxDo](https://img.shields.io/badge/LinuxDo-community-1f6feb)](https://linux.do)
 
 感谢真诚、友善、团结、专业的 [LinuxDo](https://linux.do) 社区。本项目的 CLI + Skill 路线和论文检索工作流改进，来自社区交流与开源分享的启发。
@@ -27,13 +27,13 @@ Paper Search CLI 是一个独立的 Node.js 命令行工具，用于跨多个学
 
 ## 核心特性
 
-- **20 个学术来源/平台**：Crossref、OpenAlex、PubMed、PubMed Central、Europe PMC、arXiv、bioRxiv、medRxiv、Semantic Scholar、CORE、OpenAIRE、Web of Science、Google Scholar、IACR ePrint、Sci-Hub、ScienceDirect、Springer Nature、Wiley、Scopus、Unpaywall。
+- **25 个学术来源/平台**：Crossref、OpenAlex、PubMed、PubMed Central、Europe PMC、arXiv、bioRxiv、medRxiv、Semantic Scholar、CORE、OpenAIRE、DBLP、ACM Digital Library 元数据、USENIX 元数据、OpenReview、Web of Science、Google Scholar、IACR ePrint、Sci-Hub、IEEE Xplore、ScienceDirect、Springer Nature/SpringerLink、Wiley、Scopus、Unpaywall。
 - **单一命令入口**：安装后通过 `paper-search` 调用，适合终端、脚本和 agent。
 - **JSON 优先输出**：stdout 默认输出 JSON，stderr 保留给人类可读日志和错误。
 - **统一论文数据模型**：标准化标题、作者、DOI、来源、日期、摘要、PDF 链接、引用数和平台扩展字段。
 - **多源检索与去重**：用 `--sources crossref,openalex,pmc` 选择来源，或用 `platform=all` 尝试所有已注册检索来源，再按 DOI、标题+作者合并重复结果。
 - **Semantic Scholar 正文片段检索**：`search_semantic_snippets` 用于检索 Semantic Scholar Open Access snippet 索引中的正文片段，适合查找论文中的方法学细节。该功能需要 `SEMANTIC_SCHOLAR_API_KEY`。
-- **开放获取优先下载链**：`download_with_fallback` 会先尝试原生下载、结果里的 PDF URL、PMC/Europe PMC/CORE/OpenAIRE、Unpaywall DOI 解析，只有显式开启时才把 Sci-Hub 作为最后兜底。
+- **漏斗式回退下载链**：`download_with_fallback` 会先尝试原生下载、结果里的 PDF URL、PMC/Europe PMC/CORE/OpenAIRE、Unpaywall DOI 解析，最后默认使用 Sci-Hub 兜底，除非传入 `useSciHub=false`。
 - **限速与重试**：内置平台级限速和可重试 API 错误处理。
 - **PDF 下载支持**：支持 arXiv、bioRxiv、medRxiv、Semantic Scholar、IACR、Sci-Hub、Springer 开放获取、Wiley DOI 下载等路径。
 - **适合 agent 调用**：`tools`、`status`、`search`、`download`、`run` 覆盖简单检索和精确工具调用。
@@ -51,6 +51,7 @@ paper-search search "machine learning" --platform crossref --max-results 3 --pre
 ```
 
 安装后运行 `paper-search setup`，即可把可选 API key 和 email 写入用户级配置。
+其中 Unpaywall 和 Crossref 的邮箱项可以直接回车跳过，CLI 会自动写入一个随机前缀的 Gmail 格式邮箱；如果你想使用自己的邮箱，后续再用 `paper-search config set` 覆盖即可。
 
 如果你需要本地开发版，或要验证尚未发布的改动，可以从源码安装：
 
@@ -72,34 +73,90 @@ paper-search config doctor --pretty
 
 ## 支持的平台
 
+### 平台类型
+
+下面的能力表仍然是平台能力的准确信息来源。如果只是快速选择检索来源，可以先按这些类型判断：
+
+| 类型 | 平台 | 适合场景 |
+| --- | --- | --- |
+| 综合检索 | Crossref、OpenAlex、Semantic Scholar、Google Scholar | 广覆盖发现、DOI 元数据、引用线索、文献初筛 |
+| 医学/生命科学 | PubMed、PubMed Central、Europe PMC | 临床、生物医学、公卫、生物医学元数据和开放全文 |
+| 预印本/会议稿 | arXiv、bioRxiv、medRxiv、OpenReview、IACR ePrint | 跨学科预印本、生命科学/医学预印本、AI/ML 投稿和密码学 ePrint |
+| 计算机/工程 | DBLP、ACM Digital Library 元数据、IEEE Xplore、USENIX | CS 文献目录、工程数据库、系统/安全会议论文 |
+| 开放全文/仓储 | CORE、OpenAIRE、Unpaywall | 跨学科仓储发现和开放获取 PDF 回退路径 |
+| 引文库/出版商 | Web of Science、Scopus、ScienceDirect、Springer Nature/SpringerLink、Wiley | 机构权限型元数据、引文数据库、出版商记录和下载 |
+| DOI 定向获取 | Sci-Hub | DOI 定向获取，并作为 PDF 下载漏斗的最后自动兜底；除非传入 `useSciHub=false` |
+
+部分平台会跨多个实际工作流。例如 Semantic Scholar 既适合广覆盖检索，也常用于 CS/AI；arXiv 覆盖计算机、数学、物理和部分定量学科。这里按主要使用方式归类；做计算机方向检索时，通常会同时用“计算机/工程”和“预印本/会议稿”两组。
+
+### 能力矩阵
+
+#### 综合检索
+
 | 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
 | --- | --- | --- | --- | --- | --- | --- |
 | Crossref | ✅ | ❌ | ❌ | ✅ | ❌ | 默认搜索平台，广泛元数据覆盖 |
 | OpenAlex | ✅ | 🟡 条件支持 | ❌ | ✅ | ❌ | 广泛免费元数据；记录含开放链接时可用于回退下载 |
-| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | 物理、计算机、数学等预印本 |
-| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 引文数据库、日期排序、年份范围 |
+| Semantic Scholar | ✅ | ✅ | ✅ 正文片段 | ✅ | 🟡 可选* | AI 语义检索 + OA 正文片段 |
+| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | 广泛学术发现，基于页面解析 |
+
+#### 医学/生命科学
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
 | PubMed | ✅ | ❌ | ❌ | ❌ | 🟡 可选 | NCBI E-utilities 生物医学文献 |
 | PubMed Central | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学开放全文和 PMC PDF |
 | Europe PMC | ✅ | ✅ | ✅ | ❌ | ❌ | 生物医学元数据和开放全文链接 |
-| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | 广泛学术发现，基于页面解析 |
-| bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 生物学预印本 |
-| medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 医学预印本 |
-| Semantic Scholar | ✅ | ✅ | ✅ 正文片段 | ✅ | 🟡 可选* | AI 语义检索 + OA 正文片段 |
+
+#### 计算机/工程
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| DBLP | ✅ | ❌ | ❌ | ❌ | ❌ | 通过官方 DBLP search API 检索计算机文献目录 |
+| ACM Digital Library | ✅ | ❌ | ❌ | ✅ | ❌ | 通过 Crossref 的 ACM DOI 前缀元数据检索；不抓取 ACM 页面 |
+| USENIX | ✅ | ❌ | ❌ | ❌ | ❌ | 基于 DBLP 的 USENIX 会议元数据；不抓取 USENIX 搜索页 |
+| IEEE Xplore | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 通过官方 IEEE Xplore Metadata API 检索 IEEE 元数据 |
+
+#### 开放全文/仓储
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
 | CORE | ✅ | 🟡 条件支持 | 🟡 条件支持 | ❌ | 🟡 可选 | 记录含 PDF 或全文链接时可下载 |
 | OpenAIRE | ✅ | 🟡 条件支持 | ❌ | ❌ | 🟡 可选 | 记录含开放链接时可用于回退下载 |
 | Unpaywall | 🟡 条件支持 | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | 仅支持 DOI 查询；需要 email；发现 OA PDF 时可下载 |
+
+#### 预印本/会议稿
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | 物理、计算机、数学等预印本 |
+| bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 生物学预印本 |
+| medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | 医学预印本 |
+| OpenReview | ✅ | ❌ | ❌ | ❌ | ❌ | 通过公开 OpenReview notes search 检索会议投稿、评审和预印本 |
 | IACR ePrint | ✅ | ✅ | ✅ | ❌ | ❌ | 密码学论文 |
-| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | 基于 DOI 查询和下载 |
+
+#### 引文库/出版商
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 引文数据库、日期排序、年份范围 |
 | ScienceDirect | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | Elsevier 元数据和摘要 |
-| Springer Nature | ✅ | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | 开放获取记录可下载；元数据 API 需要 key |
+| Springer Nature / SpringerLink | ✅ | 🟡 条件支持 | ❌ | ❌ | ✅ 必需 | `springerlink` 是现有 Springer Nature 集成的别名 |
 | Wiley | ❌ 关键词搜索 | ✅ | ✅ | ❌ | ✅ 必需 | TDM API，仅支持 DOI 下载 PDF |
 | Scopus | ✅ | ❌ | ❌ | ✅ | ✅ 必需 | 摘要和引文数据库 |
 
+#### DOI 定向获取
+
+| 平台 | 搜索 | 下载 | 全文 | 被引统计 | API Key | 特色功能 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | 基于 DOI 查询和下载 |
+
 说明：
 
 - 能力列中，`✅` 表示直接支持，`❌` 表示不支持，`🟡 条件支持` 表示只在满足条件时可用，例如记录里含 PDF/开放获取链接、只能按 DOI 查询，或只能下载开放获取记录。
 - API Key 列中，`❌` 表示不需要配置，`🟡 可选` 表示不配置也能用但限额或稳定性较弱，`✅ 必需` 表示只在启用该平台时必须配置，不代表新用户默认都要配置。Unpaywall 需要的是 email，不是传统 API key。
 - Wiley TDM API 不支持关键词搜索。应先用 `search_crossref` 找到 Wiley 文章 DOI，再用 `download_paper` 配合 `platform=wiley` 下载。
+- ACM 和 USENIX 检索刻意走元数据后端，不抓取平台搜索页，以遵守 robots.txt 并降低 IP 被封风险。
 - `platform=all` 会尝试所有已注册检索来源，但不包含 Wiley 这类只支持 DOI 下载、不能关键词搜索的平台。未配置 key、超时或请求失败的来源会写入 `failed_sources` / `errors`，其他来源继续返回。
 - `--sources` 接受逗号分隔来源，例如 `--sources crossref,openalex,pmc`。
 - `🟡 可选*` 对 Semantic Scholar 的含义是：普通检索可选；`search_semantic_snippets` 正文片段检索必需配置 `SEMANTIC_SCHOLAR_API_KEY`。
@@ -111,7 +168,7 @@ paper-search config doctor --pretty
 ```bash
 paper-search setup
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_semantic_scholar_api_key_here
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com  # 可选：手动覆盖 setup 自动生成的邮箱
 paper-search config list --pretty
 paper-search config doctor --pretty
 paper-search diagnostics --pretty
@@ -127,6 +184,8 @@ paper-search diagnostics --pretty
 
 `paper-search setup` 是引导式配置命令。默认只询问推荐配置：Semantic Scholar、Unpaywall email、Crossref email 和 CORE。需要遍历所有支持项时使用 `paper-search setup --all`；只想配置指定项时使用 `paper-search setup --keys SEMANTIC_SCHOLAR_API_KEY,CORE_API_KEY`。
 
+为降低首次配置成本，如果 `PAPER_SEARCH_UNPAYWALL_EMAIL` / `UNPAYWALL_EMAIL` / `CROSSREF_MAILTO` 尚未配置，setup 时直接回车会自动写入一个随机前缀的 Gmail 格式邮箱，例如 `paper.search.xxxxxx@gmail.com`，用于让 Unpaywall 和 Crossref 的基础请求能直接运行。
+
 `paper-search diagnostics --pretty` 会列出所有依赖 API key 或 email 的能力、相关配置项、当前是否已配置、常见失败原因和建议排查动作。检索命令在 key-backed 平台返回 0 结果，或遇到 401、403、400、429 时，也会在 JSON 输出里附带 `diagnostic` 字段。
 
 ### API key 推荐策略
@@ -136,11 +195,12 @@ paper-search diagnostics --pretty
 | 等级 | 配置项 | 是否建议新用户配置 | 说明 |
 | --- | --- | --- | --- |
 | 默认推荐 | `SEMANTIC_SCHOLAR_API_KEY` | 建议配置 | 开启 Semantic Scholar 正文片段检索，适合方法学细节检索，也能提高请求稳定性。 |
-| 默认推荐 | `PAPER_SEARCH_UNPAYWALL_EMAIL` 或 `UNPAYWALL_EMAIL` | 建议配置 | 用 DOI 查找开放获取 PDF；只需要邮箱，不需要申请 API key。 |
-| 默认推荐 | `CROSSREF_MAILTO` | 建议配置 | 让 Crossref 请求进入 polite pool，适合长期或高频检索。 |
+| 默认推荐 | `PAPER_SEARCH_UNPAYWALL_EMAIL` 或 `UNPAYWALL_EMAIL` | 建议配置 | 用 DOI 查找开放获取 PDF；只需要邮箱，不需要申请 API key。`setup` 直接回车会自动生成随机 Gmail 格式邮箱，也可以手动换成自己的邮箱。 |
+| 默认推荐 | `CROSSREF_MAILTO` | 建议配置 | 让 Crossref 请求进入 polite pool，适合长期或高频检索。`setup` 直接回车会复用自动生成的邮箱，也可以手动换成自己的邮箱。 |
 | 默认推荐 | `CORE_API_KEY` 或 `PAPER_SEARCH_CORE_API_KEY` | 建议配置 | CORE 匿名访问容易限流；配置 key 后更适合开放仓储检索。 |
 | 生物医学高频 | `PUBMED_API_KEY`、`NCBI_EMAIL`、`NCBI_TOOL` | 经常用 PubMed 时建议配置 | 提高 NCBI E-utilities 限额，并让请求带上明确客户端信息。 |
 | 机构权限型 | `WOS_API_KEY` | 有 Web of Science API 权限再配置 | 用于 Web of Science 检索和引文数据；需要 Clarivate API 权限。 |
+| 机构权限型 | `IEEE_API_KEY` | 有 IEEE Xplore API 权限再配置 | 用于 IEEE Xplore 元数据检索；IEEE 可能要求注册 API 访问和产品权限。 |
 | 机构权限型 | `ELSEVIER_API_KEY` | 有 Scopus 或 ScienceDirect API 权限再配置 | 同一个 Elsevier key 不等于自动拥有两个产品权限，Scopus 和 ScienceDirect 需要分别开通。 |
 | 机构权限型 | `SPRINGER_API_KEY`、`SPRINGER_OPENACCESS_API_KEY` | 需要 Springer 平台时再配置 | 用于 Springer 元数据和开放获取记录；401 通常表示 key 无效或产品权限未开通。 |
 | 机构权限型 | `WILEY_TDM_TOKEN` | 有 Wiley TDM/机构全文权限再配置 | 仅支持 DOI 下载；能否下载取决于 token 和机构订阅权限。 |
@@ -172,6 +232,9 @@ cp .env.example .env
 WOS_API_KEY=your_web_of_science_api_key_here
 WOS_API_VERSION=v1
 
+# IEEE Xplore，IEEE 元数据检索必需
+IEEE_API_KEY=your_ieee_api_key_here
+
 # PubMed，可选；从 3 requests/sec 提升到 10 requests/sec
 PUBMED_API_KEY=your_ncbi_api_key_here
 NCBI_EMAIL=you@example.com
@@ -190,10 +253,10 @@ SPRINGER_OPENACCESS_API_KEY=your_openaccess_api_key_here
 # Wiley TDM，Wiley DOI 下载必需
 WILEY_TDM_TOKEN=your_wiley_tdm_token_here
 
-# Crossref polite pool，可选但推荐
+# Crossref polite pool，可选但推荐；setup 直接回车会自动生成/复用随机 Gmail 格式邮箱
 CROSSREF_MAILTO=you@example.com
 
-# Unpaywall，DOI 开放获取解析必需
+# Unpaywall，DOI 开放获取解析必需；setup 直接回车会自动生成随机 Gmail 格式邮箱
 PAPER_SEARCH_UNPAYWALL_EMAIL=you@example.com
 UNPAYWALL_EMAIL=you@example.com
 
@@ -209,6 +272,7 @@ OPENAIRE_API_KEY=your_openaire_api_key_here
 ### API Key 获取入口
 
 - Web of Science: [Clarivate Developer Portal](https://developer.clarivate.com/apis)
+- IEEE Xplore: [IEEE Xplore Metadata API](https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API)
 - PubMed: [NCBI API Keys](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)
 - Semantic Scholar: [Semantic Scholar API](https://www.semanticscholar.org/product/api)
 - Elsevier: [Elsevier Developer Portal](https://dev.elsevier.com/apikey/manage)
@@ -355,7 +419,7 @@ paper-search diagnostics --pretty
 ```bash
 paper-search config init --pretty
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_key --pretty
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty  # 可选：手动覆盖 setup 自动生成的邮箱
 paper-search config import-env .env --pretty
 paper-search config list --pretty
 paper-search config doctor --pretty
@@ -396,8 +460,9 @@ paper-search run search_papers --json-args '{"query":"machine learning","platfor
 
 ```text
 crossref, arxiv, webofscience, wos, pubmed, biorxiv, medrxiv, semantic,
-iacr, googlescholar, scholar, scihub, sciencedirect, springer, scopus,
-openalex, unpaywall, pmc, europepmc, core, openaire, all
+iacr, googlescholar, scholar, scihub, ieee, sciencedirect, springer,
+springerlink, scopus, openalex, unpaywall, pmc, europepmc, core,
+openaire, dblp, acm, usenix, openreview, all
 ```
 
 多源检索使用 `sources`：
@@ -445,6 +510,24 @@ paper-search run search_openaire --arg query="machine learning" --arg maxResults
 
 Unpaywall 只支持 DOI，且需要配置 email。CORE 匿名访问可能很快返回空结果或被限流，长期使用建议配置 API key。
 
+### 注册表驱动的平台检索
+
+这些偏元数据检索的工具由平台注册表生成；后续接入新平台时，只需要增加新的 searcher 和平台注册信息：
+
+```bash
+paper-search run search_dblp --arg query="graph neural networks" --arg maxResults=5 --pretty
+paper-search run search_acm --arg query="software testing" --arg maxResults=5 --pretty
+paper-search run search_usenix --arg query="file systems" --arg maxResults=5 --pretty
+paper-search run search_openreview --arg query="large language models" --arg maxResults=5 --pretty
+paper-search run search_springerlink --arg query="machine learning" --arg maxResults=5 --pretty
+```
+
+`search_ieee` 使用同一套通用参数，但需要配置 `IEEE_API_KEY`：
+
+```bash
+paper-search run search_ieee --arg query="wireless networks" --arg maxResults=5 --arg articleTitle="wireless" --pretty
+```
+
 ### `search_webofscience`
 
 搜索 Web of Science。需要 `WOS_API_KEY`。
@@ -547,29 +630,31 @@ paper-search run get_paper_by_doi --arg doi="10.1038/nature12373" --arg platform
 
 ### `download_paper`
 
-从支持的平台下载 PDF。
+从指定平台下载 PDF。如果该平台没有原生下载器，或原生下载失败，会进入与 `download_with_fallback` 相同的下载漏斗。
 
 ```bash
 paper-search run download_paper --arg paperId="2301.00001" --arg platform=arxiv --arg savePath=./downloads --pretty
 ```
 
-支持下载的平台：
+原生下载平台：
 
 ```text
 arxiv, biorxiv, medrxiv, semantic, iacr, scihub, springer, wiley,
 pmc, europepmc, core
 ```
 
+其他已注册来源，例如 `crossref`、`openalex`、`dblp`、`acm`、`usenix`、`openreview`，也可以传给 `download_paper`；它们会直接进入元数据/仓储/Unpaywall/Sci-Hub 回退漏斗。
+
 ### `download_with_fallback`
 
-按开放获取优先顺序尝试下载：
+按完整下载漏斗尝试下载。顺序是原生下载、元数据 PDF URL、仓储发现、Unpaywall DOI 解析，最后默认使用 Sci-Hub 兜底：
 
 ```bash
 paper-search run download_with_fallback --arg source=arxiv --arg paperId=1201.0490 --arg doi=10.48550/arxiv.1201.0490 --arg savePath=./downloads --pretty
-paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --arg useSciHub=false --pretty
+paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --pretty
 ```
 
-`useSciHub` 默认为 `false`；只有明确选择该最后兜底路径时才设置为 `true`。
+`useSciHub` 默认为 `true`；只有需要关闭该最后兜底路径时才设置为 `false`。`download_paper` 在指定平台下载失败或平台不支持直接下载时，也会进入同一条漏斗。
 
 ### `search_wiley`
 

package/README.md

@@ -9,8 +9,8 @@ It keeps the broad platform coverage, unified paper model, and detailed capabili
 ![Node.js](https://img.shields.io/badge/node.js->=18.0.0-green.svg)
 ![TypeScript](https://img.shields.io/badge/typescript-^5.5.3-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Platforms](https://img.shields.io/badge/platforms-20-brightgreen.svg)
-![Version](https://img.shields.io/badge/version-0.1.1-blue.svg)
+![Platforms](https://img.shields.io/badge/platforms-25-brightgreen.svg)
+![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)
 [![LinuxDo](https://img.shields.io/badge/LinuxDo-community-1f6feb)](https://linux.do)
 
 Thanks to the sincere, friendly, collaborative, and professional [LinuxDo](https://linux.do) community. The CLI + Skill direction and the paper-search workflow refinements in this project were shaped by LinuxDo discussions and open-source sharing.
@@ -27,13 +27,13 @@ Thanks to the sincere, friendly, collaborative, and professional [LinuxDo](https
 
 ## Key Features
 
-- **20 academic sources/platforms**: Crossref, OpenAlex, PubMed, PubMed Central, Europe PMC, arXiv, bioRxiv, medRxiv, Semantic Scholar, CORE, OpenAIRE, Web of Science, Google Scholar, IACR ePrint, Sci-Hub, ScienceDirect, Springer Nature, Wiley, Scopus, and Unpaywall.
+- **25 academic sources/platforms**: Crossref, OpenAlex, PubMed, PubMed Central, Europe PMC, arXiv, bioRxiv, medRxiv, Semantic Scholar, CORE, OpenAIRE, DBLP, ACM Digital Library metadata, USENIX metadata, OpenReview, Web of Science, Google Scholar, IACR ePrint, Sci-Hub, IEEE Xplore, ScienceDirect, Springer Nature/SpringerLink, Wiley, Scopus, and Unpaywall.
 - **Single command interface**: install once, then call `paper-search` from terminal, scripts, or agents.
 - **JSON-first output**: stdout is machine-readable JSON by default; stderr is reserved for human-readable diagnostics.
 - **Unified paper model**: normalized title, authors, DOI, source, dates, abstract, PDF URL, citation count, and provider-specific metadata where available.
 - **Multi-source search with dedupe**: query selected sources with `--sources crossref,openalex,pmc`, or use `platform=all` to try every registered search source, then merge duplicates by DOI and title/author keys.
 - **Semantic Scholar body-snippet search**: `search_semantic_snippets` searches Semantic Scholar's Open Access snippet index for body-text snippets, which is useful for finding methodological details. It requires `SEMANTIC_SCHOLAR_API_KEY`.
-- **Open-access-first fallback download**: `download_with_fallback` tries native source download, discovered PDF URLs, PMC/Europe PMC/CORE/OpenAIRE, Unpaywall DOI resolution, then optional Sci-Hub only when explicitly enabled.
+- **Funnel-style fallback download**: `download_with_fallback` tries native source download, discovered PDF URLs, PMC/Europe PMC/CORE/OpenAIRE, Unpaywall DOI resolution, then Sci-Hub as the final fallback unless `useSciHub=false`.
 - **Rate limits and retry logic**: platform-specific rate limiting and retryable API error handling.
 - **PDF download support**: download from supported sources such as arXiv, bioRxiv, medRxiv, Semantic Scholar, IACR, Sci-Hub, Springer open access, and Wiley DOI-based access.
 - **Agent-friendly commands**: `tools`, `status`, `search`, `download`, and `run` cover both simple use and precise advanced calls.
@@ -51,6 +51,7 @@ paper-search search "machine learning" --platform crossref --max-results 3 --pre
 ```
 
 Run `paper-search setup` after installation to write optional API keys and emails into the user config.
+For the Unpaywall and Crossref email prompts, you can press Enter and the CLI will write a random Gmail-format address automatically; use `paper-search config set` later if you want to replace it with your own email.
 
 For local development, or to test changes that have not been released yet, install from source:
 
@@ -72,34 +73,90 @@ paper-search config doctor --pretty
 
 ## Supported Platforms
 
+### Platform Families
+
+The table below remains the source-of-truth for capabilities. For choosing a source quickly, use these broad families:
+
+| Family | Platforms | Best For |
+| --- | --- | --- |
+| General scholarly metadata | Crossref, OpenAlex, Semantic Scholar, Google Scholar | Broad discovery, DOI metadata, citation clues, first-pass literature search |
+| Medicine / life sciences | PubMed, PubMed Central, Europe PMC | Clinical, biomedical, public health, biomedical metadata, and open full text |
+| Preprints / conference papers | arXiv, bioRxiv, medRxiv, OpenReview, IACR ePrint | Cross-disciplinary preprints, life-science/medical preprints, AI/ML submissions, and cryptography ePrints |
+| Computer science / engineering | DBLP, ACM Digital Library metadata, IEEE Xplore, USENIX | CS bibliography, engineering databases, systems/security proceedings |
+| Open full text / repositories | CORE, OpenAIRE, Unpaywall | Cross-disciplinary repository discovery and open-access PDF fallback routes |
+| Citation indexes / publishers | Web of Science, Scopus, ScienceDirect, Springer Nature/SpringerLink, Wiley | Institution-backed metadata, citation databases, publisher-specific records and downloads |
+| DOI-targeted lookup | Sci-Hub | DOI-based retrieval and the final automatic PDF fallback unless `useSciHub=false` |
+
+Some platforms belong to more than one practical workflow. For example, Semantic Scholar is useful for broad discovery and CS/AI, while arXiv covers CS, math, physics, and quantitative fields. These groups reflect the primary way a platform is used; CS searches often combine "computer science / engineering" with "preprints / conference papers."
+
+### Capability Matrix
+
+#### General Scholarly Metadata
+
 | Platform | Search | Download | Full Text | Citations | API Key | Special Features |
 | --- | --- | --- | --- | --- | --- | --- |
 | Crossref | ✅ | ❌ | ❌ | ✅ | ❌ | Default search platform, broad metadata coverage |
 | OpenAlex | ✅ | 🟡 Conditional | ❌ | ✅ | ❌ | Broad free metadata; can feed fallback downloads when records include OA links |
-| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | Physics, CS, math, and related preprints |
-| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ Required | Citation database, date sorting, year ranges |
+| Semantic Scholar | ✅ | ✅ | ✅ Body snippets | ✅ | 🟡 Optional* | AI semantic search + OA body snippets |
+| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | Broad academic discovery, scrape-based |
+
+#### Medicine / Life Sciences
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
 | PubMed | ✅ | ❌ | ❌ | ❌ | 🟡 Optional | Biomedical literature through NCBI E-utilities |
 | PubMed Central | ✅ | ✅ | ✅ | ❌ | ❌ | Open biomedical full text and PMC PDFs |
 | Europe PMC | ✅ | ✅ | ✅ | ❌ | ❌ | Biomedical metadata plus open full-text links |
-| Google Scholar | ✅ | ❌ | ❌ | ✅ | ❌ | Broad academic discovery, scrape-based |
+
+#### Computer Science / Engineering
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
+| DBLP | ✅ | ❌ | ❌ | ❌ | ❌ | Computer science bibliography through the official DBLP search API |
+| ACM Digital Library | ✅ | ❌ | ❌ | ✅ | ❌ | ACM DOI-prefix metadata through Crossref; no ACM scraping |
+| USENIX | ✅ | ❌ | ❌ | ❌ | ❌ | DBLP-backed USENIX proceedings metadata; no USENIX search-page scraping |
+| IEEE Xplore | ✅ | ❌ | ❌ | ✅ | ✅ Required | IEEE metadata through the official IEEE Xplore Metadata API |
+
+#### Preprints / Conference Papers
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
+| arXiv | ✅ | ✅ | ✅ | ❌ | ❌ | Physics, CS, math, and related preprints |
 | bioRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | Biology preprints |
 | medRxiv | ✅ | ✅ | ✅ | ❌ | ❌ | Medical preprints |
-| Semantic Scholar | ✅ | ✅ | ✅ Body snippets | ✅ | 🟡 Optional* | AI semantic search + OA body snippets |
+| OpenReview | ✅ | ❌ | ❌ | ❌ | ❌ | Conference submissions, reviews, and preprints through public OpenReview notes search |
+| IACR ePrint | ✅ | ✅ | ✅ | ❌ | ❌ | Cryptography papers |
+
+#### Open Full Text / Repositories
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
 | CORE | ✅ | 🟡 Conditional | 🟡 Conditional | ❌ | 🟡 Optional | Downloads work when records include PDF or full-text links |
 | OpenAIRE | ✅ | 🟡 Conditional | ❌ | ❌ | 🟡 Optional | Can feed fallback downloads when records include open links |
 | Unpaywall | 🟡 Conditional | 🟡 Conditional | ❌ | ❌ | ✅ Required | DOI-only lookup; requires an email; downloads work when an OA PDF is found |
-| IACR ePrint | ✅ | ✅ | ✅ | ❌ | ❌ | Cryptography papers |
-| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | DOI-based paper lookup and PDF retrieval |
+
+#### Citation Indexes / Publishers
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
+| Web of Science | ✅ | ❌ | ❌ | ✅ | ✅ Required | Citation database, date sorting, year ranges |
 | ScienceDirect | ✅ | ❌ | ❌ | ✅ | ✅ Required | Elsevier metadata and abstracts |
-| Springer Nature | ✅ | 🟡 Conditional | ❌ | ❌ | ✅ Required | Open-access records can be downloaded; metadata API requires a key |
+| Springer Nature / SpringerLink | ✅ | 🟡 Conditional | ❌ | ❌ | ✅ Required | `springerlink` is an alias for the existing Springer Nature integration |
 | Wiley | ❌ Keyword search | ✅ | ✅ | ❌ | ✅ Required | TDM API, DOI-based PDF download only |
 | Scopus | ✅ | ❌ | ❌ | ✅ | ✅ Required | Abstract and citation database |
 
+#### DOI-Targeted Lookup
+
+| Platform | Search | Download | Full Text | Citations | API Key | Special Features |
+| --- | --- | --- | --- | --- | --- | --- |
+| Sci-Hub | ✅ | ✅ | ❌ | ❌ | ❌ | DOI-based paper lookup and PDF retrieval |
+
 Notes:
 
 - In capability columns, `✅` means directly supported, `❌` means unsupported, and `🟡 Conditional` means support depends on record content or provider constraints, such as DOI-only lookup, available PDF/OA links, or open-access-only downloads.
 - In the API Key column, `❌` means no configuration is needed, `🟡 Optional` means configuration improves limits or stability, and `✅ Required` means the key is required only when you use that platform, not that every new installation should configure it. Unpaywall requires an email rather than a traditional API key.
 - Wiley does not support keyword search through the Wiley TDM API. Use `search_crossref` to find Wiley articles and then use `download_paper` with `platform=wiley` and the DOI.
+- ACM and USENIX search intentionally use metadata-backed routes rather than crawling provider search pages, which keeps the integration compatible with robots.txt and reduces IP-blocking risk.
 - `platform=all` tries every registered search source except DOI-download-only providers such as Wiley. Sources without configured credentials, sources that time out, and sources that fail are recorded in `failed_sources` / `errors` while the remaining sources continue.
 - `--sources` accepts a comma-separated source list, for example `--sources crossref,openalex,pmc`.
 - `🟡 Optional*` for Semantic Scholar means optional for regular search; `search_semantic_snippets` body-snippet search requires `SEMANTIC_SCHOLAR_API_KEY`.
@@ -111,7 +168,7 @@ Most free metadata sources work without configuration. For API keys and emails,
 ```bash
 paper-search setup
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_semantic_scholar_api_key_here
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com  # optional: replace the setup-generated email
 paper-search config list --pretty
 paper-search config doctor --pretty
 paper-search diagnostics --pretty
@@ -127,6 +184,8 @@ The file is written with `0600` permissions. `config list` and `config doctor` m
 
 `paper-search setup` is the guided setup command. By default it asks for the recommended credentials only: Semantic Scholar, Unpaywall email, Crossref email, and CORE. Use `paper-search setup --all` to walk through every supported configuration key, or `paper-search setup --keys SEMANTIC_SCHOLAR_API_KEY,CORE_API_KEY` to configure a specific subset.
 
+To reduce first-run friction, if `PAPER_SEARCH_UNPAYWALL_EMAIL` / `UNPAYWALL_EMAIL` / `CROSSREF_MAILTO` are not configured, pressing Enter during setup writes a random Gmail-format address such as `paper.search.xxxxxx@gmail.com`, so basic Unpaywall and Crossref requests can run immediately.
+
 `paper-search diagnostics --pretty` lists every API-key or email-backed capability, the related config keys, whether the required keys are configured, common failure modes, and suggested next checks. Search commands also add a `diagnostic` field when a key-backed platform returns zero results or an auth/permission/rate-limit error.
 
 ### API Key Recommendation
@@ -136,11 +195,12 @@ The file is written with `0600` permissions. `config list` and `config doctor` m
 | Level | Config keys | Recommended for new users | Notes |
 | --- | --- | --- | --- |
 | Default recommended | `SEMANTIC_SCHOLAR_API_KEY` | Yes | Enables Semantic Scholar body-snippet search for methodology details and improves request stability. |
-| Default recommended | `PAPER_SEARCH_UNPAYWALL_EMAIL` or `UNPAYWALL_EMAIL` | Yes | Finds open-access PDFs from DOI records; this only needs an email, not an API key. |
-| Default recommended | `CROSSREF_MAILTO` | Yes | Puts Crossref requests in the polite pool, which is better for long-running or frequent searches. |
+| Default recommended | `PAPER_SEARCH_UNPAYWALL_EMAIL` or `UNPAYWALL_EMAIL` | Yes | Finds open-access PDFs from DOI records; this only needs an email, not an API key. Press Enter in `setup` to generate a random Gmail-format email, or replace it manually. |
+| Default recommended | `CROSSREF_MAILTO` | Yes | Puts Crossref requests in the polite pool, which is better for long-running or frequent searches. Press Enter in `setup` to reuse the generated email, or replace it manually. |
 | Default recommended | `CORE_API_KEY` or `PAPER_SEARCH_CORE_API_KEY` | Yes | CORE anonymous access is often rate-limited; a key makes open repository search more reliable. |
 | Biomedical-heavy use | `PUBMED_API_KEY`, `NCBI_EMAIL`, `NCBI_TOOL` | Recommended if you use PubMed heavily | Raises NCBI E-utilities limits and identifies the client. |
 | Institution entitlement | `WOS_API_KEY` | Configure only with Web of Science API access | Enables Web of Science search and citation data; requires Clarivate API entitlement. |
+| Institution entitlement | `IEEE_API_KEY` | Configure only with IEEE Xplore API access | Enables IEEE Xplore metadata search; IEEE may require registered API access and product entitlement. |
 | Institution entitlement | `ELSEVIER_API_KEY` | Configure only with Scopus or ScienceDirect API access | One Elsevier key does not automatically grant both products; Scopus and ScienceDirect need separate entitlements. |
 | Institution entitlement | `SPRINGER_API_KEY`, `SPRINGER_OPENACCESS_API_KEY` | Configure only when you need Springer | Used for Springer metadata and open-access records; 401 usually means an invalid key or missing product access. |
 | Institution entitlement | `WILEY_TDM_TOKEN` | Configure only with Wiley TDM/institutional full-text access | DOI-based download only; availability depends on the token and institutional subscription. |
@@ -172,6 +232,9 @@ cp .env.example .env
 WOS_API_KEY=your_web_of_science_api_key_here
 WOS_API_VERSION=v1
 
+# IEEE Xplore, required for IEEE metadata search
+IEEE_API_KEY=your_ieee_api_key_here
+
 # PubMed, optional; increases rate limit from 3 requests/sec to 10 requests/sec
 PUBMED_API_KEY=your_ncbi_api_key_here
 NCBI_EMAIL=you@example.com
@@ -190,10 +253,10 @@ SPRINGER_OPENACCESS_API_KEY=your_openaccess_api_key_here
 # Wiley TDM, required for Wiley DOI-based PDF download
 WILEY_TDM_TOKEN=your_wiley_tdm_token_here
 
-# Crossref polite pool, optional but recommended
+# Crossref polite pool, optional but recommended; setup can auto-generate/reuse a random Gmail-format email
 CROSSREF_MAILTO=you@example.com
 
-# Unpaywall, required for DOI-based OA resolution
+# Unpaywall, required for DOI-based OA resolution; setup can auto-generate a random Gmail-format email
 PAPER_SEARCH_UNPAYWALL_EMAIL=you@example.com
 UNPAYWALL_EMAIL=you@example.com
 
@@ -209,6 +272,7 @@ OPENAIRE_API_KEY=your_openaire_api_key_here
 ### API Key Sources
 
 - Web of Science: [Clarivate Developer Portal](https://developer.clarivate.com/apis)
+- IEEE Xplore: [IEEE Xplore Metadata API](https://developer.ieee.org/docs/read/Searching_the_IEEE_Xplore_Metadata_API)
 - PubMed: [NCBI API Keys](https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/)
 - Semantic Scholar: [Semantic Scholar API](https://www.semanticscholar.org/product/api)
 - Elsevier: [Elsevier Developer Portal](https://dev.elsevier.com/apikey/manage)
@@ -355,7 +419,7 @@ Manage the user-level config file.
 ```bash
 paper-search config init --pretty
 paper-search config set SEMANTIC_SCHOLAR_API_KEY your_key --pretty
-paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty
+paper-search config set PAPER_SEARCH_UNPAYWALL_EMAIL you@example.com --pretty  # optional: replace the setup-generated email
 paper-search config import-env .env --pretty
 paper-search config list --pretty
 paper-search config doctor --pretty
@@ -396,8 +460,9 @@ Supported platforms:
 
 ```text
 crossref, arxiv, webofscience, wos, pubmed, biorxiv, medrxiv, semantic,
-iacr, googlescholar, scholar, scihub, sciencedirect, springer, scopus,
-openalex, unpaywall, pmc, europepmc, core, openaire, all
+iacr, googlescholar, scholar, scihub, ieee, sciencedirect, springer,
+springerlink, scopus, openalex, unpaywall, pmc, europepmc, core,
+openaire, dblp, acm, usenix, openreview, all
 ```
 
 For multi-source search, pass `sources`:
@@ -445,6 +510,24 @@ paper-search run search_openaire --arg query="machine learning" --arg maxResults
 
 Unpaywall is DOI-only and requires an email. CORE public access may return zero results or rate-limit quickly without an API key.
 
+### Registry-Backed Platform Search
+
+These metadata-oriented tools are generated from the platform registry, so adding later platforms only needs a new searcher plus registry metadata:
+
+```bash
+paper-search run search_dblp --arg query="graph neural networks" --arg maxResults=5 --pretty
+paper-search run search_acm --arg query="software testing" --arg maxResults=5 --pretty
+paper-search run search_usenix --arg query="file systems" --arg maxResults=5 --pretty
+paper-search run search_openreview --arg query="large language models" --arg maxResults=5 --pretty
+paper-search run search_springerlink --arg query="machine learning" --arg maxResults=5 --pretty
+```
+
+`search_ieee` uses the same generic schema but requires `IEEE_API_KEY`:
+
+```bash
+paper-search run search_ieee --arg query="wireless networks" --arg maxResults=5 --arg articleTitle="wireless" --pretty
+```
+
 ### `search_webofscience`
 
 Search Web of Science. Requires `WOS_API_KEY`.
@@ -547,29 +630,31 @@ paper-search run get_paper_by_doi --arg doi="10.1038/nature12373" --arg platform
 
 ### `download_paper`
 
-Download PDF files from supported platforms.
+Download PDF files from a platform. If the selected platform has no native downloader, or if native download fails, the command enters the same fallback funnel used by `download_with_fallback`.
 
 ```bash
 paper-search run download_paper --arg paperId="2301.00001" --arg platform=arxiv --arg savePath=./downloads --pretty
 ```
 
-Supported download platforms:
+Native download platforms:
 
 ```text
 arxiv, biorxiv, medrxiv, semantic, iacr, scihub, springer, wiley,
 pmc, europepmc, core
 ```
 
+Other registered sources, such as `crossref`, `openalex`, `dblp`, `acm`, `usenix`, or `openreview`, can still be passed to `download_paper`; they start directly at the metadata/repository/Unpaywall/Sci-Hub fallback funnel.
+
 ### `download_with_fallback`
 
-Try open-access routes before optional last-resort sources:
+Try the full download funnel. The order is source-native download, metadata PDF URL, repository discovery, Unpaywall DOI resolution, then Sci-Hub as the final fallback:
 
 ```bash
 paper-search run download_with_fallback --arg source=arxiv --arg paperId=1201.0490 --arg doi=10.48550/arxiv.1201.0490 --arg savePath=./downloads --pretty
-paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --arg useSciHub=false --pretty
+paper-search run download_with_fallback --arg source=crossref --arg paperId="10.1038/nature12373" --arg doi="10.1038/nature12373" --arg savePath=./downloads --pretty
 ```
 
-`useSciHub` defaults to `false`; set it to `true` only when you explicitly choose that final fallback.
+`useSciHub` defaults to `true`; set it to `false` only when you need to suppress that final fallback. `download_paper` also routes failed or unsupported platform downloads through the same funnel.
 
 ### `search_wiley`