@rol1n/pi-kit 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # pi-kit
 
-> Modular extensions and prompt templates for the [Pi Coding Agent](https://pi.dev), published as the **`@rol1n/pi-kit`** bundle and as standalone **`@rol1n/<extension>`** packages.
+> One package of modular extensions, prompt templates, and skills for the [Pi Coding Agent](https://pi.dev). Install **`@rol1n/pi-kit`**, then choose what loads through Pi settings.
 
 <p align="left">
   <b>English</b> •
@@ -14,19 +14,11 @@
 
 ## Install
 
-Install the default bundle:
-
 ```sh
 pi install npm:@rol1n/pi-kit
 ```
 
-Or install any standalone extension individually:
-
-```sh
-pi install npm:@rol1n/memory-log
-pi install npm:@rol1n/subagent
-pi install npm:@rol1n/multi-harness
-```
+The package includes **15 extension entrypoints, 7 prompt templates, and the worktree-studio skill**. Extensions and prompt commands load by default; skill instructions are read on demand. No separate extension packages are needed. See [Resource Selection](#resource-selection) to disable extensions or use an allowlist. Individual features may still require credentials, platform support, or activation (`/mem-log on` for background memory).
 
 Install from GitHub or a local checkout during development:
 
@@ -46,82 +38,165 @@ pi update --extensions
 
 ## Extensions
 
-Each top-level directory is a self-contained extension (`<name>/index.ts` + `README.md`). Detailed commands, parameters, and settings are documented in each extension's README:
-
-| Extension | Description | In `@rol1n/pi-kit` | Standalone Package |
-| :--- | :--- | :---: | :--- |
-| [ask-u-questions](ask-u-questions/README.md) | Interactive single-choice, multi-choice, and text dialogs | Yes | `@rol1n/ask-u-questions` |
-| [continue-signal](continue-signal/README.md) | Resume an idle agent via `/continue` or `Alt+C` | Yes | `@rol1n/continue-signal` |
-| [custom-providers](custom-providers/README.md) | Additional model providers and gateway registration | Yes | `@rol1n/custom-providers` |
-| [image-generate](image-generate/README.md) | Image generation tool and `/image-generate` model selector | Yes | `@rol1n/image-generate` |
-| [memory-log](memory-log/README.md) | Tiered asynchronous observational memory and instant compaction | Yes | `@rol1n/memory-log` |
-| [model-vision](model-vision/README.md) | Image understanding and OCR tool (`model_vision`) | No | `@rol1n/model-vision` |
-| [multi-harness](multi-harness/README.md) | Delegate tasks across `pi`, `codex`, `claude`, and `opencode` | Yes | `@rol1n/multi-harness` |
-| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor and statusline | Yes | `@rol1n/oai-subquota` |
-| [prompt-snipaste](prompt-snipaste/README.md) | Prompt snippet selector (`/snipaste`, `Alt+S`) with 7 built-in prompts | Yes | `@rol1n/prompt-snipaste` |
-| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path (`/screenshot`) | No | `@rol1n/screenshot` |
-| [srp-theme](srp-theme/README.md) | Last-prompt preview widget and real-time streaming TPS meter | Yes | `@rol1n/srp-theme` |
-| [subagent](subagent/README.md) | Delegate tasks to parallel Pi workers in tmux/Zellij or background processes | Yes | `@rol1n/subagent` |
-| [tui-asr](tui-asr/README.md) | Streaming voice dictation via Aliyun DashScope ASR (`/asr`, `Alt+M`) | Yes | `@rol1n/tui-asr` |
-| [web-reach](web-reach/README.md) | Keyless Exa MCP web search and multi-tier page extraction | No | `@rol1n/web-reach` |
-| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY / Zellij mouse-wheel reporting fix | Yes (Windows) | `@rol1n/windows-wheel-fix` |
-
-> Standalone packages with cross-extension dependencies (`tui-asr` / `image-generate` -> `@rol1n/custom-providers`, `multi-harness` -> `@rol1n/subagent`) declare standard npm `dependencies` and resolve them automatically on install.
+Each top-level extension directory has an `index.ts` entrypoint and an English README covering its commands, parameters, and configuration. All entries below are declared in `package.json`:
+
+| Extension | Description | Entry path for settings |
+| :--- | :--- | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | Interactive single-choice, multi-choice, and text dialogs | `ask-u-questions/index.ts` |
+| [continue-signal](continue-signal/README.md) | Resume an idle agent via `/continue` or `Alt+C` | `continue-signal/index.ts` |
+| [custom-providers](custom-providers/README.md) | Additional model providers and gateway registration | `custom-providers/index.ts` |
+| [image-generate](image-generate/README.md) | Image generation tool and `/image-generate` model selector | `image-generate/index.ts` |
+| [memory-log](memory-log/README.md) | Tiered observational memory, source recall, and safe compaction | `memory-log/index.ts` |
+| [model-vision](model-vision/README.md) | Image understanding and OCR (`model_vision`) | `model-vision/index.ts` |
+| [multi-harness](multi-harness/README.md) | Delegate across `pi`, `codex`, `claude`, and `opencode` | `multi-harness/index.ts` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor | `oai-subquota/index.ts` |
+| [prompt-snipaste](prompt-snipaste/README.md) | Generic selector for enabled Pi prompts (`/snipaste`, `Alt+S`) | `prompt-snipaste/index.ts` |
+| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path | `screenshot/index.ts` |
+| [srp-theme](srp-theme/README.md) | Last-prompt preview and streaming TPS meter | `srp-theme/index.ts` |
+| [subagent](subagent/README.md) | Parallel Pi workers in tmux/Zellij or background processes | `subagent/index.ts` |
+| [tui-asr](tui-asr/README.md) | DashScope voice dictation (`/asr`, `Alt+M`) | `tui-asr/index.ts` |
+| [web-reach](web-reach/README.md) | Keyless Exa MCP search and multi-tier page extraction | `web-reach/index.ts` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY / Zellij wheel fix; no-op elsewhere | `windows-wheel-fix/index.ts` |
 
 ---
 
-## Resource Selection
+## Skills
+
+The root [`skills/`](skills/) directory is declared through `pi.skills` and distributed in the same npm package. Skills are instructions, not extension code: Pi advertises their metadata and reads the full document when needed.
+
+| Skill | Purpose |
+| :--- | :--- |
+| [worktree-studio](skills/worktree-studio/SKILL.md) | Plan isolated Git-worktree alternatives, delegate implementation, collect real diffs and verification, and compare results without automatically integrating or deleting them |
+
+Invoke it explicitly with `/skill:worktree-studio Compare the viable approaches for this change`. Git and a suitable delegation runtime are needed for experiments; `multi_harness` and `subagent` are available options. The skill requires confirmation before creating worktrees or launching paid workers. It never treats exploration approval as permission to merge, commit, or discard results.
 
-`@rol1n/pi-kit` exposes 12 extension entrypoints and the 7 prompt templates bundled in [prompt-snipaste/prompts](prompt-snipaste/prompts/). Use `pi config` or filter loaded resources in `settings.json`:
+To load only this skill, without any kit extensions or prompt templates:
 
 ```json
 {
   "packages": [
     {
       "source": "npm:@rol1n/pi-kit",
-      "extensions": ["**/*.ts", "!tui-asr/**"],
-      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
+      "extensions": [],
+      "prompts": [],
+      "skills": ["skills/worktree-studio/SKILL.md"]
     }
   ]
 }
 ```
 
+Remove older local copies from configured skill locations to avoid duplicate skill names. Setting `"skills": []` on this package disables its skills independently of extensions and prompts.
+
 ---
 
-## Development & Publishing
+## Prompt Templates
 
-[kit.config.json](kit.config.json) controls bundle selection (`bundle`), inter-extension dependencies (`deps`), and release versions. The top-level `version` belongs to `@rol1n/pi-kit`; each extension can set its own `version`, otherwise it inherits the top-level version. Set explicit extension versions to release the kit and standalone packages independently.
+The root [`prompts/`](prompts/) directory is an independent, standard Pi resource, declared as `"pi": { "prompts": ["./prompts"] }` in `package.json`. It does not belong to or require the `prompt-snipaste` extension.
 
-### Automated releases
+Templates become normal Pi slash commands: [/ask-questions](prompts/ask-questions.md), [/delegate-exploration](prompts/delegate-exploration.md), [/diagnose-report](prompts/diagnose-report.md), [/frontend-tech-preset](prompts/frontend-tech-preset.md), [/orchestrator-mode](prompts/orchestrator-mode.md), [/session-kickoff](prompts/session-kickoff.md), and [/verify-not-assume](prompts/verify-not-assume.md). They remain available when `prompt-snipaste` is disabled, or even with `"extensions": []`.
 
-1. Update the code and bump the relevant version(s) in `kit.config.json`.
-2. Push to `main` with changes to `kit.config.json` or `package.json`, or manually run **Publish to npm** in GitHub Actions. Changes to the packaging script or workflow also trigger a release run.
-3. CI runs the same pipeline for both triggers:
+To use only the directory from a local checkout, reference it through the top-level `prompts` setting; no extension needs to be loaded:
 
-```sh
-npm run manifest
-npm run check
-npm run publish:ci -- all
+```json
+{
+  "prompts": ["/absolute/path/to/pi-kit/prompts"]
+}
 ```
 
-The workflow in [`.github/workflows/publish.yml`](.github/workflows/publish.yml) generates `package.json`, validates the layout, then publishes all standalone extensions in dependency order, followed by the kit. Already-published versions are skipped; versions are never bumped automatically. `bundle: false` excludes an extension from the kit, not from standalone publishing. Publishing runs do not overlap, and a new run does not cancel an active release. Code-only pushes do not trigger publishing.
+Existing filters using `prompt-snipaste/prompts/...` must be changed to `prompts/...` after updating.
+
+Conversely, `prompt-snipaste` is a generic composer for **any enabled Pi prompt templates** from personal, trusted project, or package sources. It has no required template names or bundled fallback library.
 
-You do not need to run `manifest` or publish locally for an npm release. CI generates the manifest only in its checkout and does not commit it back. For local or Git installs, run `npm run manifest` and commit the generated `package.json` when changing bundle selection or versions so the repository manifest stays in sync.
+---
+
+## Resource Selection
 
-### Local development and manual publishing
+Edit `~/.pi/agent/settings.json` (personal) or `.pi/settings.json` (project). Replace the existing `"npm:@rol1n/pi-kit"` string inside `packages` with an object; keep your other packages. **`source` belongs inside `packages[]`, not at the top level.** Paths are relative to the installed package root, not the startup listing's `@rol1n/pi-kit:...` labels.
 
-```sh
-# Sync the local manifest and validate all extensions
-npm run manifest
-npm run check
+### Disable selected extensions
 
-# Stage a standalone package into dist/<id>
-npm run prepare:extension -- memory-log
+This loads everything except voice dictation, web search/extraction, and the Windows wheel fix. Omitting `prompts` and `skills` keeps all 7 templates and the bundled skill available:
 
-# Optional local release; also accepts extensions, kit, or a single extension ID
-npm run publish:ci -- all
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": [
+        "!tui-asr/**",
+        "!web-reach/**",
+        "!windows-wheel-fix/**"
+      ]
+    }
+  ]
+}
 ```
 
+### Load only selected extensions
+
+This loads only memory and Pi subagents, with no bundled prompt commands or skills:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": ["memory-log/index.ts", "subagent/index.ts"],
+      "prompts": [],
+      "skills": []
+    }
+  ]
+}
+```
+
+### Filter rules
+
+| Setting | Effect |
+| :--- | :--- |
+| Property omitted | Load all resources of that type declared by the package |
+| `"extensions": []` | Disable all extension entrypoints, without disabling prompts or skills |
+| `"extensions": ["!tui-asr/**"]` | Load all entrypoints except matches |
+| `"extensions": ["memory-log/index.ts"]` | Load only matching entrypoints |
+| `"extensions": ["-tui-asr/index.ts"]` | Exclude one exact entry path |
+| `"prompts": ["prompts/diagnose-report.md"]` | Load only that prompt template |
+| `"prompts": []` | Disable all bundled prompt templates |
+| `"skills": []` | Disable all bundled skills |
+| `"skills": ["skills/worktree-studio/SKILL.md"]` | Load only that skill |
+
+Run `/reload` or restart Pi after editing. Alternatively, run `pi config` in a terminal to toggle discovered resources interactively. Use an allowlist if newly added extensions should remain disabled after future kit updates.
+
+### Dependencies and overlapping tools
+
+Filtering controls entrypoint loading, not installation or imports. `image-generate` and `tui-asr` initialize the shared `custom-providers` module themselves; exclude all three entries if you do not want those providers registered. `multi-harness` uses shared helpers from `subagent/mux.ts` without requiring the `subagent` tool entry to load. These files ship in the same package; there are no sibling npm packages to install.
+
+Disable overlapping entries when another package already provides the same tool, especially `web-reach` (`web_search`, `web_fetch`) and `image-generate` (`image_generate`). Extensions and the root `prompts/` resource are independent. Disabling `prompt-snipaste/index.ts` leaves template commands available; filtering out all kit prompts leaves the selector free to use enabled prompts from other sources.
+
+### Migrating from standalone packages
+
+This repository now releases only `@rol1n/pi-kit`. Previously published standalone versions remain on npm but receive no further releases from this workflow. Remove old standalone declarations before enabling the same extensions through the kit to avoid duplicate registration; use the filters above instead.
+
+---
+
+## Development & Publishing
+
+[package.json](package.json) is the single source of package metadata, the release version, published files, and Pi resources. Edit it directly; no manifest generation or standalone staging is needed. When adding an extension, list its directory in `files` and its entrypoint in `pi.extensions` so it is included by default. Add skills as `skills/<name>/SKILL.md` and prompt templates as `prompts/<name>.md`; the declared root resource directories already cover them.
+
+```sh
+npm run check                      # Validate the manifest and extension coverage
+npm test                           # Run offline memory-log and prompt selector tests
+npm pack --dry-run --ignore-scripts # Inspect the npm package contents
+```
+
+### Releases
+
+1. Make your changes and bump `version` directly in `package.json`.
+2. Push to `main`, or manually run **Publish to npm** in GitHub Actions.
+3. [The workflow](.github/workflows/publish.yml) validates the package, runs tests, and publishes **only the root `@rol1n/pi-kit` package** with npm provenance. Existing versions are skipped; registry/network errors fail the job rather than being treated as an unpublished version.
+
+Automatic runs watch `package.json`, the validation script, and the workflow itself. Code-only pushes do not publish; bump the version when ready to release. Runs are serialized without cancelling an active publish. CI uses the configured npm Trusted Publisher, or `NPM_TOKEN` if provided, and never rewrites the manifest or bumps versions.
+
+For an authorized local release, use the normal npm command: `npm publish --access public`.
+
 ---
 
 ## Acknowledgements

package/README_zh.md

@@ -1,6 +1,6 @@
 # pi-kit
 
-> 面向 [Pi Coding Agent](https://pi.dev) 的模块化扩展与提示词模板套件，支持作为 **`@rol1n/pi-kit`** 聚合包或 **`@rol1n/<extension>`** 独立包安装。
+> 面向 [Pi Coding Agent](https://pi.dev) 的模块化扩展、提示词模板与技能套件。只安装 **`@rol1n/pi-kit`** 一个包，通过 Pi 配置选择加载哪些功能。
 
 <p align="left">
   <a href="README.md"><b>English</b></a> •
@@ -14,19 +14,11 @@
 
 ## 安装
 
-安装默认聚合包：
-
 ```sh
 pi install npm:@rol1n/pi-kit
 ```
 
-或按需安装任意独立扩展包：
-
-```sh
-pi install npm:@rol1n/memory-log
-pi install npm:@rol1n/subagent
-pi install npm:@rol1n/multi-harness
-```
+包含 **15 个扩展入口、7 个提示词模板及 worktree-studio 技能**。扩展与提示词命令默认加载，技能正文按需读取；无需安装独立扩展包。通过[资源按需筛选](#资源按需筛选)禁用不需要的扩展，或仅启用指定功能。具体功能仍可能需要认证、平台支持或单独激活（例如 `/mem-log on` 开启后台记忆）。
 
 开发期间也可直接从 GitHub 或本地目录安装：
 
@@ -46,82 +38,165 @@ pi update --extensions
 
 ## 扩展列表
 
-仓库根目录下每个文件夹均为自包含扩展（`<name>/index.ts` + `README.md`）。各扩展的详细命令、参数与配置说明请参阅对应目录的 README：
-
-| 扩展目录 | 功能简介 | 默认纳入 `pi-kit` | 独立 npm 包名 |
-| :--- | :--- | :---: | :--- |
-| [ask-u-questions](ask-u-questions/README.md) | 交互式单选、多选与自由文本提问弹窗（共享 UI 锁） | Yes | `@rol1n/ask-u-questions` |
-| [continue-signal](continue-signal/README.md) | 通过 `/continue` 或 `Alt+C` 唤醒空闲智能体继续未完成任务 | Yes | `@rol1n/continue-signal` |
-| [custom-providers](custom-providers/README.md) | 自定义模型服务商与网关（Magpie、智谱、阿里百炼等）注册 | Yes | `@rol1n/custom-providers` |
-| [image-generate](image-generate/README.md) | OpenRouter / 百炼文生图与参考图生图工具及 `/image-generate` 模型选择器 | Yes | `@rol1n/image-generate` |
-| [memory-log](memory-log/README.md) | 分层异步观察记忆系统与零模型阻塞的确定性秒级压缩 | Yes | `@rol1n/memory-log` |
-| [model-vision](model-vision/README.md) | 本地与远程图片视觉理解、OCR 与 UI 诊断工具（`model_vision`） | No | `@rol1n/model-vision` |
-| [multi-harness](multi-harness/README.md) | 跨 `pi`、`codex`、`claude`、`opencode` 的多 CLI 协同委派运行时 | Yes | `@rol1n/multi-harness` |
-| [oai-subquota](oai-subquota/README.md) | OpenAI Codex 订阅额度（5h / 7d 窗口与重置时间）状态栏监控 | Yes | `@rol1n/oai-subquota` |
-| [prompt-snipaste](prompt-snipaste/README.md) | 提示词片段选择器（`/snipaste`、`Alt+S`），内置 7 个常用提示词模板 | Yes | `@rol1n/prompt-snipaste` |
-| [screenshot](screenshot/README.md) | 一键将最新 Windows / WSL 系统截图路径插入编辑器（`/screenshot`） | No | `@rol1n/screenshot` |
-| [srp-theme](srp-theme/README.md) | 编辑器下方最近提问预览组件与实时流式 TPS 速率仪表 | Yes | `@rol1n/srp-theme` |
-| [subagent](subagent/README.md) | 基于 tmux / Zellij 分屏或后台进程的并发 Pi 子智能体工具 | Yes | `@rol1n/subagent` |
-| [tui-asr](tui-asr/README.md) | 基于阿里百炼 Paraformer 的终端实时流式语音听写（`/asr`、`Alt+M`） | Yes | `@rol1n/tui-asr` |
-| [web-reach](web-reach/README.md) | 免 Key Exa MCP 网页搜索与多级网页正文提取（RSC / HTML / PDF / Jina） | No | `@rol1n/web-reach` |
-| [windows-wheel-fix](windows-wheel-fix/README.md) | 修复 Windows ConPTY / Zellij 下鼠标滚轮被误转为上下方向键的问题 | Yes (仅 Windows) | `@rol1n/windows-wheel-fix` |
-
-> 带有跨扩展依赖的独立包（`tui-asr` / `image-generate` 依赖 `@rol1n/custom-providers`，`multi-harness` 依赖 `@rol1n/subagent`）已声明标准 npm `dependencies`，单独安装时会自动拉取补全并激活所需依赖。
+每个扩展目录都有 `index.ts` 入口和英文 README，介绍对应命令、参数与配置。以下入口全部直接声明在 `package.json` 中：
+
+| 扩展 | 功能简介 | 配置中使用的入口路径 |
+| :--- | :--- | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | 交互式单选、多选与自由文本提问 | `ask-u-questions/index.ts` |
+| [continue-signal](continue-signal/README.md) | 通过 `/continue` 或 `Alt+C` 继续未完成任务 | `continue-signal/index.ts` |
+| [custom-providers](custom-providers/README.md) | 注册自定义模型服务商与网关 | `custom-providers/index.ts` |
+| [image-generate](image-generate/README.md) | 图片生成工具与 `/image-generate` 模型选择器 | `image-generate/index.ts` |
+| [memory-log](memory-log/README.md) | 分层观察记忆、原始对话溯源与安全压缩 | `memory-log/index.ts` |
+| [model-vision](model-vision/README.md) | 图片理解与 OCR（`model_vision`） | `model-vision/index.ts` |
+| [multi-harness](multi-harness/README.md) | 跨 `pi`、`codex`、`claude`、`opencode` 委派任务 | `multi-harness/index.ts` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex 订阅额度监控 | `oai-subquota/index.ts` |
+| [prompt-snipaste](prompt-snipaste/README.md) | 面向已启用 Pi 提示词的通用选择器（`/snipaste`、`Alt+S`） | `prompt-snipaste/index.ts` |
+| [screenshot](screenshot/README.md) | 插入最新 Windows / WSL 截图路径 | `screenshot/index.ts` |
+| [srp-theme](srp-theme/README.md) | 最近提问预览与实时流式 TPS 仪表 | `srp-theme/index.ts` |
+| [subagent](subagent/README.md) | tmux / Zellij 分屏或后台进程中的并发 Pi 子智能体 | `subagent/index.ts` |
+| [tui-asr](tui-asr/README.md) | 百炼语音听写（`/asr`、`Alt+M`） | `tui-asr/index.ts` |
+| [web-reach](web-reach/README.md) | 免 Key Exa MCP 搜索与多级网页正文提取 | `web-reach/index.ts` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY / Zellij 滚轮修复，其他平台无操作 | `windows-wheel-fix/index.ts` |
 
 ---
 
-## 资源按需筛选
+## 技能
+
+根目录 [`skills/`](skills/) 通过 `pi.skills` 声明，随同一个 npm 包分发。技能是工作流指导，不是扩展代码：Pi 先展示其名称与描述，需要时再读取完整内容。
+
+| 技能 | 用途 |
+| :--- | :--- |
+| [worktree-studio](skills/worktree-studio/SKILL.md) | 规划隔离的 Git worktree 方案实验，委派实现，收集真实 diff 与验证结果，再比较取舍，不自动集成或删除成果 |
+
+可显式使用 `/skill:worktree-studio 比较这次修改的可行实现方案`。实验需要 Git 和可用的委派运行时，`multi_harness`、`subagent` 都可以使用。创建 worktree 或启动付费 worker 前会要求确认；同意探索不等于授权合并、提交或删除结果。
 
-`@rol1n/pi-kit` 默认导出 12 个扩展入口与 [prompt-snipaste/prompts](prompt-snipaste/prompts/) 下的 7 个提示词模板。可通过 `pi config` 或在 `settings.json` 中按需过滤：
+只使用该技能，不加载 kit 的扩展和提示词：
 
 ```json
 {
   "packages": [
     {
       "source": "npm:@rol1n/pi-kit",
-      "extensions": ["**/*.ts", "!tui-asr/**"],
-      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
+      "extensions": [],
+      "prompts": [],
+      "skills": ["skills/worktree-studio/SKILL.md"]
     }
   ]
 }
 ```
 
+请移除其他已配置技能目录里的旧副本，避免同名冲突。在包配置中设置 `"skills": []` 可单独禁用技能，不影响扩展和提示词。
+
 ---
 
-## 构建与发布
+## 独立提示词目录
 
-[kit.config.json](kit.config.json) 统一管理聚合包选择（`bundle`）、扩展间的依赖关系（`deps`）与发布版本。顶层 `version` 属于 `@rol1n/pi-kit`；各扩展可以单独设置 `version`，未设置时继承顶层版本。为每个扩展显式设置版本即可让聚合包与独立包分别升级。
+根目录 [`prompts/`](prompts/) 是独立、标准的 Pi 资源，在 `package.json` 中通过 `"pi": { "prompts": ["./prompts"] }` 声明，不属于、也不依赖 `prompt-snipaste` 扩展。
 
-### 自动发布
+模板会成为普通 Pi 斜杠命令：[/ask-questions](prompts/ask-questions.md)、[/delegate-exploration](prompts/delegate-exploration.md)、[/diagnose-report](prompts/diagnose-report.md)、[/frontend-tech-preset](prompts/frontend-tech-preset.md)、[/orchestrator-mode](prompts/orchestrator-mode.md)、[/session-kickoff](prompts/session-kickoff.md)、[/verify-not-assume](prompts/verify-not-assume.md)。即使禁用 `prompt-snipaste`，或配置 `"extensions": []`，这些模板仍可单独使用。
 
-1. 修改代码，并在 `kit.config.json` 中提升需要发布的包的版本。
-2. 将包含 `kit.config.json` 或 `package.json` 变更的提交推送到 `main`，或在 GitHub Actions 手动运行 **Publish to npm**。修改打包脚本或工作流本身也会触发发布流程。
-3. 自动和手动触发均执行同一条流水线：
+如需只部署本地检出目录中的模板，可通过顶层 `prompts` 引用，无需加载任何扩展：
 
-```sh
-npm run manifest
-npm run check
-npm run publish:ci -- all
+```json
+{
+  "prompts": ["/absolute/path/to/pi-kit/prompts"]
+}
 ```
 
-[`.github/workflows/publish.yml`](.github/workflows/publish.yml) 会生成 `package.json`、校验扩展布局，再按依赖顺序发布所有独立扩展，最后发布聚合包。已存在的版本自动跳过，不会自动提升版本号。`bundle: false` 只表示不纳入聚合包，不影响独立发布。发布流程不会并行执行，新触发的流程也不会取消正在进行的发布。仅修改扩展代码不会触发发布。
+升级后，已有筛选配置中的 `prompt-snipaste/prompts/...` 路径需要改为 `prompts/...`。
+
+反过来，`prompt-snipaste` 是面向**任意已启用 Pi 提示词**的通用组合框架，可读取全局、已信任项目或其他包提供的模板，不依赖固定文件名，也没有内置模板兜底。
 
-发布 npm 包无需本地运行 `manifest` 或 `publish`。CI 只在运行目录中生成清单，不会自动提交回仓库。若使用本地或 Git 安装，调整聚合包选择或版本后仍应运行 `npm run manifest` 并提交生成的 `package.json`，保持仓库清单同步。
+---
+
+## 资源按需筛选
 
-### 本地开发与手动发布
+编辑全局 `~/.pi/agent/settings.json` 或项目 `.pi/settings.json`，将 `packages` 数组中原有的 `"npm:@rol1n/pi-kit"` 字符串替换为对象，保留其他包。**`source` 是 `packages[]` 内的字段，不是顶层字段。** 筛选路径相对于安装包根目录，不是启动列表里的 `@rol1n/pi-kit:...` 展示名称。
 
-```sh
-# 同步本地清单并校验所有扩展
-npm run manifest
-npm run check
+### 黑名单：禁用部分扩展
 
-# 将单个扩展构建到 dist/<id>
-npm run prepare:extension -- memory-log
+以下配置加载除语音听写、网页搜索与 Windows 滚轮修复之外的所有扩展。不写 `prompts` 和 `skills`，仍然提供全部 7 个模板及内置技能：
 
-# 可选的本地发布，也支持 extensions、kit 或单个扩展 ID
-npm run publish:ci -- all
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": [
+        "!tui-asr/**",
+        "!web-reach/**",
+        "!windows-wheel-fix/**"
+      ]
+    }
+  ]
+}
 ```
 
+### 白名单：只加载指定扩展
+
+以下配置只启用记忆与 Pi 子智能体，不加载内置提示词命令或技能：
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": ["memory-log/index.ts", "subagent/index.ts"],
+      "prompts": [],
+      "skills": []
+    }
+  ]
+}
+```
+
+### 筛选规则
+
+| 写法 | 效果 |
+| :--- | :--- |
+| 省略某个资源字段 | 加载包中声明的全部该类资源 |
+| `"extensions": []` | 禁用全部扩展入口，不影响提示词和技能 |
+| `"extensions": ["!tui-asr/**"]` | 加载除匹配项之外的全部扩展 |
+| `"extensions": ["memory-log/index.ts"]` | 只加载匹配入口 |
+| `"extensions": ["-tui-asr/index.ts"]` | 按精确路径排除一个入口 |
+| `"prompts": ["prompts/diagnose-report.md"]` | 只加载该提示词模板 |
+| `"prompts": []` | 禁用全部内置提示词模板 |
+| `"skills": []` | 禁用全部内置技能 |
+| `"skills": ["skills/worktree-studio/SKILL.md"]` | 只加载该技能 |
+
+修改后执行 `/reload` 或重启 Pi。也可以在终端运行 `pi config`，交互勾选并保存配置。如果不希望未来升级时自动启用新增扩展，请使用白名单。
+
+### 依赖与工具重名
+
+筛选控制入口加载，不会卸载文件或阻止其他入口导入模块。`image-generate` 和 `tui-asr` 会主动初始化共用的 `custom-providers`；若不希望注册这些服务商，需要同时排除三个入口。`multi-harness` 复用 `subagent/mux.ts`，不要求启用 `subagent` 工具入口。这些依赖均包含在同一个包内，无需再安装其他独立扩展包。
+
+如果其他包已经提供同名工具，请禁用重叠入口，尤其是 `web-reach`（`web_search`、`web_fetch`）和 `image-generate`（`image_generate`）。扩展与根目录 `prompts/` 资源彼此独立：禁用 `prompt-snipaste/index.ts` 后仍可使用模板命令；禁用全部 kit 提示词后，选择器仍可使用其他来源中已启用的提示词。
+
+### 从独立包迁移
+
+本仓库此后只发布 `@rol1n/pi-kit`。已发布的独立版本仍保留在 npm，但本工作流不再发布其新版本。请先移除旧独立包的配置，再通过聚合包启用相同扩展，避免重复注册；按需加载改用上述筛选配置。
+
+---
+
+## 构建与发布
+
+[package.json](package.json) 是包元数据、版本、发布文件及 Pi 资源的唯一配置来源，直接编辑即可，无需生成清单或构建独立包。新增扩展时，将目录加入 `files`、入口加入 `pi.extensions`，默认随包加载。技能放在 `skills/<name>/SKILL.md`，提示词放在 `prompts/<name>.md`，已声明的资源根目录会自动覆盖新增文件。
+
+```sh
+npm run check                      # 校验清单与扩展覆盖范围
+npm test                           # 运行离线 memory-log 与提示词选择器测试
+npm pack --dry-run --ignore-scripts # 检查 npm 包内容
+```
+
+### 发布
+
+1. 修改代码，直接提升 `package.json` 中的 `version`。
+2. 推送到 `main`，或在 GitHub Actions 手动运行 **Publish to npm**。
+3. [工作流](.github/workflows/publish.yml) 校验清单、运行测试，随后**仅发布根目录的 `@rol1n/pi-kit`**，附带 npm provenance。已发布版本自动跳过；查询遇到网络或注册表错误会使任务失败，不会误判为尚未发布。
+
+自动触发范围是 `package.json`、校验脚本和工作流本身。仅修改扩展代码不会发布，准备发布时请提升版本。任务串行执行，不取消进行中的发布。CI 使用已配置的 npm Trusted Publisher，或提供的 `NPM_TOKEN`；不会重写清单或自动升级版本。
+
+如需经授权后在本地发布，直接使用标准命令：`npm publish --access public`。
+
 ---
 
 ## 致谢

package/ask-u-questions/README.md

@@ -5,10 +5,10 @@ Interactive single-choice, multiple-choice, and free-text questions for Pi. Regi
 ## Install
 
 ```sh
-pi install npm:@rol1n/ask-u-questions
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`.
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions.
 
 ## Use
 

package/continue-signal/README.md

@@ -5,10 +5,10 @@ Resume an idle Pi agent with a visible continuation signal.
 ## Install
 
 ```sh
-pi install npm:@rol1n/continue-signal
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`.
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions.
 
 ## Commands and shortcuts
 

package/custom-providers/README.md

@@ -5,10 +5,10 @@ Registers additional model providers through Pi's native model registry and `/lo
 ## Install
 
 ```sh
-pi install npm:@rol1n/custom-providers
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`.
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions.
 
 ## Providers
 

package/image-generate/README.md

@@ -5,10 +5,12 @@ Generate images through OpenRouter or DashScope and save them to `.pi/generated-
 ## Install
 
 ```sh
-pi install npm:@rol1n/image-generate
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`. Installing this package automatically installs `@rol1n/custom-providers`.
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions.
+
+Uses `custom-providers` from the same kit; required provider registration is initialized automatically.
 
 ## Use
 

package/memory-log/README.md

@@ -7,10 +7,10 @@
 ## Install
 
 ```sh
-pi install npm:@rol1n/memory-log
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`. The extension loads with new-session memory disabled by default (`/mem-log on` to enable for the current session, or `"defaultEnabled": true` in settings).
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions. The extension loads with new-session memory disabled by default (`/mem-log on` to enable for the current session, or `"defaultEnabled": true` in settings).
 
 ---
 

package/model-vision/README.md

@@ -5,10 +5,10 @@ Analyze a local image or public HTTP(S) image URL with a vision model. Registers
 ## Install
 
 ```sh
-pi install npm:@rol1n/model-vision
+pi install npm:@rol1n/pi-kit
 ```
 
-Available as a standalone package (not enabled in `@rol1n/pi-kit` by default).
+Included and loaded by default in `@rol1n/pi-kit`. See [resource selection](../README.md#resource-selection) to disable this entry or load only selected extensions.
 
 ## Use