@luffysolution/omnischolar-pi 0.3.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 43 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.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 共提供 43 个工具，完整列表见[工具目录](docs/TOOLS.md)。
+OmniScholar 共提供 44 个工具，完整列表见[工具目录](docs/TOOLS.md)。
 
 ## 安装
 

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/RESEARCH.en.md

@@ -99,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

@@ -99,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

@@ -22,6 +22,7 @@ Tool and capability names match the values returned to agents.
 | `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

@@ -22,6 +22,7 @@
 | `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/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.3.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.3.0" };
+const CLIENT_INFO = { name: "omnischolar-pi", version: "0.3.3" };
 export function resultText(result) {
     return result.content
         .map((item) => {

package/skills/literature-reading/SKILL.md

@@ -1,34 +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`: use `omnischolar_focus` first to identify relevant sections, then 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, bounded analysis context, 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 `omnischolar_locate` for stable line/character anchors, or `query` and optionally `section` with `omnischolar_read` for bounded matching paragraphs.
-- `compare`: pass multiple Zotero keys and retrieve compact, comparable metadata, abstracts, headings, and requested evidence. Add `contextId` when later questions should reuse only the selected 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_focus` for cross-paper evidence retrieval, `omnischolar_locate` for exact paragraph anchors, and `omnischolar_read` for bounded mode-specific reading. Record Zotero key, Markdown path, heading, figure/table/formula identifier, line locator, and cursor where relevant.
-6. Open an `omnischolar_context` for multi-turn work and append only selected evidence. Context reads are paginated; they are not a substitute for the original paper.
-7. 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

@@ -25,6 +25,11 @@ Use this workflow when the task is to find where a paper discusses a concept, me
 - `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
 

package/skills/omnischolar/SKILL.md

@@ -16,6 +16,7 @@ Choose the smallest workflow that answers the request. Follow the user's languag
 - 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`.
@@ -33,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

@@ -19,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.