@luffysolution/pi-scholar 0.1.1 → 0.2.0

package/README.en.md

@@ -0,0 +1,131 @@
+# 📚 pi-scholar
+
+[![npm version](https://img.shields.io/npm/v/@luffysolution/pi-scholar.svg)](https://www.npmjs.com/package/@luffysolution/pi-scholar)
+[![GitHub release](https://img.shields.io/github/v/release/luffysolution-svg/pi-scholar)](https://github.com/luffysolution-svg/pi-scholar/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/node/v/@luffysolution/pi-scholar.svg)](https://nodejs.org)
+
+🌐 [简体中文](./README.md) ｜ **English**
+
+A fully integrated Pi-native TypeScript research workflow: complete Ai4Scholar online search/citation capabilities, read-only Zotero Desktop access, and MinerU's official Precision API. It writes ordinary UTF-8 Markdown and a sibling asset directory — **no Obsidian, Vault, plugin, database, or other Pi extension required**.
+
+> 📦 Published to npm as **`@luffysolution/pi-scholar`** (scoped) — the unscoped name `pi-scholar` is already taken by an unrelated package. All in-product names — the `/pi-scholar` command, the `pi-scholar` skill, `pi_scholar_parse`, and `pi-scholar.config.json` — are unaffected by the npm scope.
+
+## ✨ Features
+
+- 🔎 **Online search + local matching**: directly integrates every REST/advanced tool, dynamic MCP bridge, and `/ai4scholar` command from the former `pi-ai4scholar`, matched against your local Zotero library by DOI/title.
+- 🗂️ **Full metadata aggregation**: `zotero_item` returns structured creators, dates, DOI/ISBN/ISSN, tags, notes, annotations, attachments, and the selected PDF in one call.
+- 🧬 **Deep PDF parsing**: `pi_scholar_parse` calls the official MinerU API to recognize formulas/tables/layout and extract figures, publishing results safely.
+- 📝 **Clean Markdown output**: compact YAML frontmatter plus a full-provenance `metadata.json` sidecar, with image paths that work out of the box (Obsidian-friendly, never Obsidian-dependent).
+- 🔒 **Secure by default**: Zotero requests are hard-locked to loopback addresses, MinerU secrets are redacted everywhere, downloaded ZIPs are validated against path traversal/symlinks before extraction, and publishing is transactional.
+
+## 📦 Install
+
+**Requirements**: Node.js `>=22.19`, Pi `>=0.84.4`, Zotero `7+` with the Local API enabled, Windows / macOS / Linux.
+
+```sh
+pi install npm:@luffysolution/pi-scholar
+pi install npm:@luffysolution/pi-scholar@0.2.0         # pinned version
+pi install git:https://github.com/luffysolution-svg/pi-scholar.git#main
+pi install ./path/to/pi-scholar                          # local persistent install
+pi -e ./path/to/pi-scholar                                # temporary dev load
+```
+
+Restart Pi or run `/reload`, then verify these tools/commands are available: `zotero_collections`, `zotero_search`, `zotero_item`, `pi_scholar_parse`, the built-in `ai4scholar_*` tools, `/ai4scholar`, and `/skill:pi-scholar`.
+
+Update / uninstall:
+
+```sh
+pi update npm:@luffysolution/pi-scholar
+pi remove npm:@luffysolution/pi-scholar
+```
+
+Ai4Scholar source is now maintained directly in this repository; npm installation no longer bundles or executes the `pi-ai4scholar` dependency package. If you previously installed that extension separately, run `pi remove npm:pi-ai4scholar` to avoid duplicate tool registration.
+
+### 💬 `/pi-scholar` chat command
+
+Once installed, type `/pi-scholar` inside Pi's chat.
+
+- **With no arguments**: opens a one-line input dialog ("Pi Scholar: what do you want to research?").
+- **With arguments** (e.g. `/pi-scholar find photothermal catalysis papers and match my local Zotero`): skips the dialog and runs immediately.
+
+Either way, the command hands your request to the `pi-scholar` skill (equivalent to `/skill:pi-scholar ...`) through Pi's normal prompt-template expansion, so the model plans and calls `zotero_*` / `ai4scholar_*` / `pi_scholar_parse` under Pi's usual tool-permission flow — **the command itself never calls Zotero or MinerU directly**.
+
+> In print/JSON/non-interactive Pi modes (`ctx.hasUI === false`) there is no dialog to fall back on; you must pass the request inline as an argument.
+
+### 🩺 Setup diagnostics (`npx` / `npm`, no Pi required)
+
+A small zero-dependency CLI ships alongside the extension for verifying your machine *before* or *after* installing into Pi. It only performs a bounded, read-only reachability probe and never touches Zotero data, and it cannot install or configure the Pi extension itself — only `pi install ...` does that.
+
+```sh
+npx @luffysolution/pi-scholar doctor     # Node version, config discovery, Zotero reachability, MinerU token presence
+npx @luffysolution/pi-scholar --version
+npx @luffysolution/pi-scholar --help
+```
+
+> 💡 Running `npx` from inside the `pi-scholar` project's own directory can trip up Node's local-resolution precedence; running it from any other directory works normally.
+
+## ⚙️ Configuration
+
+All configuration lives in **one JSON file** covering the Zotero connection, MinerU parsing behavior, output location, asset naming, and tag formatting. Copy [`pi-scholar.config.example.json`](./pi-scholar.config.example.json) to `pi-scholar.config.json` and edit as needed.
+
+**Discovery order**: `PI_SCHOLAR_CONFIG` env var → nearest `pi-scholar.config.json` (trusted projects only) → `~/.config/pi-scholar/config.json` → `~/.pi-scholar.json` → built-in defaults. Environment variables always override the corresponding JSON fields.
+
+> 📖 **For the full field reference — every option's default, valid range, and env var name — see [docs/CONFIGURATION.en.md](./docs/CONFIGURATION.en.md)（[中文](./docs/CONFIGURATION.md)）.**
+
+The built-in Ai4Scholar functionality keeps its separate secret configuration entry points (the key never enters `pi-scholar.config.json`): `/ai4scholar setup`, `AI4SCHOLAR_API_KEY`, `AI4SCHOLAR_BASE_URL`, etc.
+
+Don't forget to enable **Allow other applications on this computer to communicate with Zotero** in Zotero's settings. Zotero requests are unauthenticated loopback GETs only, with redirects disabled. Never expose port 23119 externally.
+
+## 🔍 Behavior
+
+<details>
+<summary>Expand for detailed behavior notes</summary>
+
+**`zotero_collections`** can list collections, read collection metadata, or list a collection's top-level items.
+
+**`zotero_item`** maps raw records into one typed `Paper`: complete forward-compatible parent metadata, structured creators, original date/year, DOI/ISBN/ISSN, publication fields, tags/collections, child notes/attachments, PDF-child annotations, indexed-text availability, and the selected PDF. When a parent is clearly sparse, missing bibliographic fields are filled only if Zotero contains **exactly one** non-deleted item with the same normalized title and first author; the donor key, fields, and raw metadata are recorded for provenance. When no attachment key is supplied, PDFs are sorted by key and the first is selected and reported. Identifier matching uses normalized DOI first, then normalized title/year; **nothing is written back to Zotero**.
+
+**`pi_scholar_parse`** validates `%PDF-`, hashes SHA-256, requests an official MinerU signed upload, uploads raw bytes with PUT, polls with bounded backoff, downloads and safely inspects the ZIP, repairs local image links, and transactionally publishes. Default result names are `FirstAuthor-Year-Title.md`; missing components use `UnknownAuthor`, `UnknownYear`, or `Untitled`. Invalid cross-platform characters and component-internal `+` signs become spaces, reserved device names are prefixed, and UTF-8 length is bounded. Collisions use ` (2)`, ` (3)`, etc. — **never** a Zotero key. Reprocessing is recognized by the YAML `zotero://select/...` deep link (legacy `zotero_key` remains readable).
+
+The YAML frontmatter is intentionally compact for note-property UIs: it contains only non-empty, commonly queried bibliographic fields plus Zotero/attachment identity and parse time. Null fields, raw objects, notes, annotations, attachment arrays, and verbose parser details are omitted. Complete path-safe provenance — including selected raw Zotero metadata, any exact-match enrichment donor, notes, annotations, attachments, and MinerU options — is written to the sibling `-scholar-assets/metadata.json`; indexed full text and local filesystem paths are not duplicated. Zotero and the selected PDF are exposed as clickable `zotero://select/...` and `zotero://open-pdf/...` frontmatter links. Images use explicit relative paths such as `![](<./<document>-scholar-assets/figure-01.jpg>)`, so spaces and Unicode render correctly in Obsidian when the Markdown and sibling asset directory are copied together. The directory suffix, image prefix, metadata filename, and document separator are all configurable. Frontmatter tags preserve their original form in the metadata sidecar while the Obsidian-facing values replace whitespace (default `-`) and unsupported punctuation; for example, `frustrated Lewis pairs` becomes `frustrated-Lewis-pairs` and `Ni/NiOx@C` becomes `Ni/NiOx-C`.
+
+MinerU receives the PDF over the network; consult its privacy policy. MinerU and Ai4Scholar have quotas and may charge credits. Tokens, Authorization headers, and signed URLs are never put in output/YAML. Tool output is bounded to 50KB/2000 lines.
+
+</details>
+
+## 🔒 Security notes
+
+- Zotero access is hard-restricted in code to `http://localhost:23119/api` or `http://127.0.0.1:23119/api`, GET-only, with redirects disabled — an extension-level compromise or misconfiguration cannot be used to reach an arbitrary host or mutate your library.
+- MinerU requests must be HTTPS with no embedded credentials; signed upload/download URLs, bearer tokens, and raw error bodies are redacted from every thrown error and from tool output.
+- The downloaded MinerU result archive is validated before extraction (central-directory inspection, entry-count/size caps, symlink/encrypted-entry rejection, path-traversal and absolute-path rejection, duplicate-entry rejection) before any file is written to disk.
+- Publishing a parsed paper is transactional: work happens in a temporary staging directory, existing files are only replaced after the new content is fully written, and a crash or cancellation restores the prior state instead of leaving a partial Markdown/asset-directory pair.
+- The Ai4Scholar implementation is included directly in this repository and package; no other Pi extension is bundled or required, so an external `pi-ai4scholar` release cannot change installed behavior.
+
+## 🛠️ Development
+
+```sh
+npm install
+npm test
+npm run check
+npm run pack:check
+npm pack --dry-run
+```
+
+Tests use mocks and temporary files; they do not contact Zotero or MinerU.
+
+<details>
+<summary>🚀 Release process (maintainers)</summary>
+
+1. Bump `version` in `package.json`, update this README's install snippets if the version is pinned anywhere, and run `npm run prepublishOnly` locally (also runs automatically before `npm publish`).
+2. Tag and push: `git tag vX.Y.Z && git push origin main --tags`, then create a GitHub Release from the tag (`gh release create vX.Y.Z --generate-notes`).
+3. Publish to npm: `npm publish` (the package is scoped and marked `"publishConfig": {"access": "public"}`, so no extra `--access` flag is required).
+4. Verify with `pi install npm:@luffysolution/pi-scholar@X.Y.Z` in a scratch Pi session before announcing.
+
+</details>
+
+## 📄 License
+
+[MIT](./LICENSE) © pi-scholar contributors
+
+Third-party dependency notices: [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

package/README.md

@@ -1,134 +1,108 @@
-# pi-scholar
+# 📚 pi-scholar
 
-Pi-native TypeScript research workflow combining the tested `pi-ai4scholar` extension, read-only Zotero Desktop access, and MinerU's official Precision API. It writes ordinary UTF-8 Markdown and a sibling per-document `.assets` directory—no Obsidian, Vault, plugin, or database required.
+[![npm version](https://img.shields.io/npm/v/@luffysolution/pi-scholar.svg)](https://www.npmjs.com/package/@luffysolution/pi-scholar)
+[![GitHub release](https://img.shields.io/github/v/release/luffysolution-svg/pi-scholar)](https://github.com/luffysolution-svg/pi-scholar/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/node/v/@luffysolution/pi-scholar.svg)](https://nodejs.org)
 
-Published to npm as **`@luffysolution/pi-scholar`** (the unscoped name `pi-scholar` is already taken by an unrelated package). All in-product names — the `/pi-scholar` command, the `pi-scholar` skill, `pi_scholar_parse`, and `pi-scholar.config.json` — are unaffected by the npm scope.
+🌐 **简体中文** ｜ [English](./README.en.md)
 
-## Install
+Pi 原生的 TypeScript 一体化科研工作流：内置完整 Ai4Scholar 在线检索/引用功能、只读的本地 Zotero 访问，以及 MinerU 官方 Precision API。产出是普通的 UTF-8 Markdown 文件 + 同级资源目录——**不依赖 Obsidian、Vault、插件、数据库或其他 Pi 扩展**。
 
-Requires Node.js **>=22.19**, Pi **>=0.84.4**, Zotero **7+** with the Local API enabled, and Windows/macOS/Linux.
+> 📦 npm 包名为 **`@luffysolution/pi-scholar`**（带作用域）——不带作用域的 `pi-scholar` 已被一个无关的第三方包占用。命令 `/pi-scholar`、技能 `pi-scholar`、工具 `pi_scholar_parse`、配置文件名 `pi-scholar.config.json` 均不受此影响，只有 npm 包标识变了。
+
+## ✨ 功能一览
+
+- 🔎 **在线检索 + 本地匹配**：已直接集成原 `pi-ai4scholar` 的全部 REST、增强工具、动态 MCP 与 `/ai4scholar` 命令，并与本地 Zotero 条目做 DOI/标题精确匹配。
+- 🗂️ **完整元数据聚合**：`zotero_item` 一次性给出结构化作者、日期、DOI/ISBN/ISSN、标签、笔记、批注、附件与已选 PDF。
+- 🧬 **PDF 深度解析**：`pi_scholar_parse` 调用 MinerU 官方 API，识别公式/表格/版面，提取插图，安全落盘。
+- 📝 **干净的 Markdown 输出**：精简 YAML frontmatter + 完整溯源信息旁车文件 `metadata.json`，图片路径开箱即用（对 Obsidian 友好但不依赖它）。
+- 🔒 **安全默认值**：Zotero 请求锁死本地回环地址、MinerU 密钥全程脱敏、ZIP 解压前做路径穿越/符号链接校验、发布过程事务化。
+
+## 📦 安装
+
+**环境要求**：Node.js `>=22.19`、Pi `>=0.84.4`、Zotero `7+`（已开启 Local API）、Windows / macOS / Linux 均可。
 
 ```sh
 pi install npm:@luffysolution/pi-scholar
-pi install npm:@luffysolution/pi-scholar@0.1.0            # pinned
+pi install npm:@luffysolution/pi-scholar@0.2.0        # 指定版本
 pi install git:https://github.com/luffysolution-svg/pi-scholar.git#main
-pi install ./path/to/pi-scholar                            # local persistent install
-pi -e ./path/to/pi-scholar                                 # temporary development load
+pi install ./path/to/pi-scholar                        # 本地持久安装
+pi -e ./path/to/pi-scholar                              # 临时开发加载
+```
+
+安装后重启 Pi 或执行 `/reload`，然后确认以下工具/命令均可用：`zotero_collections`、`zotero_search`、`zotero_item`、`pi_scholar_parse`、内置的 `ai4scholar_*` 工具、`/ai4scholar`，以及 `/skill:pi-scholar`。
+
+更新 / 卸载：
+
+```sh
+pi update npm:@luffysolution/pi-scholar
+pi remove npm:@luffysolution/pi-scholar
 ```
 
-Restart Pi or run `/reload`. Verify `zotero_collections`, `zotero_search`, `zotero_item`, `pi_scholar_parse`, imported `ai4scholar_search`/`ai4scholar_paper`/`ai4scholar_cite`, and `/skill:pi-scholar`. Update/uninstall with `pi update npm:@luffysolution/pi-scholar` and `pi remove npm:@luffysolution/pi-scholar`.
+Ai4Scholar 源码现已直接维护在本仓库中，npm 安装不会再捆绑或运行依赖包 `pi-ai4scholar`。若以前单独安装过该扩展，建议执行 `pi remove npm:pi-ai4scholar`，避免重复注册同名工具。
+
+### 💬 `/pi-scholar` 对话命令
 
-Installing the package already supplies its pinned/tested `pi-ai4scholar` dependency. The upstream extension is imported exactly once; no Ai4Scholar client source is copied or reimplemented.
+安装完成后，在 Pi 聊天框输入 `/pi-scholar` 即可调用。
 
-**If `pi-ai4scholar` is already installed as its own top-level Pi extension**, remove it first with `pi remove npm:pi-ai4scholar` (or the `git:`/local source you used). Pi loads every installed extension independently, so a standalone `pi-ai4scholar` install and the copy bundled inside `pi-scholar` would both try to register the same `ai4scholar_*` tool names, and Pi refuses to load `pi-scholar` at all until the duplicate is removed.
+- **不带参数**：弹出单行输入对话框（"Pi Scholar：你想研究什么？"）。
+- **带参数**（如 `/pi-scholar 查找光热催化论文，并匹配本地 Zotero`）：跳过对话框，直接执行。
 
-### `/pi-scholar` command
+无论哪种方式，命令都会通过 Pi 的提示词模板展开机制，把请求转发给 `pi-scholar` 技能（等价于 `/skill:pi-scholar ...`），由模型在 Pi 正常的工具权限流程下规划并调用 `zotero_*` / `ai4scholar_*` / `pi_scholar_parse`——**命令本身从不直接访问 Zotero 或 MinerU**。
 
-Once installed, type `/pi-scholar` inside Pi's chat. With no arguments it opens a one-line input dialog ("Pi Scholar：你想研究什么？"); with arguments (e.g. `/pi-scholar 查找光热催化论文，并匹配本地 Zotero`) it skips the dialog. Either way it hands your request to the `pi-scholar` skill (`/skill:pi-scholar ...`) through Pi's normal prompt-template expansion, so the model plans and calls `zotero_*`/`ai4scholar_*`/`pi_scholar_parse` under Pi's usual tool-permission flow — the command itself never calls Zotero or MinerU directly. In print/JSON/non-interactive Pi modes (`ctx.hasUI === false`), you must pass the request inline as an argument; there is no dialog to fall back on.
+> 在 print/JSON/非交互式 Pi 模式下（`ctx.hasUI === false`）没有对话框可用，必须把请求作为参数直接传入。
 
-### Setup diagnostics (`npx`/`npm`, no Pi required)
+### 🩺 环境自检（`npx` / `npm`，无需 Pi）
 
-A small zero-dependency CLI ships alongside the extension for verifying your machine *before* or *after* installing into Pi. It never touches Zotero data beyond a bounded read-only reachability probe, and it cannot install or configure the Pi extension itself — only `pi install ...` does that.
+包内附带一个零依赖的诊断 CLI，用于在安装到 Pi **之前或之后**检查你的环境。它只做一次有边界的只读可达性探测，不会读取 Zotero 数据，也不能代替 `pi install ...` 完成扩展安装/配置。
 
 ```sh
-npx @luffysolution/pi-scholar doctor     # Node version, config discovery, Zotero reachability, MinerU token presence
+npx @luffysolution/pi-scholar doctor     # 检查 Node 版本、配置发现、Zotero 可达性、MinerU 令牌是否存在
 npx @luffysolution/pi-scholar --version
 npx @luffysolution/pi-scholar --help
 ```
 
-## Configuration
-
-Use one JSON file for Zotero, MinerU behavior, output location, asset naming, and tag formatting; copy `pi-scholar.config.example.json` to `pi-scholar.config.json` (or a user-level location, see below) and edit it. **Never commit `pi-scholar.config.json`** — it is already covered by `.gitignore`.
-
-### Discovery order
-
-1. `PI_SCHOLAR_CONFIG` environment variable — an explicit path (must exist, or Pi refuses to start the tool).
-2. The nearest `pi-scholar.config.json`, searched from the current working directory upward. Only used when the project directory is trusted by Pi (`ctx.isProjectTrusted()`), so an untrusted project cannot silently redirect output or the Zotero endpoint.
-3. `~/.config/pi-scholar/config.json` (all platforms, including Windows — use `%USERPROFILE%\.config\pi-scholar\config.json`).
-4. `~/.pi-scholar.json` as a last resort.
-5. Built-in defaults if none of the above exist.
-
-Relative `output.directory` and `zotero.dataDir` values resolve **relative to the config file's own directory**, not the current working directory. Environment variables (below) are read fresh on every tool call and always win over the JSON file, which is convenient for one-off overrides (e.g. CI, a temporary output directory) without editing the file.
-
-### Full reference
-
-```json
-{
-  "output": {
-    "directory": "F:/个人知识库",
-    "filenameSeparator": "+",
-    "assetsSuffix": ".assets",
-    "assetFilePrefix": "figure",
-    "metadataFileName": "metadata.json",
-    "tagSpaceReplacement": "-"
-  },
-  "zotero": {
-    "baseUrl": "http://127.0.0.1:23119/api",
-    "timeoutMs": 15000,
-    "maxItems": 5000
-  },
-  "mineru": {
-    "tokenEnv": "MINERU_API_TOKEN",
-    "timeoutMs": 600000,
-    "pollInitialMs": 3000,
-    "pollMaxMs": 15000,
-    "maxAttempts": 120,
-    "language": "en",
-    "enableFormula": true,
-    "enableTable": true,
-    "isOcr": false,
-    "modelVersion": "vlm"
-  }
-}
-```
+> 💡 若在 `pi-scholar` 项目自身目录内运行 `npx`，Node 的本地解析优先级可能导致命令行为异常；在其他任意目录运行则完全正常。
+
+## ⚙️ 配置
+
+所有配置项集中在**一个 JSON 文件**里，涵盖 Zotero 连接、MinerU 解析行为、输出位置、资源命名与标签格式。复制 [`pi-scholar.config.example.json`](./pi-scholar.config.example.json) 为 `pi-scholar.config.json` 并按需修改。
+
+**查找顺序**：`PI_SCHOLAR_CONFIG` 环境变量 → 就近的 `pi-scholar.config.json`（仅可信项目）→ `~/.config/pi-scholar/config.json` → `~/.pi-scholar.json` → 内置默认值。环境变量随时可覆盖 JSON 文件中的对应字段。
+
+> 📖 **完整字段参考、每个选项的默认值/取值范围/环境变量名，请查阅 [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)（[English](./docs/CONFIGURATION.en.md)）。**
 
-| Field | Env override | Default | Notes |
-|---|---|---|---|
-| `output.directory` | `PI_SCHOLAR_OUTPUT_DIR` | `~/pi-scholar` | Where `.md` files and `.assets` folders are published. May be an Obsidian vault folder, but Obsidian is never required. Resolved relative to the config file's directory when given as a relative path in JSON; resolved relative to `cwd` when given via the env var. |
-| `output.filenameSeparator` | `PI_SCHOLAR_FILENAME_SEPARATOR` | `+` | 1–3 characters from `[+._ -]`, joins `Author`, `Year`, `Title` in generated filenames. |
-| `output.assetsSuffix` | `PI_SCHOLAR_ASSETS_SUFFIX` | `.assets` | Sibling directory suffix, e.g. `Paper.assets/`. Must be a safe filename component (no path separators, max 64 UTF-8 bytes). |
-| `output.assetFilePrefix` | `PI_SCHOLAR_ASSET_FILE_PREFIX` | `figure` | Extracted image basename prefix, e.g. `figure-01.png`. |
-| `output.metadataFileName` | `PI_SCHOLAR_METADATA_FILE` | `metadata.json` | Sidecar filename inside the assets directory; must end in `.json`. |
-| `output.tagSpaceReplacement` | `PI_SCHOLAR_TAG_SPACE_REPLACEMENT` | `-` | `-` or `_`; character substituted for whitespace/unsupported punctuation in Obsidian-facing tags only (the metadata sidecar keeps the original Zotero tag text). |
-| `zotero.baseUrl` | `ZOTERO_BASE_URL` | `http://127.0.0.1:23119/api` | Must be exactly `http://localhost:23119/api` or `http://127.0.0.1:23119/api` — no other host, port, path, credentials, query, or fragment is accepted. This is enforced in code, not just documented. |
-| `zotero.dataDir` | `ZOTERO_DATA_DIR` | none | Zotero's data directory (contains `storage/`), only needed as a fallback when Zotero's own `file/view/url` endpoint cannot resolve a managed attachment's path. |
-| `zotero.timeoutMs` | `ZOTERO_TIMEOUT_MS` | `15000` | Per-request timeout, 1,000–120,000 ms. |
-| `zotero.maxItems` | `ZOTERO_MAX_ITEMS` | `5000` | Upper bound on paged results per call, 1–50,000. |
-| `mineru.tokenEnv` | — | `MINERU_API_TOKEN` | Names *which* environment variable holds the MinerU secret. The config file never stores the secret itself — only the variable name (must be uppercase, `[A-Z_][A-Z0-9_]*`). |
-| — | `MINERU_API_TOKEN` (always checked) or the variable named by `mineru.tokenEnv` | none | The actual MinerU API token. Required only for `pi_scholar_parse`; every other tool works without it. |
-| `mineru.timeoutMs` | `MINERU_TIMEOUT_MS` | `600000` | Overall extraction deadline, 10,000–3,600,000 ms. Individual HTTP attempts are separately capped at 60 s. |
-| `mineru.pollInitialMs` / `mineru.pollMaxMs` | `MINERU_POLL_INITIAL_MS` / `MINERU_POLL_MAX_MS` | `3000` / `15000` | Polling backoff bounds while MinerU extracts the PDF. |
-| `mineru.maxAttempts` | `MINERU_MAX_ATTEMPTS` | `120` | Max poll attempts, 1–1000. |
-| `mineru.language` | `MINERU_LANGUAGE` | `en` | MinerU OCR/layout language hint. |
-| `mineru.enableFormula` / `mineru.enableTable` | `MINERU_ENABLE_FORMULA` / `MINERU_ENABLE_TABLE` | `true` / `true` | Accepts `1/0`, `true/false`, `yes/no` (case-insensitive) via env. |
-| `mineru.isOcr` | `MINERU_IS_OCR` | `false` | Force OCR even for text-layer PDFs. |
-| `mineru.modelVersion` | `MINERU_MODEL_VERSION` | `vlm` | MinerU model version identifier. |
+内置 Ai4Scholar 功能沿用独立的密钥配置入口（密钥不会进入 `pi-scholar.config.json`）：`/ai4scholar setup`、`AI4SCHOLAR_API_KEY`、`AI4SCHOLAR_BASE_URL` 等。
 
-Every field is validated at load time (type, range, and — for filenames/URLs — safety checks); an invalid config file or environment variable throws a clear error instead of silently falling back. See `.env.example` for a documentation-only list of the same environment variables — **this package does not read `.env` files itself**; export the variables through your shell, OS, or Pi's own environment configuration.
+别忘了在 Zotero 设置里开启 **允许其他应用程序与 Zotero 通信**。所有 Zotero 请求都是无认证的本地回环 GET，且禁用重定向；切勿把 23119 端口暴露到公网。
 
-Ai4Scholar configuration remains owned by the directly reused `pi-ai4scholar` extension: use `/ai4scholar setup`, `AI4SCHOLAR_API_KEY` (or legacy `AI4S_API_KEY`), `AI4SCHOLAR_BASE_URL`, `AI4SCHOLAR_TIMEOUT_MS`, and its proxy settings.
+## 🔍 工作原理
 
-Enable **Allow other applications on this computer to communicate with Zotero** in Zotero settings. Zotero requests are unauthenticated loopback GETs only, with redirects disabled. Never expose port 23119 externally.
+<details>
+<summary>点此展开详细行为说明</summary>
 
-## Behavior
+**`zotero_collections`** 可以列出收藏夹、读取收藏夹元数据，或列出收藏夹下的顶层条目。
 
-`zotero_collections` can list collections, read collection metadata, or list a collection's top-level items. `zotero_item` maps raw records into one typed `Paper`: complete forward-compatible parent metadata, structured creators, original date/year, DOI/ISBN/ISSN, publication fields, tags/collections, child notes/attachments, PDF-child annotations, indexed-text availability, and selected PDF. When a parent is clearly sparse, missing bibliographic fields are filled only if Zotero contains exactly one non-deleted item with the same normalized title and first author; the donor key, fields, and raw metadata are recorded for provenance. When no attachment key is supplied, PDFs are sorted by key and the first is selected and reported. Identifier matching uses normalized DOI first, then normalized title/year; nothing is written back to Zotero.
+**`zotero_item`** 把原始记录映射为一个类型化的 `Paper`：完整的向前兼容父级元数据、结构化作者、原始日期/年份、DOI/ISBN/ISSN、出版信息字段、标签/收藏夹、子笔记/附件、PDF 子项批注、全文索引可用性，以及已选 PDF。当父条目明显信息稀疏时，只有在 Zotero 中存在**恰好一条**标准化标题与第一作者都相同的未删除条目时，才会补全缺失的文献字段，并记录来源条目键、字段与原始元数据以供溯源。未显式指定附件键时，按键排序选取第一个 PDF 并在结果中说明。标识符匹配优先使用标准化 DOI，其次是标准化标题/年份；**不会**向 Zotero 写回任何内容。
 
-`pi_scholar_parse` validates `%PDF-`, hashes SHA-256, requests an official MinerU signed upload, uploads raw bytes with PUT, polls with bounded backoff, downloads and safely inspects the ZIP, repairs local image links, and transactionally publishes. Result names are `FirstAuthor+Year+Title.md`; missing components use `UnknownAuthor`, `UnknownYear`, or `Untitled`. Invalid cross-platform characters and component `+` signs become spaces, reserved device names are prefixed, and UTF-8 length is bounded. Collisions use ` (2)`, ` (3)`, etc.—never a Zotero key. Reprocessing is recognized by the YAML `zotero://select/...` deep link (legacy `zotero_key` remains readable).
+**`pi_scholar_parse`** 校验 `%PDF-` 文件头、计算 SHA-256、向 MinerU 请求签名上传地址、用 PUT 上传原始字节、带退避策略轮询状态、下载并安全检查返回的 ZIP、修复本地图片链接，并以事务方式发布结果。生成的默认文件名格式为 `FirstAuthor-Year-Title.md`；缺失的部分用 `UnknownAuthor`、`UnknownYear` 或 `Untitled` 填充。跨平台非法字符与组件内的 `+` 会被替换为空格，保留设备名会加前缀，UTF-8 长度有上限。文件名冲突用 ` (2)`、` (3)` 等后缀区分——**从不**使用 Zotero 键。是否已经解析过，通过 YAML 中的 `zotero://select/...` 深链识别（旧版 `zotero_key` 字段仍可读取）。
 
-The YAML frontmatter is intentionally compact for note-property UIs: it contains only non-empty, commonly queried bibliographic fields plus Zotero/attachment identity and parse time. Null fields, raw objects, notes, annotations, attachment arrays, and verbose parser details are omitted. Complete path-safe provenance—including selected raw Zotero metadata, any exact-match enrichment donor, notes, annotations, attachments, and MinerU options—is written to the sibling `.assets/metadata.json`; indexed full text and local filesystem paths are not duplicated. Zotero and the selected PDF are exposed as clickable `zotero://select/...` and `zotero://open-pdf/...` frontmatter links. Images use explicit relative paths such as `![](<./<document>.assets/figure-01.jpg>)`, so spaces and Unicode render correctly in Obsidian when the Markdown and sibling asset directory are copied together. The directory suffix, image prefix, metadata filename, and document separator are configurable. Frontmatter tags preserve their original form in the metadata sidecar while the Obsidian-facing values replace whitespace (default `-`) and unsupported punctuation; for example, `frustrated Lewis pairs` becomes `frustrated-Lewis-pairs` and `Ni/NiOx@C` becomes `Ni/NiOx-C`.
+YAML frontmatter 刻意保持精简，只包含非空、常用于查询的文献字段，加上 Zotero/附件身份信息与解析时间；空字段、原始对象、笔记、批注、附件数组、详细解析参数均不出现在其中。完整的、路径安全的溯源信息——包括选中的原始 Zotero 元数据、任何精确匹配的补全来源、笔记、批注、附件、MinerU 参数——写入同级的 `-scholar-assets/metadata.json`；全文索引内容和本地文件系统路径不会重复存储。Zotero 条目与已选 PDF 分别以可点击的 `zotero://select/...` 和 `zotero://open-pdf/...` 链接出现在 frontmatter 中。图片使用显式相对路径，如 `![](<./<document>-scholar-assets/figure-01.jpg>)`，因此当 Markdown 文件与同级资源目录一起复制时，空格与 Unicode 文件名也能在 Obsidian 中正确渲染。资源目录后缀、图片前缀、元数据文件名与文件名分隔符均可配置。frontmatter 标签在元数据旁车文件中保留原始形式，而面向 Obsidian 的值会把空白和不受支持的标点替换掉（默认用 `-`）；例如 `frustrated Lewis pairs` 会变成 `frustrated-Lewis-pairs`，`Ni/NiOx@C` 会变成 `Ni/NiOx-C`。
 
-MinerU receives the PDF over the network; consult its privacy policy. MinerU and Ai4Scholar have quotas and may charge credits. Tokens, Authorization headers, and signed URLs are never put in output/YAML. Tool output is bounded to 50KB/2000 lines.
+MinerU 会通过网络接收 PDF 内容，请自行了解其隐私政策；MinerU 与 Ai4Scholar 均有用量配额，可能产生费用。令牌、Authorization 头与签名 URL 从不写入输出或 YAML。工具输出统一限制在 50KB / 2000 行以内。
 
-## Security notes
+</details>
 
-- Zotero access is hard-restricted in code to `http://localhost:23119/api` or `http://127.0.0.1:23119/api`, GET-only, with redirects disabled — an extension-level compromise or misconfiguration cannot be used to reach an arbitrary host or mutate your library.
-- MinerU requests must be HTTPS with no embedded credentials; signed upload/download URLs, bearer tokens, and raw error bodies are redacted from every thrown error and from tool output.
-- The downloaded MinerU result archive is validated before extraction (central-directory inspection, entry-count/size caps, symlink/encrypted-entry rejection, path-traversal and absolute-path rejection, duplicate-entry rejection) before any file is written to disk.
-- Publishing a parsed paper is transactional: work happens in a temporary staging directory, existing files are only replaced after the new content is fully written, and a crash or cancellation restores the prior state instead of leaving a partial `.md`/`.assets` pair.
-- No dependency on this project's own registry account is required at runtime: `pi-ai4scholar` is pinned to an exact version and bundled, so a compromised or yanked upstream release cannot silently change behavior after install.
+## 🔒 安全说明
 
-## Development
+- Zotero 访问在代码层面被硬性限制为 `http://localhost:23119/api` 或 `http://127.0.0.1:23119/api`，仅允许 GET，且禁用重定向——即便扩展本身被攻破或配置错误，也无法访问任意主机或修改你的文献库。
+- MinerU 请求必须使用 HTTPS 且不含内嵌凭据；签名上传/下载 URL、Bearer 令牌与原始错误响应体，会从所有抛出的错误与工具输出中脱敏。
+- 下载的 MinerU 结果压缩包在解压前会先做校验（中央目录检查、条目数/大小上限、拒绝符号链接/加密条目、拒绝路径穿越/绝对路径、拒绝重复条目），确保写盘前的安全性。
+- 发布解析结果是事务化的：先在临时暂存目录完成全部工作，只有新内容完全写入后才替换已有文件；中途崩溃或取消会恢复到发布前的状态，不会留下半成品的 `.md` / 资源目录。
+- Ai4Scholar 实现直接包含在本仓库与发布包中，不再依赖或捆绑另一个 Pi 扩展；安装时不会因外部 `pi-ai4scholar` 版本变化而改变行为。
+
+## 🛠️ 开发
 
 ```sh
 npm install
@@ -138,11 +112,20 @@ npm run pack:check
 npm pack --dry-run
 ```
 
-Tests use mocks and temporary files; they do not contact Zotero or MinerU.
+测试全部基于 mock 与临时文件，**不会**联网访问真实的 Zotero 或 MinerU。
+
+<details>
+<summary>🚀 发布流程（维护者参考）</summary>
+
+1. 在 `package.json` 中升级 `version`，如有需要同步更新 README 中带版本号的安装示例，本地运行 `npm run prepublishOnly`（`npm publish` 前也会自动执行）。
+2. 打标签并推送：`git tag vX.Y.Z && git push origin main --tags`，随后从该标签创建 GitHub Release：`gh release create vX.Y.Z --generate-notes`。
+3. 发布到 npm：`npm publish`（包已设置作用域并标记 `"publishConfig": {"access": "public"}`，无需额外的 `--access` 参数）。
+4. 发布公告前，先在一个临时 Pi 会话中用 `pi install npm:@luffysolution/pi-scholar@X.Y.Z` 验证安装无误。
+
+</details>
+
+## 📄 许可证
 
-## Release process
+[MIT](./LICENSE) © pi-scholar contributors
 
-1. Bump `version` in `package.json`, update this README's install snippets if the version is pinned anywhere, and run `npm run prepublishOnly` locally (also runs automatically before `npm publish`).
-2. Tag and push: `git tag vX.Y.Z && git push origin main --tags`, then create a GitHub Release from the tag (`gh release create vX.Y.Z --generate-notes`).
-3. Publish to npm: `npm publish` (the package is scoped and marked `"publishConfig": {"access": "public"}`, so no extra `--access` flag is required).
-4. Verify with `pi install npm:@luffysolution/pi-scholar@X.Y.Z` in a scratch Pi session before announcing.
+第三方依赖与致谢见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -1,5 +1,5 @@
 # Third-party notices
 
-`pi-scholar` depends on and invokes `pi-ai4scholar` 0.4.2 through its public default extension export. pi-ai4scholar is Copyright its contributors and licensed under the MIT License; its LICENSE is bundled by npm with that dependency.
+The Ai4Scholar integration was consolidated from the author's MIT-licensed `pi-ai4scholar` project and is now maintained directly in this repository; it is no longer a runtime or bundled package dependency.
 
-Zotero adapter and MinerU normalization behavior was informed by official Zotero Web API v3 and MinerU API documentation and by MIT-licensed reference implementations identified during design review. No Ai4Scholar request implementation is copied. See package dependency license files for runtime library notices.
+Zotero adapter and MinerU normalization behavior was informed by official Zotero Web API v3 and MinerU API documentation and by MIT-licensed reference implementations identified during design review. See package dependency license files for runtime library notices.

package/bin/pi-scholar.mjs

@@ -28,7 +28,7 @@ function printHelp() {
   console.log(`pi-scholar ${readPackageVersion()} -- setup/diagnostic helper (not the Pi extension itself)
 
 Usage:
-  npx pi-scholar doctor      Check Node version, discover config, probe Zotero (default)
+  npx pi-scholar doctor      Check Node, config, Zotero, MinerU, and Ai4Scholar (default)
   npx pi-scholar --version   Print the package version
   npx pi-scholar --help      Show this message
 
@@ -94,11 +94,15 @@ async function doctor() {
 
   const home = process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
   const { path: configPath, source } = discoverConfigPath(process.env, process.cwd(), home);
+  let scholarConfig = {};
   if (configPath) {
     console.log(`Config file: ${configPath} (source: ${source})`);
     const parsed = readJsonSafely(configPath);
     if (parsed.error) console.log(`  Could not read config: ${parsed.error}`);
-    else console.log(`  Sections present: ${Object.keys(parsed.value ?? {}).join(", ") || "(none)"}`);
+    else {
+      scholarConfig = parsed.value ?? {};
+      console.log(`  Sections present: ${Object.keys(scholarConfig).join(", ") || "(none)"}`);
+    }
   } else {
     console.log("Config file: none found (using built-in defaults; see pi-scholar.config.example.json)");
   }
@@ -108,10 +112,16 @@ async function doctor() {
   const zotero = await probeZotero(baseUrl);
   console.log(`  ${zotero.ok ? "OK" : "FAILED"}: ${zotero.detail}`);
 
-  const tokenEnv = process.env.PI_SCHOLAR_MINERU_TOKEN_ENV ?? "MINERU_API_TOKEN";
+  const tokenEnv = scholarConfig?.mineru?.tokenEnv ?? "MINERU_API_TOKEN";
   const hasToken = Boolean(process.env.MINERU_API_TOKEN ?? process.env[tokenEnv]);
   console.log(`MinerU token (${tokenEnv}): ${hasToken ? "set" : "not set (MinerU parsing will be unavailable)"}`);
 
+  const ai4AgentDir = process.env.PI_CODING_AGENT_DIR?.trim() || path.join(home, ".pi", "agent");
+  const ai4ConfigPath = path.join(ai4AgentDir, "ai4scholar.json");
+  const ai4Stored = existsSync(ai4ConfigPath) ? readJsonSafely(ai4ConfigPath).value?.apiKey : undefined;
+  const hasAi4Token = Boolean(process.env.AI4SCHOLAR_API_KEY || process.env.AI4S_API_KEY || ai4Stored);
+  console.log(`Ai4Scholar token: ${hasAi4Token ? "set" : "not set (run /ai4scholar setup or set AI4SCHOLAR_API_KEY)"}`);
+
   console.log(`\nNext steps:`);
   console.log(`  1. In Zotero: Settings > Advanced > enable "Allow other applications to communicate with Zotero".`);
   console.log(`  2. In Pi: pi install npm:${PKG_NAME}   (or the exact scoped/pinned name from the README)`);

package/docs/CONFIGURATION.en.md

@@ -0,0 +1,150 @@
+# ⚙️ Configuration Reference
+
+[中文版](./CONFIGURATION.md)
+
+`pi-scholar` uses **one JSON file** to configure the Zotero connection, MinerU parsing behavior, output location, asset naming, and tag formatting. Every field is validated at load time (type, range, and safety checks); an invalid config throws a clear error instead of silently falling back.
+
+## 📁 Where the config file lives
+
+Copy the repo-root [`pi-scholar.config.example.json`](../pi-scholar.config.example.json) to `pi-scholar.config.json` (or one of the user-level locations below) and edit it as needed.
+
+> ⚠️ **Never commit `pi-scholar.config.json`** — it's already covered by `.gitignore` since it typically contains your personal output path and other local details.
+
+### 🔍 Discovery order
+
+Checked in order, first match wins:
+
+1. **`PI_SCHOLAR_CONFIG` env var** — an explicit path; it must exist, or the tool refuses to start.
+2. **The nearest `pi-scholar.config.json`**, searched from the current working directory upward. Only used when the project directory is trusted by Pi (`ctx.isProjectTrusted()`), so an untrusted project can't silently redirect output or the Zotero endpoint.
+3. **`~/.config/pi-scholar/config.json`** — all platforms, including Windows (`%USERPROFILE%\.config\pi-scholar\config.json`).
+4. **`~/.pi-scholar.json`** — last resort.
+5. Built-in defaults if none of the above exist.
+
+### 📌 Path resolution
+
+- Relative `output.directory` / `zotero.dataDir` values in the **JSON file** resolve relative to the **config file's own directory**.
+- The same values set via **environment variables** resolve relative to the **runtime `cwd`**.
+- Environment variables are read fresh on every tool call and **always win over the JSON file** — convenient for one-off overrides (CI, a temporary output dir) without editing the file.
+
+## 📝 Full example
+
+```json
+{
+  "output": {
+    "directory": "F:/my-vault",
+    "filenameSeparator": "-",
+    "assetsSuffix": "scholar-assets",
+    "assetFilePrefix": "figure",
+    "metadataFileName": "metadata.json",
+    "tagSpaceReplacement": "-"
+  },
+  "zotero": {
+    "baseUrl": "http://127.0.0.1:23119/api",
+    "timeoutMs": 15000,
+    "maxItems": 5000
+  },
+  "mineru": {
+    "tokenEnv": "MINERU_API_TOKEN",
+    "timeoutMs": 600000,
+    "pollInitialMs": 3000,
+    "pollMaxMs": 15000,
+    "maxAttempts": 120,
+    "language": "en",
+    "enableFormula": true,
+    "enableTable": true,
+    "isOcr": false,
+    "modelVersion": "vlm"
+  }
+}
+```
+
+---
+
+## 📤 `output` — location & naming
+
+| Field | Env override | Default |
+|---|---|---|
+| `directory` | `PI_SCHOLAR_OUTPUT_DIR` | `~/pi-scholar` |
+| `filenameSeparator` | `PI_SCHOLAR_FILENAME_SEPARATOR` | `-` |
+| `assetsSuffix` | `PI_SCHOLAR_ASSETS_SUFFIX` | `scholar-assets` |
+| `assetFilePrefix` | `PI_SCHOLAR_ASSET_FILE_PREFIX` | `figure` |
+| `metadataFileName` | `PI_SCHOLAR_METADATA_FILE` | `metadata.json` |
+| `tagSpaceReplacement` | `PI_SCHOLAR_TAG_SPACE_REPLACEMENT` | `-` |
+
+<details>
+<summary>Field details</summary>
+
+- **`directory`**: Where generated `.md` files and sibling asset folders are published. May be an Obsidian vault folder, but Obsidian is never required. Relative paths in JSON resolve relative to the config file's directory; relative paths via env var resolve relative to `cwd`.
+- **`filenameSeparator`**: 1–3 characters from `[+._ -]` used to join `Author`, `Year`, `Title` in generated filenames.
+- **`assetsSuffix`**: Sibling asset-directory suffix. The default produces `Author-Year-Title-scholar-assets/`; values beginning with a letter/number are joined using `filenameSeparator`, while values carrying their own punctuation prefix (such as `.assets` or `_media`) are appended directly. Must be a safe filename component (no path separators, max 64 UTF-8 bytes).
+- **`assetFilePrefix`**: Extracted image basename prefix, e.g. `figure-01.png`.
+- **`metadataFileName`**: Sidecar filename inside the assets directory; must end in `.json`.
+- **`tagSpaceReplacement`**: `-` or `_`; character substituted for whitespace/unsupported punctuation in Obsidian-facing tags only (the metadata sidecar keeps the original Zotero tag text).
+
+</details>
+
+## 🗂️ `zotero` — local Zotero connection
+
+| Field | Env override | Default |
+|---|---|---|
+| `baseUrl` | `ZOTERO_BASE_URL` | `http://127.0.0.1:23119/api` |
+| `dataDir` | `ZOTERO_DATA_DIR` | none |
+| `timeoutMs` | `ZOTERO_TIMEOUT_MS` | `15000` |
+| `maxItems` | `ZOTERO_MAX_ITEMS` | `5000` |
+
+<details>
+<summary>Field details</summary>
+
+- **`baseUrl`**: Must be exactly `http://localhost:23119/api` or `http://127.0.0.1:23119/api` — no other host, port, path, credentials, query, or fragment is accepted. Enforced in code, not just documented.
+- **`dataDir`**: Zotero's data directory (contains `storage/`), only needed as a fallback when Zotero's own `file/view/url` endpoint cannot resolve a managed attachment's path.
+- **`timeoutMs`**: Per-request timeout, 1,000–120,000 ms.
+- **`maxItems`**: Upper bound on paged results per call, 1–50,000.
+
+</details>
+
+> Enable **Allow other applications on this computer to communicate with Zotero** in Zotero's settings. Zotero requests are unauthenticated loopback GETs only, with redirects disabled. Never expose port 23119 externally.
+
+## 🧬 `mineru` — PDF parsing behavior
+
+| Field | Env override | Default |
+|---|---|---|
+| `tokenEnv` | — | `MINERU_API_TOKEN` |
+| (actual token) | `MINERU_API_TOKEN` or the var named by `tokenEnv` | none |
+| `timeoutMs` | `MINERU_TIMEOUT_MS` | `600000` |
+| `pollInitialMs` / `pollMaxMs` | `MINERU_POLL_INITIAL_MS` / `MINERU_POLL_MAX_MS` | `3000` / `15000` |
+| `maxAttempts` | `MINERU_MAX_ATTEMPTS` | `120` |
+| `language` | `MINERU_LANGUAGE` | `en` |
+| `enableFormula` / `enableTable` | `MINERU_ENABLE_FORMULA` / `MINERU_ENABLE_TABLE` | `true` / `true` |
+| `isOcr` | `MINERU_IS_OCR` | `false` |
+| `modelVersion` | `MINERU_MODEL_VERSION` | `vlm` |
+
+<details>
+<summary>Field details</summary>
+
+- **`tokenEnv`**: Names *which* environment variable holds the MinerU secret. The config file never stores the secret itself — only the variable name (must be uppercase, `[A-Z_][A-Z0-9_]*`).
+- **The actual MinerU API token**: Required only for `pi_scholar_parse`; every other tool works without it.
+- **`timeoutMs`**: Overall extraction deadline. Individual HTTP attempts are separately capped at 60 s.
+- **`pollInitialMs` / `pollMaxMs`**: Polling backoff bounds while MinerU extracts the PDF.
+- **`maxAttempts`**: Max poll attempts, 1–1000.
+- **`language`**: MinerU OCR/layout language hint.
+- **`enableFormula` / `enableTable`**: Accepts `1/0`, `true/false`, `yes/no` (case-insensitive) via env.
+- **`isOcr`**: Force OCR even for text-layer PDFs.
+- **`modelVersion`**: MinerU model version identifier.
+
+</details>
+
+---
+
+## 🌱 Environment variable quick reference
+
+See [`.env.example`](../.env.example) at the repo root for a documentation-only list of all variables above. **This package does not read `.env` files itself** — export the variables through your shell, OS, or Pi's own environment configuration.
+
+## 🔗 Ai4Scholar configuration
+
+Ai4Scholar is now built directly into `pi-scholar`, but keeps its established separate configuration entry points for secret isolation and backward compatibility:
+
+- `/ai4scholar setup`
+- `AI4SCHOLAR_API_KEY` (legacy `AI4S_API_KEY`)
+- `AI4SCHOLAR_BASE_URL`
+- `AI4SCHOLAR_TIMEOUT_MS`
+- and its proxy settings