docs: update documentation and usage policy

SepineTam · SepineTam · commit a47e62f6fbc7 · 2026-05-30T00:22:08.000+08:00
diff --git a/README.md b/README.md
@@ -1,39 +1,78 @@
 # NBER-CLI
+A command line interface for downloading the National Bureau of Economic Research (NBER) paper without brower.
 
-NBER-CLI is a command line tool for downloading NBER paper PDFs.
+[![Pytest](https://github.com/SepineTam/NBER-CLI/actions/workflows/pytest.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/pytest.yml)
+[![Lint](https://github.com/SepineTam/NBER-CLI/actions/workflows/lint.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/lint.yml)
+[![Docs](https://github.com/SepineTam/NBER-CLI/actions/workflows/docs.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-## Installation
+[简体中文](README.zh-CN.md) | [Documentation](docs/index.md)
+
+> **NBER** is a registered trademark of the [National Bureau of Economic Research](https://www.nber.org). This project is an independent open-source tool and is **not affiliated with, endorsed by, or sponsored by** the National Bureau of Economic Research. By using this project, you agree to the [Usage Policy](docs/en/policy.md).
+
+## Features
+
+- Search NBER working papers by title, paper number, author, abstract, or keyword.
+- Fetch structured metadata and abstracts for a paper ID such as `w25000`.
+- Download single papers or batches as PDF files.
+- Expose the same core workflows as MCP tools for AI agents.
+- Return human-readable output by default, with JSON output for automation.
+
+## Quick Start
+
+Run commands directly with `uvx`:
 
 ```bash
-pip install nber-cli
+uvx nber-cli search "Labor Economic"
+uvx nber-cli info w25000
+uvx nber-cli download w34567
 ```
 
-## CLI v0.2 Usage
+Or install the command first:
 
 ```bash
-nber-cli download w1234
-nber-cli download w1234 --file /path/to/save/w1234.pdf
-nber-cli download w1234 -f /path/to/save/w1234.pdf
-nber-cli download w1234 --save-base /path/to/save
-nber-cli download w1234 -s /path/to/save
-nber-cli download --batch w1234 w23156 w1516 --save-base /path/to/save
-nber-cli download -b w1235 w4568 w0485
-nber-cli info w34255
-nber-cli info w34255 -f json
-nber-cli search "labor economics"
-nber-cli search "ChatGPT" --start-date 2024-01-01 --per-page 20
-nber-cli search "ChatGPT" -f json
+uv tool install nber-cli
+nber-cli search "Labor Economic"
+nber-cli info w25000
+nber-cli download w34567
 ```
 
-Rules:
+## MCP Server for Agents
+
+NBER-CLI can run as a stdio MCP server:
+
+```bash
+uvx nber-cli mcp-server
+```
 
-- If neither `--file` nor `--save-base` is set, files are saved to `Path.cwd()`.
-- If both `--file` and `--save-base` are set, `--file` wins.
-- Batch download supports `--save-base` only.
-- Batch download does not support `--file`.
-- `info` and `search` default to list output. Use `--format json` or `-f json` for structured output.
+Example MCP client configuration:
 
+```json
+{
+  "mcpServers": {
+    "nber-cli": {
+      "command": "uvx",
+      "args": ["nber-cli", "mcp-server"]
+    }
+  }
+}
+```
+
+The MCP server exposes tools for paper lookup, search, and PDF download.
+
+## Documentation
+
+More usage details, command references, MCP setup, Python API examples, development notes, and release history are available in the [documentation](docs/index.md).
+
+## Development
+
+```bash
+uv sync --dev --group docs
+uv run pytest
+uv run ruff check .
+uv run --group docs mkdocs serve
+```
 
 ## License
 
-[Apache-2.0](LICENSE)
+NBER-CLI is released under the [Apache-2.0 License](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -0,0 +1,78 @@
+# NBER-CLI
+一个用于下载 National Bureau of Economic Research (NBER) 工作论文的命令行界面。
+
+[![Pytest](https://github.com/SepineTam/NBER-CLI/actions/workflows/pytest.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/pytest.yml)
+[![Lint](https://github.com/SepineTam/NBER-CLI/actions/workflows/lint.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/lint.yml)
+[![Docs](https://github.com/SepineTam/NBER-CLI/actions/workflows/docs.yml/badge.svg)](https://github.com/SepineTam/NBER-CLI/actions/workflows/docs.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[English](README.md) | [中文文档](docs/zh-CN/index.md)
+
+> **NBER** 是 [美国国家经济研究局](https://www.nber.org)（National Bureau of Economic Research）的注册商标。本项目是独立的开源工具，与美国国家经济研究局**不存在任何附属、认可或赞助关系**。使用本项目即视为同意[使用政策](docs/zh/policy.md)。
+
+## 功能特性
+
+- 按标题、论文编号、作者、摘要或关键词搜索 NBER 工作论文。
+- 通过 `w25000` 这样的论文编号获取结构化元数据和摘要。
+- 下载单篇或批量论文 PDF。
+- 通过 MCP 工具把核心能力暴露给 AI Agent。
+- 默认输出适合阅读的文本，也支持 JSON 输出用于自动化流程。
+
+## 快速开始
+
+直接通过 `uvx` 运行：
+
+```bash
+uvx nber-cli search "Labor Economic"
+uvx nber-cli info w25000
+uvx nber-cli download w34567
+```
+
+也可以先安装命令：
+
+```bash
+uv tool install nber-cli
+nber-cli search "Labor Economic"
+nber-cli info w25000
+nber-cli download w34567
+```
+
+## 给 Agent 使用的 MCP Server
+
+NBER-CLI 可以作为 stdio MCP server 运行：
+
+```bash
+uvx nber-cli mcp-server
+```
+
+MCP 客户端配置示例：
+
+```json
+{
+  "mcpServers": {
+    "nber-cli": {
+      "command": "uvx",
+      "args": ["nber-cli", "mcp-server"]
+    }
+  }
+}
+```
+
+MCP server 提供论文查询、搜索和 PDF 下载工具。
+
+## 文档
+
+更完整的用法、命令参考、MCP 配置、Python API 示例、开发说明和发布记录请见 [中文文档](docs/zh-CN/index.md)。
+
+## 开发
+
+```bash
+uv sync --dev --group docs
+uv run pytest
+uv run ruff check .
+uv run --group docs mkdocs serve
+```
+
+## 许可证
+
+NBER-CLI 使用 [Apache-2.0 License](LICENSE) 发布。
diff --git a/docs/en/contributing.md b/docs/en/contributing.md
@@ -34,7 +34,7 @@ uv run --group docs mkdocs build --strict
 When adding a new documentation page:
 
 1. Add the English page under `docs/`.
-2. Add the Simplified Chinese page under `docs/zh-CN/`.
+2. Add the Simplified Chinese page under `docs/zh/`.
 3. Register both pages in `mkdocs.yml`.
 4. Run `uv run --group docs mkdocs build --strict`.
 
diff --git a/docs/en/policy.md b/docs/en/policy.md
@@ -0,0 +1,39 @@
+# Usage Policy
+
+> If there is any conflict or inconsistency between this English version and the Chinese version, the Chinese version shall prevail.
+
+## NBER and NBER-CLI
+
+The National Bureau of Economic Research (NBER) is an independent, non-profit, nonpartisan economic research organization that publishes and distributes working papers, research metadata, newsletters, and related materials through [nber.org](https://www.nber.org).
+
+**NBER** is a registered trademark of the National Bureau of Economic Research. NBER-CLI is an independent open-source project and is not affiliated with, endorsed by, sponsored by, or operated by NBER.
+
+NBER-CLI is a command-line and MCP utility for searching NBER working papers, reading publicly exposed paper metadata, and requesting PDF downloads from NBER-hosted URLs. It does not host NBER content, provide a substitute distribution service, or create any separate entitlement to access NBER materials. Every use of NBER-CLI remains subject to NBER's [Website Privacy Policy](https://www.nber.org/nber-website-privacy-policy), [working paper access and authorization rules](https://www.nber.org/nber-help-working-papers-general-information), [copyright and permission rules](https://www.nber.org/nber-help-working-papers-general-information), [subscription terms of use](https://www.nber.org/subscribe/information-libraries), and any other policy or access condition that NBER publishes or updates.
+
+## Project Boundaries
+
+- **No project-side storage**: NBER-CLI does not operate servers, caches, mirrors, databases, CDNs, or other infrastructure for storing NBER papers or metadata. Requests go directly from the user's machine or agent runtime to NBER's website. Runtime data is transient unless the user explicitly asks the tool to write output locally.
+- **User-controlled local files**: When a user runs a download command, any PDF is saved only to the local path selected by that user. The project does not receive, retain, index, or redistribute that file.
+- **No access circumvention**: NBER-CLI does not bypass subscriptions, paywalls, account requirements, IP-based authorization, first-week or recent-paper restrictions, access limits, or other controls imposed by NBER. If NBER returns a denial, error, redirect, or unavailable response, the tool treats that response as authoritative.
+- **No traffic masking**: NBER-CLI uses standard Python HTTP libraries and ordinary request headers. It does not provide proxy pools, IP rotation, credential sharing, CAPTCHA bypass, request-signature manipulation, or other evasion mechanisms.
+- **No redistribution rights**: Installing or using NBER-CLI does not grant any license to repost, mirror, sell, sublicense, train on, or otherwise reuse NBER content beyond what NBER, the relevant authors, and applicable law allow.
+
+## Access, Copyright, and User Responsibility
+
+NBER decides what is available through its website and under what conditions. Access may depend on publication date, subscription status, institutional eligibility, geographic eligibility, account authorization, or other rules set by NBER. Users are responsible for confirming that their use is permitted before downloading, copying, quoting, sharing, or otherwise using any NBER material.
+
+NBER states that copyright in NBER Working Papers is held by the respective authors rather than by NBER. NBER-CLI does not own paper content and cannot grant permissions for uses beyond the access made available by NBER or the rights provided by law. Requests for permission beyond fair use or other applicable exceptions should be directed to the appropriate rights holder.
+
+NBER-CLI is intended for lawful personal research, education, and reproducible research workflows. It is not intended for systematic bulk harvesting, public mirroring, reposting, resale, unauthorized commercial use, or any workflow designed to avoid NBER's access decisions.
+
+## Operational Transparency
+
+Search and metadata features use NBER web pages and website endpoints that are part of the normal operation of nber.org. PDF downloads request files from URLs served by NBER. The project does not claim that these interfaces are official APIs, stable APIs, or approved integration points.
+
+Metadata, abstracts, links, availability, and files are provided by NBER and may be incomplete, delayed, revised, removed, rate limited, or otherwise changed without notice. NBER-CLI may stop working if NBER changes its website structure, access policy, endpoints, authorization checks, or file locations.
+
+## Allocation of Risk
+
+NBER-CLI is provided as an independent open-source tool on an "as is" and "as available" basis. The maintainers do not control NBER's website, content, copyright permissions, access decisions, uptime, or policies, and do not promise continued access to any NBER material.
+
+By using NBER-CLI, users accept responsibility for their own requests, downloads, storage choices, and downstream use of any materials obtained from NBER. The maintainers are not responsible for access denials, account or network restrictions, copyright or licensing disputes, data loss, service interruptions, policy violations, or other consequences arising from a user's use of NBER-CLI.
diff --git a/docs/en/python-api.md b/docs/en/python-api.md
@@ -65,6 +65,28 @@ async def main() -> None:
     await download_paper_to_file("w25000", Path("papers/w25000.pdf"))
 
 
+asyncio.run(main())
+```
+
+## Download Multiple Papers
+
+```python
+import asyncio
+from pathlib import Path
+
+from nber_cli import download_multiple_papers
+
+
+async def main() -> None:
+    result = await download_multiple_papers(
+        ["w34567", "w25000", "w32000"],
+        Path("papers"),
+    )
+    print(f"Downloaded {len(result.paths)} papers")
+    for failure in result.failures:
+        print(f"Failed: {failure.paper_id} - {failure.error}")
+
+
 asyncio.run(main())
 ```
 
@@ -96,6 +118,20 @@ asyncio.run(main())
 | `start_date` | `str` or `None` | Applied start date. |
 | `end_date` | `str` or `None` | Applied end date. |
 
+### DownloadFailure
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `paper_id` | `str` | The paper ID that failed to download. |
+| `error` | `BaseException` | The exception raised during the download attempt. |
+
+### DownloadBatchResult
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `paths` | `list[Path]` | Paths of successfully downloaded PDFs. |
+| `failures` | `list[DownloadFailure]` | Failed downloads with their errors. |
+
 ## Formatter Helpers
 
 Use formatter helpers when you want stable dictionaries for JSON output or MCP-style responses:
@@ -107,3 +143,12 @@ from nber_cli import info, related, search_results
 - `info(paper)` returns core metadata.
 - `related(paper)` returns related optional fields.
 - `search_results(results)` returns a structured search payload.
+
+For human-readable text output, use the text formatters:
+
+```python
+from nber_cli import info_text, search_results_text
+```
+
+- `info_text(paper, include_all=False)` returns a formatted text string with paper details. Set `include_all=True` to include topic, programs, and published version.
+- `search_results_text(results)` returns a formatted text string with search results.
diff --git a/docs/zh/contributing.md b/docs/zh/contributing.md
@@ -34,7 +34,7 @@ uv run --group docs mkdocs build --strict
 新增文档页时：
 
 1. 在 `docs/` 下添加英文页面。
-2. 在 `docs/zh-CN/` 下添加简体中文页面。
+2. 在 `docs/zh/` 下添加简体中文页面。
 3. 在 `mkdocs.yml` 中注册两个页面。
 4. 运行 `uv run --group docs mkdocs build --strict`。
 
diff --git a/docs/zh/policy.md b/docs/zh/policy.md
@@ -0,0 +1,37 @@
+# 使用政策
+
+## NBER 与 NBER-CLI
+
+National Bureau of Economic Research（NBER，美国国家经济研究局）是一家独立、非营利、无党派的经济研究机构，通过 [nber.org](https://www.nber.org) 发布和传播工作论文、研究元数据、通讯及相关研究材料。
+
+**NBER** 是 National Bureau of Economic Research 的注册商标。NBER-CLI 是独立的开源项目，不隶属于 NBER，亦未获得 NBER 的认可、背书、赞助或运营授权。
+
+NBER-CLI 是一个命令行与 MCP 工具，用于帮助用户搜索 NBER 工作论文、读取公开展示的论文元数据，并从 NBER 托管的 URL 请求 PDF 下载。它不托管 NBER 内容，不提供替代分发服务，也不为用户创造任何独立于 NBER 之外的访问资格。使用 NBER-CLI 始终受 NBER 的[网站隐私政策](https://www.nber.org/nber-website-privacy-policy)、[工作论文访问与授权规则](https://www.nber.org/nber-help-working-papers-general-information)、[版权与许可规则](https://www.nber.org/nber-help-working-papers-general-information)、[订阅使用条款](https://www.nber.org/subscribe/information-libraries)，以及 NBER 已发布或未来更新的其他政策和访问条件约束。
+
+## 项目边界
+
+- **不进行项目侧存储**：NBER-CLI 不运营用于存储 NBER 论文或元数据的服务器、缓存、镜像、数据库、CDN 或其他基础设施。请求直接从用户的设备或 Agent 运行环境发往 NBER 网站。除非用户明确要求把结果写入本地文件，运行时数据仅作临时处理。
+- **本地文件由用户控制**：当用户执行下载命令时，PDF 只会保存到用户选择的本地路径。本项目不会接收、保留、索引或再分发该文件。
+- **不绕过访问限制**：NBER-CLI 不绕过订阅、付费墙、账号要求、基于 IP 的授权、新近论文或首周访问限制、访问额度，或 NBER 设置的其他控制措施。如果 NBER 返回拒绝、错误、跳转或不可用响应，本工具会将该响应视为有效结果。
+- **不隐藏或伪装流量**：NBER-CLI 使用标准 Python HTTP 库和常规请求头，不提供代理池、IP 轮换、凭据共享、验证码绕过、请求签名篡改或其他规避机制。
+- **不授予再分发权利**：安装或使用 NBER-CLI 不代表用户获得转载、镜像、销售、再授权、训练模型，或以其他方式复用 NBER 内容的许可；相关使用仍以 NBER、相应作者及适用法律允许的范围为准。
+
+## 访问、版权与用户责任
+
+NBER 决定其网站上哪些内容可访问，以及在什么条件下可访问。访问资格可能取决于论文发布时间、订阅状态、机构资格、地区资格、账号授权，或 NBER 设置的其他规则。用户在下载、复制、引用、分享或以其他方式使用任何 NBER 材料前，应自行确认相关使用是否被允许。
+
+NBER 说明其 Working Papers 的版权由相应作者持有，而非由 NBER 持有。NBER-CLI 不拥有任何论文内容，也无权授予超出 NBER 已开放访问范围或法律允许范围之外的使用许可。涉及合理使用或其他法定例外之外的许可请求，应由用户向相应权利人确认。
+
+NBER-CLI 的目标用途是合法的个人研究、教育和可复现研究流程。它不适用于系统性批量抓取、公开镜像、转载、转售、未经授权的商业使用，或任何旨在规避 NBER 访问决定的流程。
+
+## 运行透明性
+
+搜索和元数据功能使用 NBER 网页，以及 nber.org 正常运行过程中使用的网站端点。PDF 下载会请求由 NBER 提供的文件 URL。本项目不声称这些接口是官方 API、稳定 API 或经 NBER 批准的集成方式。
+
+元数据、摘要、链接、可访问性和文件均由 NBER 提供，可能存在不完整、延迟、修订、移除、限流或其他变更。若 NBER 更改网站结构、访问政策、端点、授权校验或文件位置，NBER-CLI 可能无法继续工作。
+
+## 风险归属
+
+NBER-CLI 作为独立开源工具，按“现状”和“可用时”提供。维护者不控制 NBER 的网站、内容、版权许可、访问决定、服务可用性或政策，也不承诺用户可以持续访问任何 NBER 材料。
+
+使用 NBER-CLI 即表示用户自行承担其请求、下载、本地存储选择，以及后续使用 NBER 材料所产生的责任。维护者不对访问被拒、账号或网络受限、版权或许可争议、数据丢失、服务中断、政策违反，或因用户使用 NBER-CLI 而产生的其他后果承担责任。
diff --git a/docs/zh/python-api.md b/docs/zh/python-api.md
diff --git a/mkdocs.yml b/mkdocs.yml
