@rol1n/pi-kit 0.1.1 → 0.1.3

package/prompt-snipaste/README.md

@@ -1,20 +1,32 @@
 # prompt-snipaste
 
-Select prompt snippets to prepend or append to the next user message, with live preview and a session transcript card. Bundles 7 built-in prompt snippets under `prompts/`.
+A generic composer for Pi prompt templates: select snippets to prepend or append to the next user message, with live preview and a session transcript card. It ships no private template library and requires no particular prompt names.
 
 ## Install
 
 ```sh
-pi install npm:@rol1n/prompt-snipaste
+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
 
-Open with `/snipaste` or `Alt+S`. Navigate with arrow keys, toggle with `Space`, preview with `Tab`, confirm with `Enter`, and cancel with `Escape`.
+Open with `/snipaste` or `Alt+S`. Navigate with arrow keys, toggle with `Space`, preview with `Tab`, confirm with `Enter`, and cancel with `Escape`. A confirmed selection applies once, to the next user message.
 
-## Frontmatter
+## Prompt sources and filtering
+
+Pi owns discovery and filtering. The selector reads only prompt commands exposed by `pi.getCommands()`, including templates from personal configuration, trusted projects, and other packages. It does not scan package directories, read settings itself, or fall back to disabled templates.
+
+- Ordinary Markdown and standard Pi templates work without any snippet-specific metadata.
+- Add or change prompts through Pi's normal prompt directories or settings, then run `/reload`.
+- Package `prompts` filters are respected. With no enabled templates, the menu displays a notice and injects nothing.
+- Same-named files from different sources have independent identities based on their full source paths.
+- The kit's root [`prompts/`](../prompts/) directory is a separate resource. Disabling it does not disable the selector; disabling the selector does not disable native template commands.
+
+The selector composes template bodies as text; it does **not** invoke slash commands or expand positional argument placeholders such as `$1`. Use Pi's normal `/template args` invocation when argument expansion is needed.
+
+## Optional frontmatter
 
 ```markdown
 ---
@@ -25,3 +37,5 @@ order: 100
 ---
 Check correctness, error handling, and missing validation.
 ```
+
+All fields are optional. `name` overrides the menu label, `description` describes the template, `placement` defaults to `append`, and `order` defaults to `100`. Prepend snippets come first, followed by append snippets; each group is sorted by numeric order and name.

package/prompt-snipaste/index.ts

@@ -20,11 +20,11 @@ export default function promptSnipaste(pi: ExtensionAPI) {
 			return;
 		}
 
-		snippets = loadSnippets(ctx.cwd, pi);
+		snippets = loadSnippets(pi);
 		enabled = new Set([...enabled].filter((id) => snippets.some((s) => s.id === id)));
 
 		if (snippets.length === 0) {
-			ctx.ui.notify("No Markdown files found in prompt directories", "warning");
+			ctx.ui.notify("No enabled prompt templates. Add prompts in Pi settings, then /reload.", "warning");
 			updateWidget(ctx);
 			return;
 		}
@@ -50,14 +50,14 @@ export default function promptSnipaste(pi: ExtensionAPI) {
 	pi.on("session_start", (_event, ctx) => {
 		enabled = new Set();
 		pendingTurnSnippets = null;
-		snippets = loadSnippets(ctx.cwd, pi);
+		snippets = loadSnippets(pi);
 		updateWidget(ctx);
 	});
 
 	pi.on("input", async (_event, ctx) => {
 		if (enabled.size === 0) return undefined;
 
-		snippets = loadSnippets(ctx.cwd, pi);
+		snippets = loadSnippets(pi);
 		const active = snippets.filter((s) => enabled.has(s.id));
 		enabled = new Set();
 		updateWidget(ctx);

package/prompt-snipaste/snippets.ts

@@ -1,10 +1,6 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const BUNDLED_PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "prompts");
-import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Snippet } from "./types.ts";
 
 export function parseSnippet(filename: string, raw: string): Snippet | null {
@@ -48,159 +44,42 @@ export function parseSnippet(filename: string, raw: string): Snippet | null {
 	};
 }
 
-function resolveSnippetPath(rawPath: string, cwd: string): string {
-	const trimmed = rawPath.trim();
-	if (trimmed === "~" || trimmed.startsWith("~/") || (process.platform === "win32" && trimmed.startsWith("~\\"))) {
-		return resolve(homedir(), trimmed.replace(/^~[/\\]?/, ""));
-	}
-	if (isAbsolute(trimmed)) {
-		return resolve(trimmed);
-	}
-	const fromCwd = resolve(cwd, trimmed);
-	if (existsSync(fromCwd)) return fromCwd;
-	const fromAgent = resolve(getAgentDir(), trimmed);
-	if (existsSync(fromAgent)) return fromAgent;
-	return fromCwd;
-}
-
-function getSettingsPrompts(cwd: string, pi?: ExtensionAPI): string[] {
-	const results: string[] = [];
-
-	if (pi) {
-		try {
-			const settings = pi.getSettings();
-			if (Array.isArray(settings?.prompts)) {
-				results.push(...settings.prompts);
-				return results;
-			}
-		} catch {
-			// pi.getSettings() may throw before runner binds
-		}
-	}
-
-	const settingsFiles = [
-		join(getAgentDir(), "settings.json"),
-		join(cwd, CONFIG_DIR_NAME, "settings.json"),
-	];
-
-	for (const sf of settingsFiles) {
-		if (!existsSync(sf)) continue;
-		try {
-			const content = readFileSync(sf, "utf-8");
-			const parsed = JSON.parse(content.replace(/^\uFEFF/, ""));
-			if (Array.isArray(parsed?.prompts)) {
-				for (const p of parsed.prompts) {
-					if (typeof p === "string" && !results.includes(p)) {
-						results.push(p);
-					}
-				}
-			}
-		} catch {
-			// ignore JSON parse errors
-		}
-	}
+const UNREADABLE_PROMPT_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
 
-	return results;
-}
-
-export function loadSnippets(cwd: string, pi?: ExtensionAPI): Snippet[] {
+/**
+ * Pi owns prompt discovery, trust, and resource filtering. Consume only its
+ * enabled prompt commands; never scan directories or revive excluded templates.
+ */
+export function loadSnippets(pi: Pick<ExtensionAPI, "getCommands">): Snippet[] {
 	const seen = new Map<string, Snippet>();
-	const excludedNames = new Set<string>();
 
-	const loadedPromptPaths = pi?.getCommands()
-		.filter((command) => command.source === "prompt")
-		.map((command) => command.sourceInfo.path);
-	const defaultDirs = loadedPromptPaths ? [] : [
-		BUNDLED_PROMPTS_DIR,
-		join(getAgentDir(), "prompts"),
-		join(cwd, CONFIG_DIR_NAME, "prompts"),
-	];
-	const settingsPrompts = loadedPromptPaths ?? getSettingsPrompts(cwd, pi);
+	for (const command of pi.getCommands()) {
+		if (command.source !== "prompt") continue;
+		const path = resolve(command.sourceInfo.path);
+		if (!path.toLowerCase().endsWith(".md") || seen.has(path)) continue;
 
-	const processDirectory = (dir: string) => {
-		if (!existsSync(dir)) return;
-		let files: string[];
+		let raw: string;
 		try {
-			files = readdirSync(dir);
+			raw = readFileSync(path, "utf-8");
 		} catch (error) {
-			if (!(error instanceof Error) || !("code" in error)) throw error;
-			console.error(`Failed to read prompt directory ${dir}: ${error.message}`);
-			return;
+			if (!(error instanceof Error) || !("code" in error) || !UNREADABLE_PROMPT_CODES.has(String(error.code))) throw error;
+			console.error(`prompt-snipaste: cannot read enabled prompt ${path}: ${error.message}`);
+			continue;
 		}
-		for (const file of files) {
-			if (!file.endsWith(".md")) continue;
-			if (excludedNames.has(file)) continue;
-			const fullPath = join(dir, file);
-			try {
-				const snippet = parseSnippet(file, readFileSync(fullPath, "utf-8"));
-				if (snippet) seen.set(file, snippet);
-			} catch (error) {
-				if (!(error instanceof Error) || !("code" in error)) throw error;
-				console.error(`Failed to read prompt ${fullPath}: ${error.message}`);
-			}
+		const snippet = parseSnippet(basename(path), raw);
+		if (snippet) {
+			// Source paths, not basenames, keep same-named templates independent.
+			seen.set(path, {
+				...snippet,
+				id: path,
+				description: command.description ?? snippet.description,
+			});
 		}
-	};
-
-	const processFile = (filePath: string) => {
-		if (!existsSync(filePath) || !filePath.endsWith(".md")) return;
-		const filename = basename(filePath);
-		if (excludedNames.has(filename)) return;
-		try {
-			const snippet = parseSnippet(filename, readFileSync(filePath, "utf-8"));
-			if (snippet) seen.set(filename, snippet);
-		} catch (error) {
-			if (!(error instanceof Error) || !("code" in error)) throw error;
-			console.error(`Failed to read prompt file ${filePath}: ${error.message}`);
-		}
-	};
-
-	// Collect exclusions first
-	for (const raw of settingsPrompts) {
-		if (typeof raw !== "string") continue;
-		const trimmed = raw.trim();
-		if (trimmed.startsWith("-") || trimmed.startsWith("!")) {
-			const clean = trimmed.slice(1).trim();
-			excludedNames.add(basename(clean));
-		}
-	}
-
-	// 1. Load default prompt directories
-	for (const dir of defaultDirs) {
-		processDirectory(dir);
-	}
-
-	// 2. Load Pi's resolved prompts, or explicit settings paths without a runtime.
-	for (const raw of settingsPrompts) {
-		if (typeof raw !== "string") continue;
-		let trimmed = raw.trim();
-		if (trimmed.startsWith("-") || trimmed.startsWith("!")) continue;
-		if (trimmed.startsWith("+")) trimmed = trimmed.slice(1).trim();
-		if (!trimmed) continue;
-
-		const resolved = resolveSnippetPath(trimmed, cwd);
-		if (!existsSync(resolved)) continue;
-
-		try {
-			const stat = statSync(resolved);
-			if (stat.isDirectory()) {
-				processDirectory(resolved);
-			} else if (stat.isFile() && resolved.endsWith(".md")) {
-				processFile(resolved);
-			}
-		} catch (error) {
-			if (!(error instanceof Error) || !("code" in error)) throw error;
-			console.error(`Failed to inspect prompt path ${resolved}: ${error.message}`);
-		}
-	}
-
-	// Remove any excluded items
-	for (const ex of excludedNames) {
-		seen.delete(ex);
 	}
 
-	return Array.from(seen.values()).sort((a, b) => {
+	return [...seen.values()].sort((a, b) => {
 		if (a.placement !== b.placement) return a.placement === "prepend" ? -1 : 1;
 		if (a.order !== b.order) return a.order - b.order;
-		return a.name.localeCompare(b.name);
+		return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
 	});
 }

package/prompt-snipaste/types.ts

@@ -1,4 +1,5 @@
 export interface Snippet {
+	/** Absolute source path when loaded from Pi; stable across menu refreshes. */
 	id: string;
 	name: string;
 	description: string;

package/screenshot/README.md

@@ -8,7 +8,7 @@ Searches standard and localized `Pictures/Screenshots` and OneDrive screenshot d
 ## Install
 
 ```sh
-pi install npm:@rol1n/screenshot
+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.

package/screenshot/index.ts

@@ -0,0 +1,126 @@
+/**
+ * screenshot — Insert the latest Windows/WSL system screenshot path into Pi's editor.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const SCREENSHOT_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"]);
+const SKIP_USER_DIRS = /^(Public|Default|Default User|All Users|desktop\.ini)$/i;
+
+function isExpectedFileSystemError(error: unknown): boolean {
+  return error instanceof Error && "code" in error &&
+    ["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(String(error.code));
+}
+
+function isWindows(): boolean {
+  return process.platform === "win32";
+}
+
+function isWSL(): boolean {
+  if (process.platform !== "linux") return false;
+  if (process.env.WSL_DISTRO_NAME || process.env.WSLENV || existsSync("/mnt/c/Users")) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf-8"));
+  } catch (error) {
+    if (isExpectedFileSystemError(error)) return false;
+    throw error;
+  }
+}
+
+export function supportsScreenshots(): boolean {
+  return isWindows() || isWSL();
+}
+
+function findScreenshotDirs(): string[] {
+  const dirs = new Set<string>();
+  const addIfDirectory = (path: string) => {
+    try {
+      if (existsSync(path) && statSync(path).isDirectory()) dirs.add(path);
+    } catch (error) {
+      if (!isExpectedFileSystemError(error)) throw error;
+    }
+  };
+
+  if (isWindows()) {
+    const profile = process.env.USERPROFILE || process.env.HOME;
+    if (profile) {
+      addIfDirectory(join(profile, "Pictures", "Screenshots"));
+      addIfDirectory(join(profile, "Pictures", "屏幕截图"));
+      addIfDirectory(join(profile, "OneDrive", "Pictures", "Screenshots"));
+      addIfDirectory(join(profile, "OneDrive", "图片", "屏幕截图"));
+      addIfDirectory(join(profile, "OneDrive", "Pictures", "屏幕截图"));
+    }
+  }
+
+  if (isWSL()) {
+    const usersRoot = "/mnt/c/Users";
+    try {
+      for (const entry of readdirSync(usersRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || SKIP_USER_DIRS.test(entry.name)) continue;
+        const profile = join(usersRoot, entry.name);
+        addIfDirectory(join(profile, "Pictures", "Screenshots"));
+        addIfDirectory(join(profile, "Pictures", "屏幕截图"));
+        addIfDirectory(join(profile, "OneDrive", "Pictures", "Screenshots"));
+        addIfDirectory(join(profile, "OneDrive", "图片", "屏幕截图"));
+      }
+    } catch (error) {
+      if (!isExpectedFileSystemError(error)) throw error;
+    }
+  }
+
+  return [...dirs];
+}
+
+export function findLatestScreenshot(): string | null {
+  let latestPath: string | null = null;
+  let latestMtime = -1;
+
+  for (const dir of findScreenshotDirs()) {
+    let files: string[];
+    try {
+      files = readdirSync(dir);
+    } catch (error) {
+      if (isExpectedFileSystemError(error)) continue;
+      throw error;
+    }
+
+    for (const file of files) {
+      if (!SCREENSHOT_EXTENSIONS.has(extname(file).toLowerCase())) continue;
+      const path = join(dir, file);
+      try {
+        const stat = statSync(path);
+        if (stat.isFile() && stat.mtimeMs > latestMtime) {
+          latestPath = path;
+          latestMtime = stat.mtimeMs;
+        }
+      } catch (error) {
+        if (!isExpectedFileSystemError(error)) throw error;
+      }
+    }
+  }
+
+  return latestPath;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("screenshot", {
+    description: "Insert the latest Windows/WSL system screenshot path into the editor",
+    handler: async (_args, ctx: ExtensionContext) => {
+      if (!supportsScreenshots()) {
+        ctx.ui.notify("Current environment is not Windows or WSL; cannot locate Windows screenshots.", "warning");
+        return;
+      }
+
+      const path = findLatestScreenshot();
+      if (!path) {
+        ctx.ui.notify("No Windows screenshots found.", "warning");
+        return;
+      }
+
+      ctx.ui.pasteToEditor(`${path} `);
+      ctx.ui.notify(`Referenced screenshot: ${path.split(/[\\/]/).pop()}`, "info");
+    },
+  });
+}

package/scripts/check-package.mjs

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+
+assert.equal(manifest.name, "@rol1n/pi-kit");
+assert.match(manifest.version, /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/, "Expected a release version in package.json");
+assert.equal(manifest.type, "module");
+assert.equal(manifest.license, "MIT");
+assert.ok(manifest.keywords.includes("pi-package"), "Missing pi-package discovery keyword");
+assert.ok(Array.isArray(manifest.files), "Expected a files allowlist");
+
+// Validate the hand-maintained manifest; never generate or rewrite it.
+const extensions = readdirSync(root, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, "index.ts")))
+  .map((entry) => entry.name)
+  .sort();
+assert.ok(extensions.length > 0, "No extension directories found");
+assert.deepEqual(
+  [...manifest.pi.extensions].sort(),
+  extensions.map((name) => `./${name}/index.ts`),
+  "pi.extensions must declare every top-level extension exactly once",
+);
+for (const name of extensions) {
+  assert.ok(existsSync(join(root, name, "README.md")), `Missing ${name}/README.md`);
+  assert.ok(manifest.files.includes(name), `files must include the complete ${name} directory`);
+}
+
+assert.deepEqual(manifest.pi.prompts, ["./prompts"], "pi.prompts must declare the independent root prompts directory");
+assert.ok(manifest.files.includes("prompts"), "files must include the root prompts directory");
+assert.ok(existsSync(join(root, "prompts")), "Missing root prompts directory");
+assert.deepEqual(manifest.pi.skills, ["./skills"], "pi.skills must declare the root skills directory");
+assert.ok(manifest.files.includes("skills"), "files must include the root skills directory");
+const skills = readdirSync(join(root, "skills"), { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && existsSync(join(root, "skills", entry.name, "SKILL.md")))
+  .map((entry) => entry.name);
+assert.ok(skills.length > 0, "Expected at least one skill directory containing SKILL.md");
+assert.deepEqual(manifest.pi.themes, []);
+for (const name of ["@earendil-works/pi-ai", "@earendil-works/pi-agent-core", "@earendil-works/pi-coding-agent", "@earendil-works/pi-tui", "typebox"]) {
+  assert.equal(manifest.peerDependencies[name], "*", `${name} must remain a host-provided peer`);
+  assert.ok(!manifest.dependencies?.[name], `Do not install a separate copy of ${name}`);
+}
+for (const exclusion of ["!**/test/**", "!**/tests/**", "!**/*.{test,spec}.{ts,js,mjs,cjs}", "!**/.env", "!**/.env.*"]) {
+  assert.ok(manifest.files.includes(exclusion), `Missing package exclusion: ${exclusion}`);
+}
+for (const path of ["LICENSE", "README.md", "README_zh.md", "scripts/check-package.mjs"]) {
+  assert.ok(existsSync(join(root, path)), `Missing ${path}`);
+}
+
+const promptCount = readdirSync(join(root, "prompts")).filter((name) => name.endsWith(".md")).length;
+console.log(`Checked ${manifest.name}@${manifest.version}: ${extensions.length} extensions, ${promptCount} prompts, ${skills.length} skill${skills.length === 1 ? "" : "s"}.`);

package/skills/worktree-studio/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: worktree-studio
+description: Orchestrate isolated Git-worktree experiments and compare independently implemented alternatives with real diffs and verification. Use for The Road Not Taken, competing implementation approaches, parallel worktree exploration, or accepting/rejecting agent-produced worktrees. Owns planning, confirmation, directory layout, worker delegation, evidence collection, and comparison; does not auto-integrate or discard results.
+---
+
+# Worktree Studio — The Road Not Taken
+
+Separate the workflow from the runtime. Git manages directories; this skill manages the experiment; a delegation tool runs each task in the specified `cwd`. `multi_harness` is one runtime, not a requirement for creating worktrees. Ordinary `subagent` or another available runtime may be used with equivalent explicit directory and lifecycle controls.
+
+## 1. Define and confirm the experiment
+
+- Use experiments only when evidence from genuinely viable alternatives will resolve uncertainty. Do not manufacture alternatives for a routine change.
+- Define the common goal, concrete acceptance criteria, each approach, and the number of alternatives. Do not hard-code two workers or require different harnesses.
+- Choose a reproducible baseline and name workers by purpose (for example `cache-codex`, `batch-pi`). Identify write overlap and dependencies.
+- Confirm the plan with the user **before creating worktrees or launching paid workers**. Explain expected workers/models, directories, resource costs, and retained artifacts. Timeouts are not spending limits; these workers may have full filesystem permissions.
+- Respect existing user approval without repeating questions already answered. Do not interpret approval to explore as approval to merge, commit, install dependencies, or delete results.
+
+## 2. Inspect the baseline without disturbing changes
+
+Use Git with argument-safe paths, for example:
+
+```sh
+git -C <source> rev-parse --show-toplevel
+git -C <source> rev-parse HEAD
+git -C <source> status --porcelain=v1 --untracked-files=normal
+git -C <source> worktree list --porcelain
+```
+
+Read relevant project instructions and code. Record the exact baseline SHA, source directory, and acceptance commands in a plan file outside worker directories.
+
+A dirty source cannot be reproduced from `HEAD`. Stop and explain the discrepancy. Ask the user to resolve the state, or explicitly approve comparing the committed baseline while leaving local changes untouched. Never automatically stash, stage, commit, reset, or copy ignored/secret files. Do not claim an experiment includes uncommitted context when it does not.
+
+## 3. Lay out isolated worktrees
+
+Choose a fresh experiment directory outside the source checkout and never reuse a nonempty path. Record a mapping of approach → worker name → harness/model → absolute worktree path.
+
+For each alternative:
+
+```sh
+git -C <source> worktree add --detach <absolute-new-path> <baseline-sha>
+```
+
+If creation partially fails, keep successful worktrees and report their paths. Do not force-remove them. Do not use Git locks or branches shared between workers.
+
+Ignored dependencies/build outputs are not copied by Git. Establish what can be verified without installing anything; ask before dependency installation or version changes. A worktree is not a security sandbox.
+
+## 4. Delegate one well-scoped task per directory
+
+Use any suitable runtime. With `multi_harness`, each worker is an equal CLI peer (`pi`, `codex`, `claude`, or `opencode`), not a mode:
+
+```json
+{"action":"spawn","name":"cache-codex","harness":"codex","cwd":"/absolute/experiment/cache","task":"Implement the cache approach. Baseline: <sha>. Acceptance: <criteria and commands>. Work only in this directory. Do not commit, merge, switch branches, delete worktrees, modify the source checkout, read secrets, or install dependencies without permission. Report changes, commands actually executed, results, blockers, and trade-offs."}
+```
+
+- Give every worker the **same goal and acceptance criteria**, with a different assigned approach where appropriate.
+- Include explicit paths, scope, no-go operations, expected artifacts, and verification commands in the task.
+- Native TUIs stay open after each turn. Completion arrives as a pushed notification. Do not wait in bash loops, repeatedly capture panes, or continually call `status`.
+- Treat `harness-done "summary"` as a summary submission; settlement hooks produce the authoritative turn-completion event. A worker's success claim is not independent verification.
+- To clarify, repair, or request more evidence, send a follow-up to the same idle worker:
+
+```json
+{"action":"send","target":"cache-codex","task":"Run the missing acceptance check in your existing directory. Report the exact command, result, and remaining limitations; do not integrate or commit."}
+```
+
+Use `status` for a user-requested snapshot or diagnosis, not as a waiting loop. If a timeout or trust/permission dialog blocks work, surface it; do not silently bypass additional security controls.
+
+## 5. Collect evidence and independently accept/reject
+
+After notifications arrive, inspect **every** worktree. Keep machine evidence separate from worker summaries:
+
+```sh
+git -C <worker-dir> rev-parse HEAD
+git -C <worker-dir> status --short --untracked-files=normal
+git -C <worker-dir> diff --no-ext-diff --stat <baseline-sha>
+git -C <worker-dir> diff --no-ext-diff --binary <baseline-sha>
+git -C <worker-dir> ls-files --others --exclude-standard -z
+git -C <worker-dir> log --oneline <baseline-sha>..HEAD
+```
+
+- Save tracked diffs and inspect untracked deliverables separately: ordinary `git diff` omits new untracked files. Never stage files merely to make a diff appear complete.
+- Detect unexpected commits, branch changes, deleted files, dependency edits, out-of-scope changes, and modifications to the original checkout.
+- Run comparable acceptance checks yourself when safe. Record command, directory, exit/result, and environment limitations. Do not mark an unrun or permission-blocked check as passed.
+- Review correctness, maintainability, scope, performance evidence, compatibility, operational risks, and costs when reported. Do not fabricate absent pricing or infer free usage from zero/missing cost.
+- For UI outputs, inspect desktop/mobile rendering if browser access is available; otherwise state that visual validation was not performed.
+
+## 6. Report, recommend, and preserve
+
+Write a comparison report in the experiment directory:
+
+1. Goal, baseline SHA, source path, acceptance criteria.
+2. Route/worker/harness/model/directory mapping.
+3. Per-route implementation summary, tracked diff, untracked artifacts, unexpected commits, independent test results, and limitations.
+4. Comparison table: accepted criteria, failures, trade-offs, evidence gaps, resource/cost observations.
+5. Recommendation with reasons, or an explicit statement that evidence is insufficient.
+6. Paths to preserved worktrees, runtime sessions/logs, and pending decisions.
+
+Ask before integrating any result. Do not automatically choose a winner, merge, cherry-pick, commit, or delete worktrees.
+
+When the user wants runtime cleanup, `multi_harness({"action":"close","target":"cache-codex"})` closes an idle TUI without deleting working files. For active work, use `stop` first. Explain that stopping a worker is not the same as removing its Git worktree. Any later removal needs separate explicit approval after artifact review.

package/srp-theme/README.md

@@ -5,10 +5,10 @@ Incremental Pi terminal presentation enhancement: adds a `belowEditor` last-prom
 ## Install
 
 ```sh
-pi install npm:@rol1n/srp-theme
+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
 

package/subagent/README.md

@@ -5,10 +5,10 @@ Delegate tasks to independent, full-powered Pi workers. The `subagent` tool retu
 ## Install
 
 ```sh
-pi install npm:@rol1n/subagent
+pi install npm:@rol1n/pi-kit
 ```
 
-Also included in `@rol1n/pi-kit`. The parent and workers require the `pi` executable on PATH and their normal Pi authentication.
+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 parent and workers require the `pi` executable on PATH and their normal Pi authentication.
 
 ## Use
 
@@ -30,6 +30,6 @@ Also included in `@rol1n/pi-kit`. The parent and workers require the `pi` execut
 
 Without a usable multiplexer, the worker backend falls back to a background process. Native Windows supports PowerShell launch commands and Zellij panes; tmux is for POSIX environments. Session transcripts and task artifacts are stored under `~/.pi/agent/`.
 
-## Other delegation packages
+## Other delegation tools
 
-Use [multi-harness](https://github.com/RolinShmily/pi-kit/tree/main/multi-harness) for Codex, Claude, or OpenCode peers. That package shares multiplexer helpers (`mux.ts`) while exposing a separate tool.
+Use [multi-harness](https://github.com/RolinShmily/pi-kit/tree/main/multi-harness) for Codex, Claude, or OpenCode peers. It shares multiplexer helpers (`mux.ts`) within the same kit while exposing a separate tool.

package/tui-asr/README.md

@@ -5,10 +5,12 @@ Streaming voice dictation for Pi's terminal editor using Aliyun DashScope Parafo
 ## Install
 
 ```sh
-pi install npm:@rol1n/tui-asr
+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.
 
 ## Commands and shortcuts
 

package/web-reach/README.md

@@ -5,10 +5,10 @@ Keyless web search (`web_search` via Exa MCP) and multi-tier page extraction (`w
 ## Install
 
 ```sh
-pi install npm:@rol1n/web-reach
+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.
 
 ## Configuration
 

package/windows-wheel-fix/README.md

@@ -6,7 +6,7 @@ Restores mouse-wheel reporting for Pi under Windows ConPTY / Zellij ([earendil-w
 ## Install
 
 ```sh
-pi install npm:@rol1n/windows-wheel-fix
+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.