@luffysolution/omnischolar-pi 0.1.1 → 0.1.2

package/docs/INSTALLATION.en.md

@@ -1,9 +1,9 @@
-# Installation and agent setup
-
-[简体中文](INSTALLATION.md)
-
-## Install the Python command
-
+# Installation and agent setup
+
+[简体中文](INSTALLATION.md)
+
+## Install the Python command
+
 Python 3.11 or newer is required. Choose one installer:
 
 ```sh
@@ -13,32 +13,109 @@ python -m pip install luffysolution-omnischolar
 ```
 
 For development from a source checkout, replace the package name with `.`.
-
-Check the command:
-
-```sh
-omnischolar --version
-omnischolar doctor --json
-```
-
-## Install local MCP and Skills
-
-```sh
-omnischolar install --dry-run claude
-omnischolar install claude
-```
-
-`--dry-run` prints the planned changes without writing files. User scope is the default; use `--scope project` for repository-local configuration:
-
-```sh
-omnischolar install cursor --scope project
-```
-
-| Agent | User MCP | Project MCP | Skills |
-|---|---|---|---|
-| Codex | `~/.codex/config.toml` | `.codex/config.toml` | supported |
-| Claude Code | `~/.claude.json` | `.mcp.json` | supported |
-| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | supported |
+
+Check the command:
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+The Python command installation above is optional when you use the Codex plugin path below. The plugin runs the pinned PyPI package through `uvx` instead.
+
+## Install in the Codex app or Codex CLI
+
+This repository is a Codex Git marketplace. Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and verify that both commands are available:
+
+```sh
+codex --version
+uv --version
+```
+
+Add the marketplace and install OmniScholar:
+
+```sh
+codex plugin marketplace add luffysolution-svg/omnischolar --ref main
+codex plugin add omnischolar@omnischolar
+```
+
+Restart the ChatGPT desktop app after adding the marketplace. Open **Plugins**, switch to the **OmniScholar** source, and install or enable the plugin. Codex CLI users can run `/plugins` and choose the same entry.
+
+The installed plugin contains `plugin.json`, `skills/`, and `mcp.json`. Its MCP entry executes:
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+`uvx` creates an isolated environment and caches the exact release, so this route does not require a separate `pip install`. The first start requires package-index access. To fetch updates to the Git marketplace, run:
+
+```sh
+codex plugin marketplace upgrade omnischolar
+```
+
+To uninstall the plugin or remove its marketplace source:
+
+```sh
+codex plugin remove omnischolar@omnischolar
+codex plugin marketplace remove omnischolar
+```
+
+Removing the marketplace is optional and should be done only after removing plugins installed from it.
+
+## Install in Claude Code
+
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) first. From an interactive Claude Code session, run:
+
+```text
+/plugin marketplace add luffysolution-svg/omnischolar
+/plugin install omnischolar@omnischolar
+```
+
+Or use the shell commands for scripting and non-interactive setup:
+
+```sh
+claude plugin marketplace add luffysolution-svg/omnischolar
+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 eight folders under `skills/`, and starts `.mcp.json` automatically when the plugin is enabled. The MCP command is pinned to:
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+The first MCP start needs package-index access. Skills are namespaced with `omnischolar`, for example `/omnischolar:scholar-search` and `/omnischolar:zotero-research`.
+
+Update or remove the installation with:
+
+```sh
+claude plugin marketplace update omnischolar
+claude plugin uninstall omnischolar@omnischolar --scope user
+claude plugin marketplace remove omnischolar
+```
+
+Remove the marketplace only after uninstalling plugins that came from it.
+
+## Install local MCP and Skills
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
+`--dry-run` prints the planned changes without writing files. User scope is the default; use `--scope project` for repository-local configuration:
+
+```sh
+omnischolar install cursor --scope project
+```
+
+| Agent | User MCP | Project MCP | Skills |
+|---|---|---|---|
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` | supported |
+| Claude Code | `~/.claude.json` | `.mcp.json` | supported |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | supported |
 | OpenCode | `~/.config/opencode/opencode.json` | `opencode.jsonc` | supported |
 | Hermes | `~/.hermes/config.yaml` | manual MCP setup | supported |
 | Pi | npm Extension | npm Extension | supported |
@@ -47,60 +124,60 @@ omnischolar install cursor --scope project
 For Pi, `omnischolar install pi` installs `npm:@luffysolution/omnischolar-pi` with Pi's package manager and copies the Skills to the selected scope. The Extension starts the local `omnischolar mcp` process. The `pi` command and the Python `omnischolar` command must both be on `PATH`.
 
 WorkBuddy/CodeBuddy supports local stdio MCP servers. Its official documentation does not define a portable Skills directory, so only the MCP component is installed automatically.
-
-## Update, uninstall, and restore
-
-```sh
-omnischolar update claude
-omnischolar uninstall claude
-
-omnischolar mcp install claude
-omnischolar mcp status claude
-omnischolar mcp uninstall claude
-
-omnischolar install skills claude
-omnischolar update skills claude
+
+## Update, uninstall, and restore
+
+```sh
+omnischolar update claude
+omnischolar uninstall claude
+
+omnischolar mcp install claude
+omnischolar mcp status claude
+omnischolar mcp uninstall claude
+
+omnischolar install skills claude
+omnischolar update skills claude
 omnischolar uninstall skills claude
 
 omnischolar update pi
 omnischolar uninstall pi
-```
-
-A backup is created before each change. If the MCP handshake fails after installation, the previous configuration is restored automatically. To restore a reported backup yourself:
-
-```sh
-omnischolar rollback PATH_TO_BACKUP
-```
-
-Other MCP servers and Skills are left in place. The command stops if an existing `omnischolar` entry was not created by this installer or if a managed Skill was edited locally.
-
-## Use the official Skills CLI
-
-The Skills CLI is separate from Python and MCP installation. Print the command for an agent with:
-
-```sh
-omnischolar npx-skills cursor
-```
-
-For example:
-
-```sh
-npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
-npx skills update -p -y
-```
-
-These commands install Skills only; they do not install the `omnischolar` Python command.
-
-## If MCP does not connect
-
-1. Run `omnischolar --version` from the environment used by the agent.
-2. Run `omnischolar mcp status HOST` to inspect the installed path.
-3. Run `omnischolar doctor --json` to check configuration and output access.
-4. Restart the agent and inspect its MCP log.
-5. Before reinstalling, run `omnischolar install --dry-run HOST`.
-
-The only MCP server entry in this release is local stdio:
-
-```sh
-omnischolar mcp
-```
+```
+
+A backup is created before each change. If the MCP handshake fails after installation, the previous configuration is restored automatically. To restore a reported backup yourself:
+
+```sh
+omnischolar rollback PATH_TO_BACKUP
+```
+
+Other MCP servers and Skills are left in place. The command stops if an existing `omnischolar` entry was not created by this installer or if a managed Skill was edited locally.
+
+## Use the official Skills CLI
+
+The Skills CLI is separate from Python and MCP installation. Print the command for an agent with:
+
+```sh
+omnischolar npx-skills cursor
+```
+
+For example:
+
+```sh
+npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
+npx skills update -p -y
+```
+
+These commands install Skills only; they do not install the `omnischolar` Python command.
+
+## If MCP does not connect
+
+1. Run `omnischolar --version` from the environment used by the agent.
+2. Run `omnischolar mcp status HOST` to inspect the installed path.
+3. Run `omnischolar doctor --json` to check configuration and output access.
+4. Restart the agent and inspect its MCP log.
+5. Before reinstalling, run `omnischolar install --dry-run HOST`.
+
+The only MCP server entry in this release is local stdio:
+
+```sh
+omnischolar mcp
+```

package/docs/INSTALLATION.md

@@ -1,9 +1,9 @@
-# 安装与 Agent 配置
-
-[English](INSTALLATION.en.md)
-
-## 安装 Python 命令
-
+# 安装与 Agent 配置
+
+[English](INSTALLATION.en.md)
+
+## 安装 Python 命令
+
 需要 Python 3.11 或更高版本，任选一种方式：
 
 ```sh
@@ -13,32 +13,109 @@ python -m pip install luffysolution-omnischolar
 ```
 
 如需从源码开发安装，请将包名替换为 `.`。
-
-验证命令是否可用：
-
-```sh
-omnischolar --version
-omnischolar doctor --json
-```
-
-## 安装本地 MCP 与 Skills
-
-```sh
-omnischolar install --dry-run claude
-omnischolar install claude
-```
-
-`--dry-run` 只显示计划，不写文件。默认安装到当前用户；项目级配置使用 `--scope project`：
-
-```sh
-omnischolar install cursor --scope project
-```
-
-| Agent | 用户级 MCP | 项目级 MCP | Skills |
-|---|---|---|---|
-| Codex | `~/.codex/config.toml` | `.codex/config.toml` | 支持 |
-| Claude Code | `~/.claude.json` | `.mcp.json` | 支持 |
-| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | 支持 |
+
+验证命令是否可用：
+
+```sh
+omnischolar --version
+omnischolar doctor --json
+```
+
+如果采用下面的 Codex 插件安装方式，则无需预先安装上述 Python 命令；插件会通过 `uvx` 运行固定版本的 PyPI 包。
+
+## 安装到 Codex App 或 Codex CLI
+
+本仓库本身就是 Codex Git Marketplace。先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)，并确认两个命令可用：
+
+```sh
+codex --version
+uv --version
+```
+
+添加 Marketplace 并安装 OmniScholar：
+
+```sh
+codex plugin marketplace add luffysolution-svg/omnischolar --ref main
+codex plugin add omnischolar@omnischolar
+```
+
+添加 Marketplace 后请重启 ChatGPT 桌面应用，打开 **Plugins**，切换到 **OmniScholar** 来源，再安装或启用插件。Codex CLI 用户可以运行 `/plugins` 并选择同一条目。
+
+安装后的插件包含 `plugin.json`、`skills/` 和 `mcp.json`。其 MCP 配置执行：
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+`uvx` 会创建隔离环境并缓存该精确版本，因此无需另行运行 `pip install`。第一次启动需要能够访问 Python 包索引。若要更新 Git Marketplace：
+
+```sh
+codex plugin marketplace upgrade omnischolar
+```
+
+卸载插件或移除 Marketplace 来源：
+
+```sh
+codex plugin remove omnischolar@omnischolar
+codex plugin marketplace remove omnischolar
+```
+
+只有在已卸载其中插件后才建议移除 Marketplace 来源。
+
+## 安装到 Claude Code
+
+先安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)。在 Claude Code 交互会话中运行：
+
+```text
+/plugin marketplace add luffysolution-svg/omnischolar
+/plugin install omnischolar@omnischolar
+```
+
+在脚本或非交互式环境中可使用 shell 命令：
+
+```sh
+claude plugin marketplace add luffysolution-svg/omnischolar
+claude plugin install omnischolar@omnischolar --scope user
+```
+
+使用 `--scope project` 可通过仓库设置与协作者共享启用状态；使用 `--scope local` 则只在当前仓库为自己启用。如果 Claude 提示 `Run /reload-plugins to activate`，请先运行该命令。
+
+Claude Code 会把仓库根插件复制到版本化缓存，发现 `skills/` 下的 8 个 Skills，并在插件启用时自动启动 `.mcp.json`。MCP 命令固定为：
+
+```sh
+uvx --from luffysolution-omnischolar==0.1.2 omnischolar mcp
+```
+
+第一次启动 MCP 需要能够访问 Python 包索引。Skills 使用 `omnischolar` 命名空间，例如 `/omnischolar:scholar-search` 和 `/omnischolar:zotero-research`。
+
+更新或移除安装：
+
+```sh
+claude plugin marketplace update omnischolar
+claude plugin uninstall omnischolar@omnischolar --scope user
+claude plugin marketplace remove omnischolar
+```
+
+请在卸载来自该 Marketplace 的插件后再移除 Marketplace。
+
+## 安装本地 MCP 与 Skills
+
+```sh
+omnischolar install --dry-run claude
+omnischolar install claude
+```
+
+`--dry-run` 只显示计划，不写文件。默认安装到当前用户；项目级配置使用 `--scope project`：
+
+```sh
+omnischolar install cursor --scope project
+```
+
+| Agent | 用户级 MCP | 项目级 MCP | Skills |
+|---|---|---|---|
+| Codex | `~/.codex/config.toml` | `.codex/config.toml` | 支持 |
+| Claude Code | `~/.claude.json` | `.mcp.json` | 支持 |
+| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | 支持 |
 | OpenCode | `~/.config/opencode/opencode.json` | `opencode.jsonc` | 支持 |
 | Hermes | `~/.hermes/config.yaml` | 需手动设置 MCP | 支持 |
 | Pi | npm Extension | npm Extension | 支持 |
@@ -47,60 +124,60 @@ omnischolar install cursor --scope project
 对 Pi，`omnischolar install pi` 会通过 Pi 包管理器安装 `npm:@luffysolution/omnischolar-pi`，并把 Skills 复制到所选作用域。Extension 会启动本地 `omnischolar mcp` 进程，因此 `pi` 与 Python 的 `omnischolar` 命令都必须位于 `PATH`。
 
 WorkBuddy/CodeBuddy 支持本地 stdio MCP。其官方文档没有定义可移植的 Skills 目录，因此安装器只自动配置 MCP。
-
-## 更新、卸载与恢复
-
-```sh
-omnischolar update claude
-omnischolar uninstall claude
-
-omnischolar mcp install claude
-omnischolar mcp status claude
-omnischolar mcp uninstall claude
-
-omnischolar install skills claude
-omnischolar update skills claude
+
+## 更新、卸载与恢复
+
+```sh
+omnischolar update claude
+omnischolar uninstall claude
+
+omnischolar mcp install claude
+omnischolar mcp status claude
+omnischolar mcp uninstall claude
+
+omnischolar install skills claude
+omnischolar update skills claude
 omnischolar uninstall skills claude
 
 omnischolar update pi
 omnischolar uninstall pi
-```
-
-修改前会创建备份。若安装后的 MCP 握手失败，原配置会自动恢复。也可手动恢复命令返回的备份：
-
-```sh
-omnischolar rollback PATH_TO_BACKUP
-```
-
-已有的其他 MCP 服务和 Skills 不会被删除。若同名配置不属于 OmniScholar，或已安装的 Skill 被手工改过，命令会停止并说明冲突。
-
-## 使用官方 Skills CLI
-
-Skills CLI 与 Python/MCP 安装相互独立。先查看适合目标 Agent 的命令：
-
-```sh
-omnischolar npx-skills cursor
-```
-
-例如：
-
-```sh
-npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
-npx skills update -p -y
-```
-
-这组命令只安装 Skills，不会安装 `omnischolar` Python 命令。
-
-## MCP 连接失败
-
-1. 运行 `omnischolar --version`，确认 Agent 的 PATH 能找到该命令。
-2. 运行 `omnischolar mcp status HOST` 查看安装位置。
-3. 运行 `omnischolar doctor --json` 检查配置和输出目录。
-4. 重启 Agent，再查看其 MCP 日志。
-5. 若需重新安装，先运行 `omnischolar install --dry-run HOST`。
-
-OmniScholar 的 MCP 入口只有本地 stdio：
-
-```sh
-omnischolar mcp
-```
+```
+
+修改前会创建备份。若安装后的 MCP 握手失败，原配置会自动恢复。也可手动恢复命令返回的备份：
+
+```sh
+omnischolar rollback PATH_TO_BACKUP
+```
+
+已有的其他 MCP 服务和 Skills 不会被删除。若同名配置不属于 OmniScholar，或已安装的 Skill 被手工改过，命令会停止并说明冲突。
+
+## 使用官方 Skills CLI
+
+Skills CLI 与 Python/MCP 安装相互独立。先查看适合目标 Agent 的命令：
+
+```sh
+omnischolar npx-skills cursor
+```
+
+例如：
+
+```sh
+npx skills add luffysolution-svg/omnischolar --skill '*' -a cursor -y
+npx skills update -p -y
+```
+
+这组命令只安装 Skills，不会安装 `omnischolar` Python 命令。
+
+## MCP 连接失败
+
+1. 运行 `omnischolar --version`，确认 Agent 的 PATH 能找到该命令。
+2. 运行 `omnischolar mcp status HOST` 查看安装位置。
+3. 运行 `omnischolar doctor --json` 检查配置和输出目录。
+4. 重启 Agent，再查看其 MCP 日志。
+5. 若需重新安装，先运行 `omnischolar install --dry-run HOST`。
+
+OmniScholar 的 MCP 入口只有本地 stdio：
+
+```sh
+omnischolar mcp
+```

package/docs/MATERIALS.en.md

@@ -1,45 +1,45 @@
-# Materials and chemistry data
-
-[简体中文](MATERIALS.md)
-
-## Materials Project
-
-Materials Project uses these tools:
-
-| Tool | Use |
-|---|---|
-| `materials_capabilities` | Show supported data types, fields, and filters without a network call |
-| `materials_search` | Filter summary records by formula, elements, chemical system, stability, and related fields |
-| `materials_route_search` | Query specialized collections such as thermo |
-| `materials_get` | Retrieve one material by ID and data type |
-| `materials_advanced` | Retrieve phase data and, with a local backend, calculate XRD |
-| `materials_export` | Save existing results as JSON, CSV, Markdown, or CIF |
-
-Example:
-
-```json
-{
-  "schemaVersion": 1,
-  "data": {
-    "materialsProject": {
-      "enabled": true,
-      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY",
-      "maxPages": 5
-    }
-  }
-}
-```
-
-Keep formulas, element sets, chemical systems, material IDs, and task IDs distinct. Each collection accepts different filters; call `materials_capabilities` before building a specialized query.
-
-CIF export uses lattice and site data returned by the service and checks numeric values, occupancy, and coordinates. The exported P1 structure is an exchange representation, not a new symmetry analysis. Computed stability also does not establish experimental synthesizability.
-
-XRD needs an additional local calculation backend. Without it, `materials_advanced` returns `local_backend_required` rather than creating a plausible-looking diffraction curve.
-
-## CAS Common Chemistry
-
-CAS queries are enabled only when the config includes an endpoint and request/response description supplied by the service provider. An API key or website login alone is not enough.
-
-Without that information, `chemical_sources` reports `contract_blocked`; `chemical_search` and `chemical_get` do not guess an endpoint.
-
-CAS data remains subject to CAS licensing, including non-commercial restrictions where applicable.
+# Materials and chemistry data
+
+[简体中文](MATERIALS.md)
+
+## Materials Project
+
+Materials Project uses these tools:
+
+| Tool | Use |
+|---|---|
+| `materials_capabilities` | Show supported data types, fields, and filters without a network call |
+| `materials_search` | Filter summary records by formula, elements, chemical system, stability, and related fields |
+| `materials_route_search` | Query specialized collections such as thermo |
+| `materials_get` | Retrieve one material by ID and data type |
+| `materials_advanced` | Retrieve phase data and, with a local backend, calculate XRD |
+| `materials_export` | Save existing results as JSON, CSV, Markdown, or CIF |
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "data": {
+    "materialsProject": {
+      "enabled": true,
+      "apiKeyEnv": "OMNISCHOLAR_MATERIALS_PROJECT_API_KEY",
+      "maxPages": 5
+    }
+  }
+}
+```
+
+Keep formulas, element sets, chemical systems, material IDs, and task IDs distinct. Each collection accepts different filters; call `materials_capabilities` before building a specialized query.
+
+CIF export uses lattice and site data returned by the service and checks numeric values, occupancy, and coordinates. The exported P1 structure is an exchange representation, not a new symmetry analysis. Computed stability also does not establish experimental synthesizability.
+
+XRD needs an additional local calculation backend. Without it, `materials_advanced` returns `local_backend_required` rather than creating a plausible-looking diffraction curve.
+
+## CAS Common Chemistry
+
+CAS queries are enabled only when the config includes an endpoint and request/response description supplied by the service provider. An API key or website login alone is not enough.
+
+Without that information, `chemical_sources` reports `contract_blocked`; `chemical_search` and `chemical_get` do not guess an endpoint.
+
+CAS data remains subject to CAS licensing, including non-commercial restrictions where applicable.