@luffysolution/omnischolar-pi 0.2.0 → 0.3.3

package/README.en.md

@@ -20,7 +20,7 @@ It can search public indexes, combine online records with your Zotero notes, sen
 - Generate or edit scientific illustrations with configured image services
 - Preserve local Markdown edits and place incoming conflict versions in `.conflicts/`
 
-OmniScholar exposes 38 tools. See the [tool list](docs/TOOLS.en.md).
+OmniScholar exposes 44 tools. See the [tool list](docs/TOOLS.en.md).
 
 <details>
 <summary>Install and connect an agent</summary>
@@ -106,7 +106,7 @@ Enable the service and fill in its API key to use Ai4Scholar, image generation,
 
 The root [`mcp.json`](mcp.json) is a reusable MCP stdio example. It intentionally contains no API keys: the MCP process reads the global [`omnischolar.config.example.json`](omnischolar.config.example.json), which can be created with `omnischolar config init`. The plugin copy is [`.mcp.json`](.mcp.json).
 
-Configure the Obsidian output location, paper folders, Markdown files, and parsed image assets with `output.rootDirectory`, `output.literatureDirectory`, `output.folderNameTemplate`, `output.filenameTemplate`, `output.filenameSeparator`, and `output.assetFilenameTemplate`; see [literature and output configuration](docs/RESEARCH.en.md).
+Configure the Obsidian output location, paper folders, Markdown files, parsed image assets, Zotero reading records, and structured analyses with `output.rootDirectory`, `output.literatureDirectory`, `output.source`, and `output.analysis`; see [literature and output configuration](docs/RESEARCH.en.md).
 
 ## Try it
 

package/README.md

@@ -25,7 +25,7 @@ OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、
 - 调用已配置的图片服务生成或编辑科研示意图
 - 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
 
-OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+OmniScholar 共提供 43 个工具，完整列表见[工具目录](docs/TOOLS.md)。
 
 <details>
 <summary>安装与部署</summary>

package/README.zh-CN.md

@@ -17,8 +17,9 @@ OmniScholar 通过本地 Python MCP 服务，为 Codex、Claude Code、Cursor、
 - 查询 Materials Project，并导出 JSON、CSV、Markdown 或 CIF
 - 调用已配置的图片服务生成或编辑科研示意图
 - 保留手工修改过的 Markdown，把待合并版本放入 `.conflicts/`
+- 将 Zotero PDF、笔记和批注保存到每篇文献的 `source/`，并将结构化分析保存到配置的 `Analysis/Single` 与 `Analysis/Multi`
 
-OmniScholar 共提供 38 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+OmniScholar 共提供 44 个工具，完整列表见[工具目录](docs/TOOLS.md)。
 
 ## 安装
 
@@ -67,7 +68,7 @@ codex plugin add omnischolar@omnischolar
 
 在 ChatGPT 桌面应用中重启应用，打开 **Plugins**，选择 **OmniScholar** Marketplace，然后安装或启用 **OmniScholar**。在 Codex CLI 中可运行 `/plugins` 浏览同一 Marketplace。
 
-插件会同时安装 8 个 Skills，并从 PyPI 最新版本启动本地 MCP：
+插件会同时安装 10 个 Skills，并从 PyPI 最新版本启动本地 MCP：
 
 ```sh
 uvx --from luffysolution-omnischolar@latest omnischolar mcp
@@ -197,6 +198,8 @@ OpenAlex、PubMed、arXiv 和 Crossref 无需 API key。其他服务按需启用
 | `scholar-search` | 文献、专利、作者、引用网络、期刊和数据集 |
 | `zotero-research` | 本地 Zotero 匹配、笔记、批注和附件 |
 | `paper-reading` | MinerU 解析，以及正文、公式、表格和图片精读 |
+| `literature-reading` | 全文、图表、公式、段落、比较和综述解读 |
+| `literature-retrieval` | 聚焦检索、段落定位和有界阅读上下文 |
 | `academic-citation` | 证据核对、引用候选、格式化和参考文献 |
 | `scientific-figure` | 科研图片生成、编辑、检查和标注 |
 | `materials-project` | 材料筛选、性质、计算来源、相数据和导出 |

package/docs/CONFIGURATION.en.md

@@ -62,6 +62,31 @@ The new-paper subfolder and file name can be customized as well:
 
 Paper and folder templates support `{author}`, `{year}`, `{title}`, and `{separator}`; `folderNameTemplate` controls each paper directory name. The shared separator accepts `-`, `+`, and `_` and is available to paper, folder, and attachment templates. Attachment filenames support `{index}`, `{original}`, `{extension}`, and `{separator}`. These settings affect new publications only; existing sync records keep the path stored in the manifest. Here, attachment means a parsed image asset, not the original Zotero PDF attachment.
 
+## Zotero reading records and structured analyses
+
+```json
+{
+  "output": {
+    "source": {
+      "directory": "source",
+      "copyPdf": true,
+      "pdfFilenameTemplate": "paper.pdf",
+      "zoteroReadingRecordFilename": "zotero-reading-record.md",
+      "embedPdf": true
+    },
+    "analysis": {
+      "singleDirectory": "Analysis/Single",
+      "multiDirectory": "Analysis/Multi",
+      "singleFilenameTemplate": "{analysisType}",
+      "comparisonFilenameTemplate": "{date}{separator}{topic}{separator}compare",
+      "reviewFilenameTemplate": "{date}{separator}{topic}{separator}review"
+    }
+  }
+}
+```
+
+The reading record keeps Zotero notes and PDF annotations in separate sections. `omnischolar_analysis` writes `full-read` or `targeted-reading` under the single-paper directory, and `compare` or `review` under the multi-paper directory. It records source fingerprints and relative links and does not overwrite local analysis edits by default.
+
 ## API keys
 
 API keys may be entered directly in the provider's `apiKey` field:

package/docs/CONFIGURATION.md

@@ -62,6 +62,48 @@ OmniScholar 使用 `schemaVersion: 1` 的 JSON 配置。可直接复制根目录
 
 文献和文件夹模板支持 `{author}`、`{year}`、`{title}`、`{separator}`；`folderNameTemplate` 控制每篇文献目录名。连接符目前支持 `-`、`+` 和 `_`，并由文献、文件夹、附件模板共用。附件图片模板支持 `{index}`、`{original}`、`{extension}`、`{separator}`。这些设置只影响新建文献，已有同步记录沿用 manifest 中的路径。这里的附件图片是解析生成的图片，不是 Zotero 原始 PDF 附件。
 
+## Zotero 阅读记录与结构化分析
+
+解析并发布论文时，OmniScholar 可以把选中的 Zotero PDF 复制到每篇文献目录的 `source/`，并生成 `zotero-reading-record.md`。该文件将 Zotero 笔记与 PDF 批注分成两个区块，保留批注类型、颜色、页码、标签、评论和 PDF 相对链接。笔记和批注是个人阅读记录，不应直接当作论文原文证据。
+
+```json
+{
+  "output": {
+    "source": {
+      "directory": "source",
+      "copyPdf": true,
+      "pdfFilenameTemplate": "paper.pdf",
+      "zoteroReadingRecordFilename": "zotero-reading-record.md",
+      "embedPdf": true
+    },
+    "analysis": {
+      "singleDirectory": "Analysis/Single",
+      "multiDirectory": "Analysis/Multi",
+      "singleFilenameTemplate": "{analysisType}",
+      "comparisonFilenameTemplate": "{date}{separator}{topic}{separator}compare",
+      "reviewFilenameTemplate": "{date}{separator}{topic}{separator}review"
+    }
+  }
+}
+```
+
+默认目录结构为：
+
+```text
+<output.rootDirectory>/
+├── Literatures/<paper>/source/
+│   ├── paper.pdf
+│   └── zotero-reading-record.md
+├── Analysis/Single/<paper>/
+│   ├── full-read.md
+│   └── targeted-reading.md
+└── Analysis/Multi/
+    ├── <date>-<topic>-compare.md
+    └── <date>-<topic>-review.md
+```
+
+使用 `omnischolar_analysis` 写入结构化分析。单篇分析使用 `full-read` 或 `targeted-reading`，多篇分析使用 `compare` 或 `review`。工具会写入来源 fingerprint 和相对链接；默认不覆盖手工修改的分析文件，而是返回冲突候选路径。
+
 ## API key
 
 API key 可以直接写入对应服务的 `apiKey`。例如：

package/docs/INSTALLATION.en.md

@@ -112,7 +112,7 @@ claude plugin install omnischolar@omnischolar --scope user
 
 Choose `--scope project` to share the enabled plugin through repository settings, or `--scope local` to enable it only for yourself in the current repository. If Claude reports `Run /reload-plugins to activate`, run that command before using the plugin.
 
-Claude Code copies the repository-root plugin into its versioned cache, discovers the nine folders under `skills/`, and starts `.mcp.json` automatically when the plugin is enabled. The MCP command uses the latest PyPI package:
+Claude Code copies the repository-root plugin into its versioned cache, discovers the ten folders under `skills/`, and starts `.mcp.json` automatically when the plugin is enabled. The MCP command uses the latest PyPI package:
 
 ```sh
 uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp

package/docs/INSTALLATION.md

@@ -112,7 +112,7 @@ claude plugin install omnischolar@omnischolar --scope user
 
 使用 `--scope project` 可通过仓库设置与协作者共享启用状态；使用 `--scope local` 则只在当前仓库为自己启用。如果 Claude 提示 `Run /reload-plugins to activate`，请先运行该命令。
 
-Claude Code 会把仓库根插件复制到版本化缓存，发现 `skills/` 下的 9 个 Skills，并在插件启用时自动启动 `.mcp.json`。MCP 命令使用 PyPI 最新包：
+Claude Code 会把仓库根插件复制到版本化缓存，发现 `skills/` 下的 10 个 Skills，并在插件启用时自动启动 `.mcp.json`。MCP 命令使用 PyPI 最新包：
 
 ```sh
 uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp

package/docs/RESEARCH.en.md

@@ -48,6 +48,14 @@ The combined view can include metadata, notes, annotations, attachment details,
 
 `zotero_item` defaults to metadata-only output; request `mode=aggregate` when notes, annotations, attachments, indexed text, or PDF selection are needed. After parsing, use `omnischolar_read` for cursor-based full-text reading or bounded figure, formula, paragraph, comparison, and review evidence. The complete Markdown remains in the output directory and is not returned to the agent by default.
 
+### Focused retrieval and reading contexts
+
+Use `omnischolar_focus` over parsed local publications for bounded BM25 + TF-IDF vector evidence retrieval. It returns matching paragraphs, headings, character ranges, and `paper.md#Lx-Ly` line locators rather than a complete Markdown document. Restrict it with `keys`, `section`, `topK`, and `maxPerDocument`. The local backend explicitly reports `strategy=hybrid-bm25-tfidf`, `vectorBackend=tfidf-local`, and `semantic=false`, so term-vector similarity is not presented as dense semantic embedding retrieval.
+
+Use `omnischolar_locate` for exact paragraph location in one paper, with phrase or all-term matching and Zotero key, title, section, and stable anchors. Use `omnischolar_read` with `mode=figures` for image paths, table Markdown, captions, and bounded figure/table context. The agent must still distinguish visual observation, caption text, author claims, and interpretation.
+
+For multi-turn reading, call `omnischolar_context` with `open`, then pass its `contextId` to `omnischolar_focus`, `omnischolar_locate`, or `omnischolar_read`. The cache stores selected evidence only; `get` is paginated and bounded, so it does not automatically re-inject a complete paper into the agent. `compare` and `review` can add per-paper evidence to the same context.
+
 Notes and annotations are personal reading context, not evidence from the publication. Check the paper itself before citing a claim.
 
 ## MinerU parsing
@@ -91,6 +99,10 @@ The output location and new-file naming can be customized in the global configur
 
 Supported paper filename variables are `{author}`, `{year}`, `{title}`, and `{separator}`; `folderNameTemplate` independently controls each paper directory name. `filenameSeparator` accepts `-`, `+`, and `_`, and is shared by paper, folder, and attachment templates. Attachment images support `assetFilenameTemplate` with `{index}`, `{original}`, `{extension}`, and `{separator}`. New papers are written under `rootDirectory/literatureDirectory`, with images under each paper directory's `assets/` folder. Existing manifest records keep their original paths so changing the configuration does not break incremental synchronization. Here, attachment images means parsed image assets, not the original Zotero PDF attachment.
 
+When `output.source.copyPdf` is enabled, the selected Zotero PDF is copied into each paper's `source/` directory and `zotero-reading-record.md` is generated. The record keeps Zotero notes and PDF annotations in separate sections, including annotation type, color, page, tags, comments, and relative PDF links. These are personal reading records, not independent paper evidence.
+
+Use `omnischolar_analysis` to write structured analyses: `full-read` and `targeted-reading` for one paper, and `compare` and `review` for multiple papers. By default, single-paper analyses are stored under `Analysis/Single/<paper>/` and multi-paper analyses under `Analysis/Multi/`; paths and filename templates are configurable under `output.source` and `output.analysis`.
+
 `omnischolar_sync` shows a plan before writing under `output.rootDirectory`. The directory can be a regular folder or part of an Obsidian vault.
 
 Sync distinguishes new content, no change, metadata changes, parse changes, render changes, missing files, conflicts, exclusions, and interrupted recovery. Metadata repair, rerendering, and transaction recovery do not upload a PDF.

package/docs/RESEARCH.md

@@ -48,6 +48,14 @@ http://127.0.0.1:23119/api
 
 `zotero_item` 默认返回元数据；需要笔记、批注或 PDF 选择时再显式使用 `mode=aggregate`。已解析文献使用 `omnischolar_read` 按全文游标、图表、公式、段落、对比或综述模式分段读取，完整 Markdown 仍保存在输出目录，不会默认一次返回给 Agent。
 
+### 聚焦检索与阅读上下文
+
+已解析的本地文献可以用 `omnischolar_focus` 做有界的 BM25 + TF-IDF 向量混合证据检索。它返回匹配段落、章节、字符范围和 `paper.md#Lx-Ly` 行定位，不返回整篇 Markdown；可用 `keys`、`section`、`topK` 和 `maxPerDocument` 限定范围。当前本地后端会明确返回 `strategy=hybrid-bm25-tfidf`、`vectorBackend=tfidf-local` 和 `semantic=false`，因此不会把词项向量相似度误称为真正的语义 embedding 检索。
+
+需要单篇精确定位时使用 `omnischolar_locate`，按短语或全部词项匹配段落，并保留 Zotero key、标题、章节和定位锚点。图表读取使用 `omnischolar_read` 的 `figures` 模式，返回图片路径、表格 Markdown、标题以及受限的图表上下文；Agent 仍需区分图像观察、图注、作者结论和自己的解释。
+
+多轮阅读可以先用 `omnischolar_context` 的 `open` 创建上下文，再把 `contextId` 传给 `omnischolar_focus`、`omnischolar_locate` 或 `omnischolar_read`。缓存只保存选中的证据片段，`get` 仍然分页并受字符上限约束，不会自动把整篇论文再次注入 Agent。`compare` 和 `review` 模式也可以把每篇文献的有界证据加入同一个上下文。
+
 Zotero 笔记和批注属于个人阅读记录，不应当作论文原文证据。需要引用论文结论时，仍要核对原文。
 
 ## MinerU 解析
@@ -91,6 +99,17 @@ OmniScholar 不会自动把 Zotero 附件上传到 MinerU。应先确认具体
 
 支持的文献文件名变量为 `{author}`、`{year}`、`{title}` 和 `{separator}`；`folderNameTemplate` 单独控制每篇文献目录名。`filenameSeparator` 当前支持 `-`、`+` 和 `_`，会同时提供给文献、文件夹和附件模板。附件图片支持 `assetFilenameTemplate`，变量为 `{index}`、`{original}`、`{extension}` 和 `{separator}`。新文献会写入 `rootDirectory/literatureDirectory`，图片放在每篇文献目录下的 `assets/`。已有 manifest 记录会沿用原路径，避免改配置后破坏增量同步。这里的附件图片是解析结果中的图片，不是 Zotero 原始 PDF 附件。
 
+若 `output.source.copyPdf` 为 true，选中的 Zotero PDF 会复制到每篇文献目录的 `source/`，并生成 `zotero-reading-record.md`。该文件将 Zotero 笔记和 PDF 批注分成两个区块，批注保留类型、颜色、页码、标签、评论和 PDF 相对链接；它们属于个人阅读记录，不应直接作为论文原文证据。
+
+结构化解读通过 `omnischolar_analysis` 写入：
+
+- `full-read`：单篇 SCI 文献精读；
+- `targeted-reading`：单篇针对性解读，聚焦图表、公式、机制、方法、现有笔记和关联文献；
+- `compare`：用户选定多篇文献的紧凑对比矩阵；
+- `review`：多篇文献的主题性、叙述性、系统性或范围综述。
+
+默认输出为 `Analysis/Single/<paper>/` 和 `Analysis/Multi/`，路径和文件名由 `output.source`、`output.analysis` 配置。工具会保存来源 fingerprint 和相对链接，默认不会覆盖手工修改的分析文件。
+
 `omnischolar_sync` 会先给出计划，再写入 `output.rootDirectory`。该目录可以是普通文件夹，也可以位于 Obsidian Vault 中。
 
 同步会区分新建、无需更新、元数据变化、解析变化、渲染变化、文件缺失、冲突、排除和中断恢复。仅修复元数据、渲染或中断事务时不会上传 PDF。

package/docs/TOOLS.en.md

@@ -19,6 +19,10 @@ Tool and capability names match the values returned to agents.
 | `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
 | `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
 | `omnischolar_read` | literature | `literature.read`, `literature.fulltext`, `literature.figures`, `literature.formulas` | none | no | none | free |
+| `omnischolar_focus` | literature | `literature.focus`, `literature.retrieval`, `literature.evidence` | none | no | none | free |
+| `omnischolar_locate` | literature | `literature.locate`, `literature.paragraphs`, `literature.evidence` | none | no | none | free |
+| `omnischolar_context` | literature | `literature.context.open`, `literature.context.append`, `literature.context.read` | filesystem | no | none | free |
+| `omnischolar_analysis` | literature | `literature.analysis.write`, `literature.analysis.read` | filesystem | no | none | free |
 | `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
 | `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
 | `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |

package/docs/TOOLS.md

@@ -19,6 +19,10 @@
 | `zotero_search` | zotero | `zotero.search` | none | yes | none | free |
 | `zotero_item` | zotero | `zotero.item`, `zotero.aggregate` | none | yes | none | free |
 | `omnischolar_read` | literature | `literature.read`, `literature.fulltext`, `literature.figures`, `literature.formulas` | none | no | none | free |
+| `omnischolar_focus` | literature | `literature.focus`, `literature.retrieval`, `literature.evidence` | none | no | none | free |
+| `omnischolar_locate` | literature | `literature.locate`, `literature.paragraphs`, `literature.evidence` | none | no | none | free |
+| `omnischolar_context` | literature | `literature.context.open`, `literature.context.append`, `literature.context.read` | filesystem | no | none | free |
+| `omnischolar_analysis` | literature | `literature.analysis.write`, `literature.analysis.read` | filesystem | no | none | free |
 | `omnischolar_parse` | parsing | `pdf.parse`, `sync.publish` | external-upload | yes | mineru | metered |
 | `omnischolar_sync` | parsing | `sync.plan`, `sync.apply`, `sync.recovery` | filesystem | yes | none | free |
 | `ai4scholar_search` | ai4scholar | `ai4scholar.search` | paid | yes | ai4scholar | paid |

package/host-configs/README.md

@@ -8,4 +8,4 @@
 - Pi: see `pi.md`; the npm Extension bridges the local MCP server
 - WorkBuddy/CodeBuddy: merge `workbuddy.json` into `~/.codebuddy/.mcp.json` or project `.mcp.json`
 
-All supported MCP entries start the latest PyPI package with `uvx --from luffysolution-omnischolar@latest omnischolar mcp`. These files contain no provider credentials.
+All supported MCP entries start the latest PyPI package with `uvx --refresh-package luffysolution-omnischolar --from luffysolution-omnischolar@latest omnischolar mcp`. These files contain no provider credentials.

package/host-configs/hermes.yaml

@@ -1,6 +1,6 @@
 mcp_servers:
   omnischolar:
     command: "uvx"
-    args: ["--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"]
+    args: ["--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"]
     # Optional: restrict exposure with tools.include or tools.exclude.
     # Inherit OMNISCHOLAR_* and provider environment variables from Hermes.

package/host-configs/opencode.jsonc

@@ -3,7 +3,7 @@
   "mcp": {
     "omnischolar": {
       "type": "local",
-      "command": ["uvx", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
+      "command": ["uvx", "--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
       "enabled": true,
       "timeout": 10000
     }

package/host-configs/workbuddy.json

@@ -3,7 +3,7 @@
     "omnischolar": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
+      "args": ["--refresh-package", "luffysolution-omnischolar", "--from", "luffysolution-omnischolar@latest", "omnischolar", "mcp"],
       "description": "OmniScholar research tools"
     }
   }

package/omnischolar.config.example.json

@@ -265,6 +265,20 @@
     "filenameSeparator": "-",
     "assetFilenameTemplate": "image-{index}{extension}",
     "conflictDirectory": ".conflicts",
-    "safeWrites": true
+    "safeWrites": true,
+    "source": {
+      "directory": "source",
+      "copyPdf": true,
+      "pdfFilenameTemplate": "paper.pdf",
+      "zoteroReadingRecordFilename": "zotero-reading-record.md",
+      "embedPdf": true
+    },
+    "analysis": {
+      "singleDirectory": "Analysis/Single",
+      "multiDirectory": "Analysis/Multi",
+      "singleFilenameTemplate": "{analysisType}",
+      "comparisonFilenameTemplate": "{date}{separator}{topic}{separator}compare",
+      "reviewFilenameTemplate": "{date}{separator}{topic}{separator}review"
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luffysolution/omnischolar-pi",
-  "version": "0.2.0",
+  "version": "0.3.3",
   "description": "Pi MCP bridge for the OmniScholar research toolkit",
   "type": "module",
   "license": "MIT",

package/pi-extension/dist/index.js

@@ -1,7 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type } from "typebox";
-const CLIENT_INFO = { name: "omnischolar-pi", version: "0.2.0" };
+const CLIENT_INFO = { name: "omnischolar-pi", version: "0.3.3" };
 export function resultText(result) {
     return result.content
         .map((item) => {

package/skills/academic-citation/SKILL.md

@@ -2,7 +2,6 @@
 name: academic-citation
 description: Verify, format, and insert scholarly citations with OmniScholar. Use for APA, IEEE, GB/T 7714 and other styles, citation-network evidence, bibliography generation, candidate discovery, or verified citation insertion.
 license: MIT
-compatibility: Requires OmniScholar. Online verification needs an enabled literature provider; Ai4Scholar formatting and candidate operations require configured credentials.
 ---
 
 # Academic citation

package/skills/chemical-data/SKILL.md

@@ -2,7 +2,6 @@
 name: chemical-data
 description: Inspect CAS Common Chemistry contract status and query substance records only when a provider-issued API contract is configured. Use for chemical names, CAS Registry Numbers, structures, and basic compound information; not literature, reaction, or materials-property discovery.
 license: MIT
-compatibility: Requires OmniScholar. CAS search and detail remain contract-blocked unless the user supplies an authorized provider-issued endpoint/request/response contract.
 ---
 
 # Chemical substance data

package/skills/literature-reading/SKILL.md

@@ -1,33 +1,114 @@
 ---
 name: literature-reading
-description: Interpret parsed scholarly papers from OmniScholar with bounded full-text, figure, formula, paragraph, comparison, and review workflows. Use when the user wants to understand, compare, or synthesize papers rather than only retrieve metadata.
+description: Interpret SCI papers with bounded evidence, Zotero reading records, structured single-paper analyses, targeted figure/formula/knowledge reading, and compact multi-paper comparisons or reviews.
 license: MIT
 ---
 
-# Literature reading and interpretation
+# SCI literature reading
 
-Follow the user's language. Keep the original paper and generated Markdown on disk; expose only the evidence needed for the current reading mode.
+Follow the language of the user's latest request. Keep stable field names and analysis types in English, but write headings, explanations, tables, and conclusions in the user's language. Preserve paper titles, DOI strings, formulas, chemical names, gene names, and instrument/model names unless translation is explicitly requested.
 
-## Select a mode
+## Output locations
 
-- `full`: read the entire paper progressively with `omnischolar_read`, following `nextCursor` until `hasMore` is false. Summarize each section before moving on.
-- `figures`: retrieve figure/table asset paths, captions, and section context. Inspect the referenced local assets when the host supports image input; distinguish visual observations from captions and author claims.
-- `formulas`: retrieve bounded displayed formulas with their section headings. Explain symbols and assumptions only when supported by nearby text.
-- `paragraphs`: use `query` and optionally `section` to retrieve matching paragraphs instead of loading the document.
-- `compare`: pass multiple Zotero keys and retrieve compact, comparable metadata, abstracts, headings, and requested evidence.
-- `review`: pass multiple Zotero keys and build a literature-review evidence matrix. Preserve differences in methods, population/materials, outcomes, limitations, and confidence; do not merge claims merely because titles are similar.
+- MinerU Markdown, assets, copied PDF, and `zotero-reading-record.md` belong to the managed per-paper publication directory.
+- Single-paper analyses use `omnischolar_analysis` with `analysisType=full-read` or `analysisType=targeted-reading` and are saved under the configured `Analysis/Single` directory.
+- Multi-paper analyses use `analysisType=compare` or `analysisType=review` and are saved under the configured `Analysis/Multi` directory.
+- Never write analysis content into the managed MinerU Markdown file. Use the analysis tool so source fingerprints, relative links, and conflict handling are preserved.
 
-## Workflow
+## Source and reading-record policy
 
-1. Match a Zotero record by DOI, then normalized title/year/author; report ambiguity.
-2. Use `zotero_item` with `mode=item` for metadata and `mode=aggregate` only when notes, annotations, or attachment selection are needed.
-3. Confirm the selected PDF and run `omnischolar_sync` with `action=plan` before parsing.
-4. Parse only when structured content is necessary and external upload is authorized. `omnischolar_parse` returns a local publication path and parse metadata, not the full Markdown body.
-5. Use `omnischolar_read` for bounded evidence retrieval. Record Zotero key, Markdown path, heading, figure/table/formula identifier, and cursor where relevant.
-6. State OCR, layout, formula, table, and missing-text limitations. Never treat Zotero notes or annotations as independent evidence without labeling them.
+1. Match the Zotero parent by DOI first, then normalized title/year/author. Stop on ambiguity.
+2. Use `zotero_item` with `mode=item` for identity. Use `mode=aggregate` when notes, annotations, or attachment selection are needed.
+3. Run `omnischolar_sync` with `action=plan` before parsing or refreshing a paper.
+4. After parsing, use the generated source PDF and `source/zotero-reading-record.md` when available. Zotero notes and PDF annotations are personal reading records, not independent paper evidence.
+5. Separate every answer into original evidence, author interpretation, model interpretation, user reading record, and uncertainty.
 
-Full-text mode is intentionally paginated. Never bypass pagination by requesting an oversized result. If a retrieved excerpt is truncated, continue with its cursor rather than guessing the missing text.
+## Single-paper `full-read` template
 
-## Output
+Use this for a complete SCI-paper reading. The saved document must cover:
 
-Separate original evidence, interpretation, and uncertainty. For comparisons and reviews, use a table or evidence matrix with per-paper provenance. Do not expose credentials, signed URLs, or unrelated local files.
+1. bibliographic information and paper type;
+2. one-sentence summary;
+3. research background, gap, question, and hypothesis/objective;
+4. core innovation and contribution, with comparison to prior work when evidence exists;
+5. materials, samples, datasets, instruments, controls, variables, and experimental conditions;
+6. method and research design, including statistics, models, parameters, and reproducibility details;
+7. main results with quantitative values and figure/table references;
+8. paper conclusion, applicability, and limitations;
+9. reference/evidence index with paper section, page, figure/table/formula, and stable local link;
+10. a short `Zotero 阅读记录` navigation item that links to `source/zotero-reading-record.md`. Do not copy the note or annotation bodies into `full-read`; the source reading record is the canonical page for them.
+
+Do not fill unavailable experimental conditions, statistics, or sample information from general knowledge. Write `not reported`, `not available`, or `uncertain`.
+
+## Single-paper `targeted-reading` template
+
+Use this when the user asks about a mechanism, method, result, limitation, figure, table, equation, concept, or relationship to existing knowledge. Retrieve only the relevant evidence and include:
+
+- user question and scope;
+- relevant figures, tables, schemes, and equations;
+- exact or bounded evidence with locators;
+- visual observation, caption, author claim, and model interpretation as separate fields;
+- a link to relevant existing knowledge-base notes, prior saved analyses, and the Zotero reading record when they are available; do not duplicate long note/annotation bodies;
+- links to related papers and whether the relation is support, contradiction, extension, or merely topical similarity;
+- unresolved questions and confidence.
+
+For extracted figures, tables, and formulas:
+
+- Build a compact two-column Markdown table for figures and tables. The left column is `预览` and the right column is `图表名称、原文位置与分析解读`.
+- In the left column, embed available local figure images with a bounded Obsidian thumbnail such as `![[path/to/figure.png|260]]`; the embedded image must be clickable to the source asset/PDF context when the host supports it.
+- For tables, keep the left cell compact with a collapsible or bounded table preview; do not put a very wide table inside the right cell.
+- In the right column, keep separate lines for object name, source section/page, author caption, visual or tabular observation, and interpretation. Do not turn a caption into an unsupported scientific conclusion.
+- Render important equations as an ordered list. Each item must contain the equation in block math `$$ ... $$`, followed by variables, purpose, assumptions/conditions, and the paper-specific interpretation. Never show escaped formula source inside backticks.
+- If a figure caption or formula was not extracted reliably, say so and link to the PDF/source section instead of guessing.
+
+Do not regenerate the full paper reading unless the user asks for it.
+
+## Multi-paper `compare` template
+
+Use for a user-selected set of papers. This is a comparison, not a claim of exhaustive literature coverage.
+
+- State the comparison question and dimensions first.
+- Confirm paper identity, DOI, year, journal, and Zotero key.
+- Use a compact evidence matrix. Prefer one dimension per row and one paper per column; split the matrix into multiple small tables when it becomes too wide.
+- Required dimensions normally include research question, material/sample/dataset, method/design, key conditions, main outcome, limitation, and evidence locator.
+- Follow the matrix with agreements, contradictions, condition-dependent differences, methodological effects, and remaining gaps.
+- Never merge conclusions because titles are similar; verify population/materials, conditions, outcome definitions, and uncertainty.
+
+## Multi-paper `review` template
+
+Use for a topic-level narrative or systematic/scoping review. State the review mode, question, corpus, time range, search/selection scope, and whether the result is exhaustive. Then provide:
+
+1. corpus overview;
+2. thematic or methodological taxonomy;
+3. compact evidence tables;
+4. progress and trends;
+5. consensus and controversies;
+6. bias, evidence limitations, and missing research;
+7. conclusion and future directions;
+8. per-paper source and evidence index.
+
+Do not call a bounded user-selected set a systematic review unless a systematic search and selection protocol was actually performed.
+
+## Sources and links
+
+Do not add your own duplicate `Sources` section. `omnischolar_analysis` appends one canonical `## Sources` section containing Obsidian links to the MinerU document, copied PDF, and `zotero-reading-record.md`. Use those links for navigation instead of manually constructing relative paths.
+
+## Update and follow-up workflow
+
+For a follow-up question about a previously read paper:
+
+1. Reuse the existing context only as a bounded working set.
+2. Check `omnischolar_sync` status/plan and the source fingerprint.
+3. Retrieve only missing sections, figures, formulas, annotations, or related-paper evidence.
+4. State what is new, changed, unchanged, and still uncertain.
+5. Write a new targeted analysis or update the existing analysis through `omnischolar_analysis`; never silently overwrite a user-modified file.
+
+For a changed PDF, mark the previous analysis as requiring review and regenerate only after the new source version has been verified.
+
+## Context discipline
+
+- Use `omnischolar_focus` before broad reading.
+- Use `omnischolar_locate` for exact phrases, numbers, identifiers, formulas, and claims.
+- Use `omnischolar_read` with bounded cursors for full sections.
+- Use `omnischolar_context` only for selected evidence and follow-up continuity.
+- Never put a complete paper, complete Zotero aggregate, or unbounded tool response into the model context.

package/skills/literature-retrieval/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: literature-retrieval
+description: Find focused evidence in parsed local papers, locate paragraphs, compare selected papers, and maintain a bounded reading context without loading whole documents.
+license: MIT
+---
+
+# Focused literature retrieval
+
+Use this workflow when the task is to find where a paper discusses a concept, method, result, limitation, or comparison dimension. Retrieval is evidence selection; it is not itself a scientific conclusion.
+
+## Workflow
+
+1. Match the Zotero parent by DOI first, then normalized title/year/author. If the match or PDF attachment is ambiguous, stop and report the choices.
+2. Use `zotero_item` with `mode=item` for identity. Use `mode=aggregate` only when attachment selection or annotations are needed.
+3. Confirm local parsed output with `omnischolar_sync` and `action=plan`. Parse only when structured content is needed and an external upload is authorized.
+4. Call `omnischolar_focus` with a short research concept, optional `keys`, `section`, `topK`, and `includeContext`. Treat returned `excerpt`, heading, paragraph ID, and line locator as the evidence packet.
+5. Call `omnischolar_locate` when the user needs exact paragraphs in one paper. Prefer `matchMode=phrase` for a quoted phrase and `allTerms` for a concept.
+6. Use `omnischolar_context` with `action=open` before a long multi-turn task. Pass its `contextId` to focus, locate, and `omnischolar_read`; retrieve the cache later with a bounded `get` call.
+7. For several papers, use `omnischolar_read` with `mode=compare` or `mode=review`, pass `contextId` when continuity is needed, and preserve per-paper provenance.
+
+## Retrieval policy
+
+- The current local retriever uses bounded BM25-style lexical retrieval plus a transparent TF-IDF vector score. It does not claim dense semantic embedding support; `semantic` remains `false` until a real embedding backend is configured.
+- Exact identifiers, formulas, material names, gene/protein names, numbers, and quoted phrases should be verified with `omnischolar_locate` or a section read even when focused search returns a hit.
+- `markdownPath` is a local provenance field. Do not expose unrelated local files, credentials, or Zotero private data.
+- A cache stores selected excerpts only. Never add an entire paper or an unbounded tool response to a context.
+- Distinguish extracted text, caption/table content, visual observations, author claims, interpretation, and uncertainty in the final answer.
+- Treat `zotero-reading-record.md` as a user-reading-record source. It contains two separate blocks: Zotero notes and PDF annotations. Do not merge either block into original-paper evidence.
+- When a single-paper answer must be persisted, use `omnischolar_analysis` with `analysisType=full-read` or `analysisType=targeted-reading`; do not write directly into MinerU Markdown.
+- When a multi-paper answer must be persisted, use `analysisType=compare` or `analysisType=review`. Keep tables compact: put dimensions in rows, split very wide comparisons into multiple tables, and retain per-paper evidence links.
+- Reuse the source PDF, MinerU Markdown, and reading record through relative links. A source change must be reported before relying on a previous analysis.
+- For persisted targeted reading, use Obsidian embeds for local figures, standard Markdown tables for tables, and `$$...$$` block math for formulas. Do not save raw absolute Windows paths or escaped formula source as the visible result.
+
+## Handoff to reading modes
+
+- `full`: follow `nextCursor` with `omnischolar_read`; never request an oversized page.
+- `figures`: use `omnischolar_read` with `mode=figures`; inspect the referenced asset when the host supports images, then separate caption, visual observation, and claim.
+- `formulas`: use `mode=formulas` and explain symbols only with nearby evidence.
+- `compare`/`review`: use bounded per-paper evidence and an evidence matrix; do not merge similar claims without checking methods and populations/materials.

package/skills/materials-project/SKILL.md

@@ -2,7 +2,6 @@
 name: materials-project
 description: Query Materials Project records, inspect structures and phase data, and export sourced results with OmniScholar. Use for materials screening, property retrieval, phase analysis, XRD capability checks, or JSON/CSV/Markdown/CIF export.
 license: MIT
-compatibility: Requires OmniScholar and a Materials Project API key. Simulated XRD additionally requires the optional local backend reported by the runtime.
 ---
 
 # Materials Project

package/skills/omnischolar/SKILL.md

@@ -13,8 +13,10 @@ Choose the smallest workflow that answers the request. Follow the user's languag
 - Literature, patents, authors, citation graphs, recommendations, journals, snippets, or datasets: follow `scholar-search`.
 - Local collections, metadata, notes, annotations, attachments, or PDF selection: follow `zotero-research`.
 - Structured PDF text, equations, tables, figures, or close reading: follow `paper-reading`.
+- Focused retrieval, paragraph location, evidence caching, or retrieval-first paper work: follow `literature-retrieval`.
 - Interpreting parsed papers, full-text reading, figure/formula analysis, comparisons, or literature reviews: follow `literature-reading`.
 - Citation evidence, candidates, formatting, or insertion: follow `academic-citation`.
+- Structured single-paper or multi-paper analysis output: follow `literature-reading` and persist with `omnischolar_analysis`.
 - Generated or edited illustrations: follow `scientific-figure`.
 - Materials Project records and exports: follow `materials-project`.
 - CAS substance records and contract status: follow `chemical-data`.
@@ -32,6 +34,7 @@ The generated configuration enables provider sections by default. Use providers
 5. Call `omnischolar_parse` only when structured PDF extraction is necessary and both configuration and the current tool call authorize external upload.
 6. Read generated content progressively and verify claims against retrieved evidence.
 7. Format citations only after identity and relevance checks.
+8. For saved analyses, keep `Analysis/Single` and `Analysis/Multi` as the only top-level analysis branches; use `full-read`, `targeted-reading`, `compare`, or `review` as the analysis type.
 8. Route image work by declared capability, then inspect the result for scientific errors.
 
 For Semantic Scholar, keep paper and author operations separate: use `literature_search`/`literature_get` for papers, `literature_graph` for recommendations and citation relations, and `literature_author` for author search, author detail, or an author's papers. Respect provider throttling and `Retry-After`; do not treat a transient 429 or 5xx as evidence that the API is unsupported.

package/skills/paper-reading/SKILL.md

@@ -2,7 +2,6 @@
 name: paper-reading
 description: Parse and analyze a selected local PDF with OmniScholar and MinerU. Use when the task needs structured full text, equations, tables, figures, captions, or close reading beyond metadata and Zotero notes.
 license: MIT
-compatibility: Requires OmniScholar; Zotero-based reading needs local Zotero, and external parsing needs configured MinerU access.
 ---
 
 # PDF parsing and close reading
@@ -20,4 +19,7 @@ Follow the user's language. MinerU receives PDF bytes over the network and may c
 7. Distinguish extracted text, visual observation, captions, and author claims. Cite exact sections or numbered objects where possible.
 8. State OCR, equation, table, or layout limitations that affect confidence.
 
+9. After successful publication, verify that the managed paper directory contains the configured `source/` PDF and `zotero-reading-record.md`. The reading record must keep Zotero notes and PDF annotations in separate sections, preserve annotation color/type/page/tag information, and link back to the copied PDF with relative paths.
+10. Use `omnischolar_analysis` to persist `full-read` or `targeted-reading` output under the configured single-paper analysis directory. Do not overwrite the MinerU source Markdown.
+
 Read [sync.md](references/sync.md) for managed-output states. If MinerU is unavailable, use bounded Zotero indexed text and notes when sufficient; otherwise report that structured full-text parsing is blocked. Never upload a different attachment as a fallback without explicit selection.

package/skills/zotero-research/SKILL.md

@@ -2,7 +2,6 @@
 name: zotero-research
 description: Search and inspect the user's local Zotero library with OmniScholar. Use for collections, bibliographic metadata, notes, annotations, attachments, indexed text, local-paper matching, or selecting a PDF without modifying Zotero.
 license: MIT
-compatibility: Requires OmniScholar and a running Zotero desktop instance with local application access enabled.
 ---
 
 # Read-only Zotero research