nber-cli 0.3.1__tar.gz → 0.5.0__tar.gz

{nber_cli-0.3.1 → nber_cli-0.5.0}/.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "nber-cli",
   "description": "Claude Code marketplace for NBER-CLI research workflows.",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "owner": {
     "name": "Song Tan",
     "email": "sepinetam@gmail.com",
@@ -12,7 +12,7 @@
     {
       "name": "nber-cli",
       "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "author": {
         "name": "Song Tan",
         "email": "sepinetam@gmail.com"

nber_cli-0.5.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This file is the canonical release history. The English mirror at `docs/en/changelog.md` and the Chinese mirror at `docs/zh/changelog.md` are generated from the same source content and must stay in lock-step. Any release commit updates all three together.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-06-16
+
+### Security
+- RSS feed parsing now uses `defusedxml` to block XML external entity (XXE) and entity expansion attacks.
+- CLI downloads are restricted to the current working directory and its subdirectories by default. Use `nber-cli download --restrict false` to override per invocation. The `download.restrict_dir` config key is stored and validated, but the current CLI default remains `true`.
+- Database `init` and `migrate` paths on macOS and Linux must reside within the user's home directory.
+- Synchronous HTTP requests enforce TLS 1.2 as the minimum version.
+- Selected info/download failure paths now avoid raw exception text; download-log messages and soft database warnings use sanitized summaries or exception class names.
+
+### Added
+- `nber-cli config show` / `get <key>` / `set <key> <value>` / `verify` for inspecting and editing `~/.nber-cli/config.json`.
+- `download.concurrency` configuration option (default `3`) and the `--concurrency` / `-c` CLI flag to cap concurrent downloads.
+- `--restrict true|false` flag on `nber-cli download` to control directory restriction per invocation.
+- `--yes` flag for `nber-cli mcp-server`; the existing `--port` option now requires explicit confirmation when set to a non-default value.
+- `sse` transport for `nber-cli mcp-server`.
+- JSON Schema (`config.schema.json`) for validating `~/.nber-cli/config.json`.
+- Strict raw-configuration validation that reports malformed JSON, invalid section/value types, and schema-minimum violations without silently injecting defaults.
+- Plugin manifests and marketplace metadata now share the package version, and the Claude plugin skill path uses the case-sensitive tracked `./skills/NBER-CLI` directory.
+- Domain invariant validation in all core dataclasses (`NBER`, `NBERSearchResults`, `NBERFeedItem`, `NBERFeedFetchResult`, clean results, and download results).
+- `get_config_value`, `set_config_value`, `read_config`, `write_config`, and `validate_config` exported from the package top level.
+- Paper ID format validation (`w?\d+`) across CLI, download, and MCP entry points.
+- Validation of fetched paper titles, positive citation IDs, and response/request paper-ID agreement before metadata is accepted.
+
+### Changed
+- Replaced legacy `typing.Dict`, `List`, and `Optional` aliases with modern Python 3.11 syntax.
+- Added `mypy` configuration and strengthened type annotations across `cli.py`, `config_store.py`, and `fetcher.py`.
+- `mcp-server` transport name corrected to `streamable-http`; the existing `--port` option now uses `--yes` confirmation for non-default values.
+- Retry loops in `fetcher.py` now use exponential backoff capped at 30 seconds.
+- `feed fetch` skips malformed individual RSS items instead of failing the entire feed.
+- Invalid configured or per-call download concurrency values are rejected or fall back to the documented safe default instead of creating an invalid semaphore.
+- Database schema-changing and data-writing operations reject databases with a future `PRAGMA user_version`; the diagnostic schema-version reader remains read-only.
+- Feed fetching establishes/validates the local schema before the network request, then writes feed items plus fetch history transactionally after the response is parsed; cleanup operations pair schema validation/upgrade and deletion in one SQLite transaction.
+- `download.py` enables `raise_for_status=True` on `ClientSession`.
+- Error handling narrowed to specific network/timeout exception types with preserved exception chains.
+- Removed the info cache hit hint that was printed to stderr on cached `info` lookups.
+
+### Fixed
+- `feed fetch` now tolerates unescaped `<` characters followed by whitespace or a digit in RSS title and description text while keeping strict XML parsing for all other malformed input.
+- RSS parse failures now report their line and column when available, and `feed fetch` reports runtime parse errors with exit code `1` without printing command usage.
+
+## [0.4.0] - 2026-06-04
+
+### Added
+- `nber-cli info --refresh` skips the local `info_cache` and re-fetches the paper from NBER. The new data is written back to the cache when the cache is enabled.
+- `nber-cli info cache --turn-on` / `--turn-off` toggle the `info_cache` lookup globally and persist the state to `~/.nber-cli/config.json`.
+- `nber-cli info cache --set-refresh <N>` sets the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and used as the TTL for every subsequent `info` call. Defaults to `30` days.
+- `nber-cli info cache clear` with `--days`, `--all`, `--start-date`, or `--end-date` mirrors the `feed clean` parameter set, using `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- `nber-cli info cache` (no sub-action) prints the current cache state, TTL, and cached row count.
+- New `nber_cli.config_store` module: centralised read and write of `~/.nber-cli/config.json` plus the `InfoCacheSettings` dataclass and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`).
+- New `nber_cli.info_cache.get_paper_with_info_cache_result` async helper (in the `nber_cli.info_cache` module) that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag, so callers (CLI and MCP) can surface a "loaded from cache" hint.
+- Public Python API exports from the package top level: `InfoCacheSettings`, `clear_info_cache`, `count_info_cache`, `get_info_cache_settings`, `get_info_cache_ttl_days`, `is_info_cache_enabled`, `is_info_cache_expired`, `set_info_cache_enabled`, `set_info_cache_ttl_days`, `NBERInfoCacheClearResult`. `InfoCacheLookupResult` and `get_paper_with_info_cache_result` are exposed from the `nber_cli.info_cache` module rather than the package top level; import them as `from nber_cli.info_cache import ...`.
+
+### Changed
+- `~/.nber-cli/config.json` now carries an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## [0.3.1] - 2026-06-03
+
+### Added
+- `db init` and `db migrate` top-level subcommands replace `feed init` and `feed migrate`. The database is now general-purpose and stores feed cache, behavior logs, and paper metadata cache.
+- `info_cache` table caches paper metadata fetched via `info` and the MCP `get_paper_info` tool. Subsequent lookups return immediately from the cache.
+- `query_log`, `download_log`, and `info_log` tables record search keywords, download outcomes, and paper info lookups for later auditing.
+- `schema_version` field written to `~/.nber-cli/config.json` so future schema migrations can roll forward safely.
+
+### Changed
+- Default database renamed from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations continue to work without manual steps.
+- Database schema upgraded from `user_version = 1` to `user_version = 2`. Existing v1 databases are upgraded automatically on next CLI invocation; original `feed_items` rows are preserved.
+- Database code consolidated into `nber_cli.db`. The original `init_feed_database`, `migrate_feed_database`, and `get_feed_database_path` helpers are kept as thin compatibility wrappers.
+
+## [0.3.0] - 2026-06-03
+
+### Added
+- `feed init` subcommand: initialize a local SQLite feed cache and write its path to user config.
+- `feed fetch` subcommand: fetch NBER's new working papers RSS feed, cache seen items, and show newly discovered papers by default.
+- `feed fetch --max-items`: limit displayed feed output. When used without `--display-all`, display-all behavior is enabled automatically.
+- `feed migrate` subcommand: move the feed cache database and SQLite sidecar files to a new path, then update user config.
+- `feed clean` subcommand: clean cached feed database records by age, date range, or all records after interactive confirmation.
+- Python API exports for feed cache helpers and feed result models.
+
+### Changed
+- Added user config support at `~/.nber-cli/config.json` for the feed cache database path.
+- Expanded English and Chinese documentation for feed commands, configuration, Python API, and release notes.
+
+## [0.2.0] - 2026-05-31
+
+### Added
+- `download` subcommand: single paper ID or batch mode (`--batch`), explicit file path (`--file`), target directory (`--save-base`).
+- `info` subcommand: paper metadata with `--all` flag for full details and `--format json` option.
+- `search` subcommand: full-text search with date filters (`--start-date`, `--end-date`), pagination (`--page`, `--per-page`), `--format json` option.
+- `mcp-server` subcommand: MCP server for AI agent integration with stdio and streamable_http transports.
+
+### Changed
+- Reworked CLI into subcommand syntax (`nber-cli <subcommand>`).
+- Simplified downloader to direct async HTTP PDF fetches (removed database-backed state tracking).
+- Removed legacy web UI module and script entrypoint.
+
+## [0.1.4] - 2025-08-09
+
+### Added
+- Added `--version` / `-v` flag to display current version.
+- Added comprehensive help message with examples.
+- Added `__main__.py` file to support `python -m nber_cli` usage.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.

{nber_cli-0.3.1 → nber_cli-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: nber-cli
-Version: 0.3.1
-Summary: A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
+Version: 0.5.0
+Summary: A command-line interface for accessing National Bureau of Economic Research (NBER) papers without a browser.
 Project-URL: Homepage, https://github.com/sepinetam/nber-cli
 Project-URL: Repository, https://github.com/sepinetam/nber-cli
 Project-URL: Issues, https://github.com/sepinetam/nber-cli/issues
@@ -22,6 +22,7 @@ Requires-Python: >=3.11
 Requires-Dist: aiohttp
 Requires-Dist: aiohttp-retry
 Requires-Dist: certifi
+Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: fake-useragent
 Requires-Dist: mcp>=1.27.1
 Description-Content-Type: text/markdown
@@ -33,6 +34,8 @@ A command line interface for reaching the National Bureau of Economic Research (
 [![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)
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 
 [简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
 
@@ -43,9 +46,14 @@ A command line interface for reaching the National Bureau of Economic Research (
 - 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.
+- Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
+- Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 
+See [Configuration](docs/en/configuration.md) for the full list of configurable values and the local database layout, and [Usage Policy](docs/en/policy.md) for what NBER-CLI writes to disk by default.
+
 ## Quick Start
 
 ### Use in Agents

{nber_cli-0.3.1 → nber_cli-0.5.0}/README.md

@@ -5,6 +5,8 @@ A command line interface for reaching the National Bureau of Economic Research (
 [![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)
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 
 [简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
 
@@ -15,9 +17,14 @@ A command line interface for reaching the National Bureau of Economic Research (
 - 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.
+- Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
+- Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 
+See [Configuration](docs/en/configuration.md) for the full list of configurable values and the local database layout, and [Usage Policy](docs/en/policy.md) for what NBER-CLI writes to disk by default.
+
 ## Quick Start
 
 ### Use in Agents

{nber_cli-0.3.1 → nber_cli-0.5.0}/README.zh-CN.md

@@ -5,7 +5,8 @@
 [![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)
-
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 [English](README.md) | [中文文档](docs/zh/index.md)
 
 > **NBER** 是 [美国国家经济研究局](https://www.nber.org)（National Bureau of Economic Research）的注册商标。本项目是独立的开源工具，与美国国家经济研究局**不存在任何附属、认可或赞助关系**。使用本项目即视为同意[使用政策](docs/zh/policy.md)。
@@ -15,9 +16,14 @@
 - 按标题、论文编号、作者、摘要或关键词搜索 NBER 工作论文。
 - 通过 `w25000` 这样的论文编号获取结构化元数据和摘要。
 - 下载单篇或批量论文 PDF。
+- 通过本地 RSS feed 缓存追踪 NBER 新发布的工作论文（`nber-cli feed fetch` / `feed clean`）。
+- 本地缓存论文元数据（`nber-cli info` 会写入 `info_cache`），采用滑动 TTL；同时为 `search`、`download` 和 `info` 查询记录行为日志。
+- 把缓存、RSS 条目和行为日志统一存放在本地 SQLite 数据库 `~/.nber-cli/nber.db`（路径可通过 `nber-cli db init` / `db migrate` 配置）。
 - 通过 MCP 工具把核心能力暴露给 AI Agent。
 - 默认输出适合阅读的文本，也支持 JSON 输出用于自动化流程。
 
+完整可配置项和本地数据库结构请见[配置](docs/zh/configuration.md)，默认写入磁盘的内容请见[使用政策](docs/zh/policy.md)。
+
 ## 快速开始
 
 ### 在 Agent 中使用

{nber_cli-0.3.1 → nber_cli-0.5.0}/docs/en/agents/index.md

@@ -33,7 +33,7 @@ Agents that support MCP can run NBER-CLI without a checked-out repository:
 Agents that support skills should load the NBER-CLI skill from:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 The skill tells the agent when to use NBER-CLI, how to run `uvx nber-cli ...`, how to configure MCP, and how to interpret access errors.

{nber_cli-0.3.1 → nber_cli-0.5.0}/docs/en/agents/openclaw.md

@@ -24,7 +24,7 @@ This runs the published `nber-cli` package with `uvx`, so a checked-out copy of
 If OpenClaw supports skill or instruction imports, load:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 The skill gives the agent the usage policy, command examples, JSON output guidance, and common error interpretation.

{nber_cli-0.3.1 → nber_cli-0.5.0}/docs/en/agents/others.md

@@ -20,7 +20,7 @@ Add this MCP server:
 Then load or paste the skill from:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 ## If MCP Is Not Supported

nber_cli-0.5.0/docs/en/changelog.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+This page mirrors the canonical `CHANGELOG.md` at the repository root. The Chinese mirror at `docs/zh/changelog.md` carries the same content. Any release commit updates all three together.
+
+## Unreleased
+
+## 0.5.0 - 2026-06-16
+
+### Security
+
+- RSS feed parsing now uses `defusedxml` to block XML external entity (XXE) and entity expansion attacks.
+- CLI downloads are restricted to the current working directory and its subdirectories by default. Use `nber-cli download --restrict false` to override per invocation. The `download.restrict_dir` config key is stored and validated, but the current CLI default remains `true`.
+- Database `init` and `migrate` paths on macOS and Linux must reside within the user's home directory.
+- Synchronous HTTP requests enforce TLS 1.2 as the minimum version.
+- Selected info/download failure paths now avoid raw exception text; download-log messages and soft database warnings use sanitized summaries or exception class names.
+
+### Added
+
+- Added `nber-cli config show` / `get <key>` / `set <key> <value>` / `verify` for inspecting and editing `~/.nber-cli/config.json`.
+- Added `download.concurrency` configuration option (default `3`) and the `--concurrency` / `-c` CLI flag to cap concurrent downloads.
+- Added `--restrict true|false` flag on `nber-cli download` to control directory restriction per invocation.
+- Added `--yes` for `nber-cli mcp-server`; the existing `--port` option now requires explicit confirmation when set to a non-default value.
+- Added the `sse` transport for `nber-cli mcp-server`.
+- Added JSON Schema (`config.schema.json`) for validating `~/.nber-cli/config.json`.
+- Added strict raw-configuration validation that reports malformed JSON, invalid section/value types, and schema-minimum violations without silently injecting defaults.
+- Added plugin manifest and marketplace metadata version synchronization, with the Claude plugin skill path corrected to the case-sensitive tracked `./skills/NBER-CLI` directory.
+- Added domain invariant validation in all core dataclasses (`NBER`, `NBERSearchResults`, `NBERFeedItem`, `NBERFeedFetchResult`, clean results, and download results).
+- Added `get_config_value`, `set_config_value`, `read_config`, `write_config`, and `validate_config` exports from the package top level.
+- Added paper ID format validation (`w?\d+`) across CLI, download, and MCP entry points.
+- Added validation of fetched paper titles, positive citation IDs, and response/request paper-ID agreement before metadata is accepted.
+
+### Changed
+
+- Replaced legacy `typing.Dict`, `List`, and `Optional` aliases with modern Python 3.11 syntax.
+- Added `mypy` configuration and strengthened type annotations across `cli.py`, `config_store.py`, and `fetcher.py`.
+- Corrected the `mcp-server` transport name to `streamable-http`; the existing `--port` option now uses `--yes` confirmation for non-default values.
+- Retry loops in `fetcher.py` now use exponential backoff capped at 30 seconds.
+- `feed fetch` skips malformed individual RSS items instead of failing the entire feed.
+- Invalid configured or per-call download concurrency values are rejected or fall back to the documented safe default instead of creating an invalid semaphore.
+- Database schema-changing and data-writing operations reject databases with a future `PRAGMA user_version`; the diagnostic schema-version reader remains read-only.
+- Feed fetching establishes/validates the local schema before the network request, then writes feed items plus fetch history transactionally after the response is parsed; cleanup operations pair schema validation/upgrade and deletion in one SQLite transaction.
+- `download.py` enables `raise_for_status=True` on `ClientSession`.
+- Error handling narrowed to specific network/timeout exception types with preserved exception chains.
+- Removed the info cache hit hint that was printed to stderr on cached `info` lookups.
+
+### Fixed
+
+- `feed fetch` now tolerates unescaped `<` characters followed by whitespace or a digit in RSS title and description text while keeping strict XML parsing for all other malformed input.
+- RSS parse failures now report their line and column when available, and `feed fetch` reports runtime parse errors with exit code `1` without printing command usage.
+
+## 0.4.0 - 2026-06-04
+
+### Added
+
+- Added `nber-cli info --refresh` to bypass the local `info_cache` and re-fetch paper metadata from NBER. The fresh data is written back to the cache when the cache is enabled.
+- Added `nber-cli info cache --turn-on` and `--turn-off` to toggle the `info_cache` lookup globally. The setting is persisted to `~/.nber-cli/config.json`.
+- Added `nber-cli info cache --set-refresh <N>` to set the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and applied as the TTL for every subsequent `info` call. Defaults to `30` days.
+- Added `nber-cli info cache clear` with the same parameter set as `feed clean`: `--days`, `--all`, `--start-date`, and `--end-date`. Filtering uses `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- Added `nber-cli info cache` (no sub-action) to print the current cache state, TTL, and cached row count.
+- Added `nber_cli.config_store` module with `InfoCacheSettings` and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`) for reading and writing `~/.nber-cli/config.json`.
+- Added `nber_cli.info_cache.get_paper_with_info_cache_result` async helper that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag.
+- Added public Python API exports from the package top level: `InfoCacheSettings`, `clear_info_cache`, `count_info_cache`, `get_info_cache_settings`, `get_info_cache_ttl_days`, `is_info_cache_enabled`, `is_info_cache_expired`, `set_info_cache_enabled`, `set_info_cache_ttl_days`, `NBERInfoCacheClearResult`. `InfoCacheLookupResult` and `get_paper_with_info_cache_result` are exposed from the `nber_cli.info_cache` module rather than the package top level; import them as `from nber_cli.info_cache import ...`.
+
+### Changed
+
+- `~/.nber-cli/config.json` now stores an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## 0.3.1 - 2026-06-03
+
+### Added
+
+- Added `nber-cli db init` and `nber-cli db migrate` for initializing and relocating the local database. These replace `feed init` and `feed migrate`.
+- Added `info_cache` table so repeated `nber-cli info` and MCP `get_paper_info` calls return immediately from cache.
+- Added `query_log`, `download_log`, and `info_log` tables for recording search keywords, download outcomes, and info lookups.
+- Added `schema_version` field in `~/.nber-cli/config.json` for forward-compatible schema upgrades.
+
+### Changed
+
+- Renamed default database file from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations keep working without manual steps.
+- Upgraded database schema from version 1 to version 2 with automatic upgrade on next invocation.
+- Consolidated database code into `nber_cli.db`. Old `init_feed_database` and `migrate_feed_database` helpers remain as thin compatibility wrappers.
+
+## 0.3.0 - 2026-06-03
+
+### Added
+
+- Added `nber-cli feed init` for creating a local SQLite feed cache.
+- Added `nber-cli feed fetch` for fetching NBER's new working papers RSS feed and showing newly cached items.
+- Added `nber-cli feed fetch --max-items` for limiting displayed feed output.
+- Added `nber-cli feed migrate` for moving the feed cache database and updating user config.
+- Added `nber-cli feed clean` for cleaning cached feed database records with confirmation.
+- Added Python API documentation for feed cache helpers and feed data models.
+
+### Changed
+
+- Added user config documentation for `~/.nber-cli/config.json` and `feed.db-path`.
+- Expanded English and Chinese feed cache documentation across CLI, getting started, configuration, and Python API pages.
+
+## 0.2.0 - 2026-05-31
+
+### Changed
+
+- Reworked the CLI into `nber-cli download ...` subcommand syntax.
+- Added `--file/-f` and `--save-base/-s` path handling behavior.
+- Added `--batch/-b` multi-ID download mode.
+- Removed database-backed download state tracking.
+- Simplified the downloader to direct async HTTP PDF fetches.
+- Updated documentation for the v0.2 command model.
+- Removed the legacy web UI module and script entrypoint.
+
+## 0.1.4 - 2025-08-09
+
+### Added
+
+- Added `--version` / `-v` flag to display current version.
+- Added comprehensive help message with examples.
+- Added `__main__.py` support for `python -m nber_cli`.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.