@saifymatteo/pi-extensions 0.1.1 → 0.1.3

package/packages/pi-session-finder/README.md

@@ -1,5 +1,9 @@
 # pi-session-finder
 
+![/session-global listing sessions from every project, with forks nested](screenshot.png)
+
+*`/session-global` searches saved sessions across all projects. They are grouped by folder, with forks nested under their parent.*
+
 Search saved sessions across projects, display their fork families, and open or fork a conversation into the current project.
 
 ## Running locally

package/packages/pi-session-finder/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-session-finder",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-finder/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-session-id/README.md

@@ -1,5 +1,9 @@
 # pi-session-id
 
+![/session-id confirming the copied session ID](screenshot.png)
+
+*`/session-id` copies the current session ID to the clipboard.*
+
 Copy the current session ID to the system clipboard.
 
 ## Running locally

package/packages/pi-session-id/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-session-id",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-id/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-session-nav/README.md

@@ -1,5 +1,9 @@
 # pi-session-nav
 
+![Alt+O message navigator over the current conversation](screenshot.png)
+
+*Alt+O lists the conversation's messages. Pick one and press Enter to jump to it.*
+
 Navigate visible user and assistant messages on the active conversation branch without adding transcript entries.
 
 ## Running locally

package/packages/pi-session-nav/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-session-nav",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-nav/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-session-rename/README.md

@@ -1,5 +1,9 @@
 # pi-session-rename
 
+![Generated session title in the footer and terminal title](screenshot.png)
+
+*After the first prompt, the session gets a generated title. It appears in the footer and in the terminal tab title.*
+
 Automatically title main interactive sessions from the first submitted prompt and optionally mirror the name to a Herdr tab. Manual names take precedence; failed generation retries on later prompts.
 
 ## Running locally

package/packages/pi-session-rename/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-session-rename",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-rename/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-session-retention/README.md

@@ -1,5 +1,9 @@
 # pi-session-retention
 
+![/session-cleanup preview listing inactive session families](screenshot.png)
+
+*`/session-cleanup preview` shows which inactive session families would move to Trash. It changes nothing.*
+
 From the monorepo root:
 
 ```sh

package/packages/pi-session-retention/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-session-retention",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-session-retention/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-skill-usage-log/README.md

@@ -1,5 +1,9 @@
 # pi-skill-usage-log
 
+![/skill-usage report of loaded and used skills across projects](screenshot.png)
+
+*`/skill-usage` shows which installed skills were loaded and which were actually used, across all projects.*
+
 Passively record skill loads and subsequent tool activity, then show cross-project usage without adding the report to conversation context.
 
 ## Running locally

package/packages/pi-skill-usage-log/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-skill-usage-log",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-skill-usage-log/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-tool-usage-log/README.md

@@ -1,5 +1,9 @@
 # pi-tool-usage-log
 
+![/tool-usage report of calls, errors, nesting and duration per tool](screenshot.png)
+
+*`/tool-usage` totals every tool call: count, sessions, errors, nested calls, average duration and last use.*
+
 Passively record direct and nested tool executions and show aggregate usage, errors, duration, selected model and thinking level.
 
 ## Running locally

package/packages/pi-tool-usage-log/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-tool-usage-log",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -13,6 +14,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-tool-usage-log/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-tts/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-tts
 
+![The text_to_speech tool saving a WAV file into the project](screenshot.png)
+
+*The agent calls `text_to_speech`, and the WAV file from the configured speech endpoint is saved into the project.*
+
 ## Purpose and registrations
 
 Registers `text_to_speech` when the registry has a `type: "tts"` model; no slash commands or playback. Sends narration to a service and saves a new WAV, never overwriting an existing output. Uses standard fetch/streams and Pi tool registration; requires filesystem hard-link support for atomic publication.

package/packages/pi-tts/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@saifymatteo/pi-tts",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-tts/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-user-image-previews/README.md

@@ -1,5 +1,9 @@
 # Inline user image previews
 
+![Attached image shown as a collapsible preview row, expanded inline with Ctrl+O](screenshot.png)
+
+*An attached image gets a collapsible preview row in the transcript. Ctrl+O opens it inline. Stock pi shows nothing.*
+
 Adds collapsible UI-only previews for newly submitted image attachments.
 
 ## Try locally

package/packages/pi-user-image-previews/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@saifymatteo/pi-user-image-previews",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Adds collapsible UI-only previews for newly submitted image attachments.",
   "type": "module",
   "license": "AGPL-3.0-only",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension"
   ],
   "files": [
     "src",
@@ -14,6 +15,7 @@
     "LICENSE"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-user-image-previews/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ]

package/packages/pi-vision/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-vision
 
+![A text-only model answering about an image via a vision model description](screenshot.png)
+
+*The main model here is text-only. Stock pi drops the image. With pi-vision, a configured vision model describes the image and the main model works from that description.*
+
 ## Purpose and registrations
 
 Registers a `context` hook, not a tool or slash command. Preserves native images for image-capable session models by default. For text-only/unknown models it replaces image blocks with model-generated descriptions. Optional `describe` / `describe-old` policies self-describe all/older images using the current model on OpenAI Chat Completions connections.
@@ -12,7 +16,7 @@ Resolution also consults agent `models.json`, `models-store.json`, `auth.json`,
 
 ## Bundled skill
 
-The package bundles the `vision-tools` skill (`skills/vision-tools`): `bin/` launcher CLIs (`crop`, `detect`, `glance`, `ground`, `trace`, `vision-doctor`), Python tools under `scripts/`, reference guides, and `SKILL.md`. The extension's guidance messages point the agent at `vision-doctor` and the skill. Requires Python 3 with Pillow (PIL); the CLIs are Python scripts, not compiled binaries. Based on [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) (MIT), modified in this repository — see [NOTICE.md](NOTICE.md).
+The package bundles the `vision-tools` skill (`skills/vision-tools`): `bin/` launcher CLIs (`crop`, `detect`, `glance`, `ground`, `trace`, `vision-doctor`), Python tools under `scripts/`, reference guides, and `SKILL.md`. Invoke the launchers with Python and their absolute skill-relative paths, for example `python3 "<skill-directory>/bin/crop" image.png --region 0,0,100,100 -o detail.png`. Follow the interpreter-selection guidance in `SKILL.md` if Windows exposes Python as `python` or `py -3`. No PATH registration, executable bit, or agent-home shim is required. The extension does not modify PATH. Automated long-screenshot OCR prefers the bundled `bin/glance` with the current Python interpreter, falling back to PATH only if that script is missing. The extension's guidance messages point the agent at `vision-doctor` and the skill. Requires Python 3 with Pillow (PIL); the CLIs are Python scripts, not compiled binaries. Based on [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) (MIT), modified in this repository — see [NOTICE.md](NOTICE.md).
 
 ## Host limitations and security
 

package/packages/pi-vision/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@saifymatteo/pi-vision",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
-    "pi-package"
+    "pi-package",
+    "pi-extension",
+    "pi-skill"
   ],
   "files": [
     "src",
@@ -15,6 +17,7 @@
     "skills"
   ],
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/packages/pi-vision/screenshot.png",
     "extensions": [
       "./src/index.ts"
     ],

package/packages/pi-vision/skills/vision-tools/SKILL.md

@@ -33,20 +33,35 @@ For browser or accessible GUI work, prefer DOM/accessibility information for
 controls and state. Use screenshot coordinates when that information is
 unavailable or the task specifically concerns appearance.
 
+## Run the packaged scripts
+
+1. Resolve `<skill-dir>` to the absolute directory containing this `SKILL.md`,
+   using the skill location supplied by the host. Replace that placeholder in
+   commands below; keep script paths quoted and keep the project's working
+   directory.
+2. Select a Python 3 interpreter: try `python3 --version`; on Windows, use
+   `python --version` or `py -3 --version` if needed. Substitute that command
+   for `python3` in the examples.
+3. Invoke `bin/<tool>` and `scripts/<name>.py` through that interpreter. The
+   extensionless files in `bin/` are Python scripts, not installed binaries.
+   This works without PATH registration, executable permissions, or agent-home
+   symlinks. Short tool names in prose refer to these same script paths.
+
+Use `--help` on the selected script for additional options.
+
 ## Local tools: use when their output is needed
 
-Resolve `scripts/` paths relative to this skill directory. Use `--help` for
-additional options. These tools do not use the vision API; HTML rendering can
-load resources referenced by the page.
+These tools do not use the vision API; HTML rendering can load resources
+referenced by the page.
 
 | Need | Command |
 | --- | --- |
-| Reusable crop or close-up | `crop shot.png --region X1,Y1,X2,Y2 -o detail.png` |
-| Locate pixel differences | `python3 scripts/pixel_diff.py before.png after.png` |
-| Measure a region's palette | `python3 scripts/dominant_colors.py shot.png --region X1,Y1,X2,Y2` |
-| Vectorize a flat graphic | `trace icon.png -o icon.svg` |
-| Extract a transparent foreground | `python3 scripts/extract_fg.py shot.png --region X1,Y1,X2,Y2 -o icon.png` |
-| Render an HTML file | `python3 scripts/html_shot.py page.html --width 1440 --height 900 -o page.png` |
+| Reusable crop or close-up | `python3 "<skill-dir>/bin/crop" shot.png --region X1,Y1,X2,Y2 -o detail.png` |
+| Locate pixel differences | `python3 "<skill-dir>/scripts/pixel_diff.py" before.png after.png` |
+| Measure a region's palette | `python3 "<skill-dir>/scripts/dominant_colors.py" shot.png --region X1,Y1,X2,Y2` |
+| Vectorize a flat graphic | `python3 "<skill-dir>/bin/trace" icon.png -o icon.svg` |
+| Extract a transparent foreground | `python3 "<skill-dir>/scripts/extract_fg.py" shot.png --region X1,Y1,X2,Y2 -o icon.png` |
+| Render an HTML file | `python3 "<skill-dir>/scripts/html_shot.py" page.html --width 1440 --height 900 -o page.png` |
 
 - `crop --scale 4` enlarges a crop; it adds no missing detail. Coordinates
   measured on that output use the enlarged grid, not the original image.
@@ -84,11 +99,11 @@ separately configured vision chain, not to the main agent model automatically.
 Structured output does not guarantee better recognition or localization.
 
 ```bash
-glance shot.png -q "Read the small status label."
-glance shot.png --region X1,Y1,X2,Y2 --ocr
-glance before.png after.png -q "What changed semantically?"
-ground shot.png "the send button"
-detect shot.png "buttons"
+python3 "<skill-dir>/bin/glance" shot.png -q "Read the small status label."
+python3 "<skill-dir>/bin/glance" shot.png --region X1,Y1,X2,Y2 --ocr
+python3 "<skill-dir>/bin/glance" before.png after.png -q "What changed semantically?"
+python3 "<skill-dir>/bin/ground" shot.png "the send button"
+python3 "<skill-dir>/bin/detect" shot.png "buttons"
 ```
 
 `ground` and `detect` return estimated boxes in original-image pixels, including
@@ -98,9 +113,9 @@ For multi-image questions, pass the images in one call so the model sees them
 together. Native side-by-side inspection is also sufficient for semantic
 comparison; use pixel diff when numerical differences matter.
 
-The long-screenshot OCR script still uses `glance` for automated transcription.
-Its `--split-only` mode makes chunks without API requests for native inspection.
-Keep the `glance` client/config available if using the automated path.
+The long-screenshot OCR script invokes this skill's `bin/glance` with its
+current Python interpreter, falling back to PATH only if the bundled script
+is missing. Its `--split-only` mode makes chunks without API requests.
 
 ### Configuration and failures
 
@@ -112,10 +127,11 @@ conversion on supported connections. Text-only or unknown-capability models
 still use the configured compatibility bridge. This policy does not route CLI
 calls through the main model.
 
-On a model-backed CLI configuration/API error, run `vision-doctor`. Use
-`vision-doctor --smoke` only when a real diagnostic request is needed; it sends
-a test image. Relay failures honestly. Continue with native inspection when
-available; report if the scripted output cannot be produced. Keep provider
+On a model-backed CLI configuration/API error, run
+`python3 "<skill-dir>/bin/vision-doctor"`. Add `--smoke` only when a real
+diagnostic request is needed; it sends a test image. Relay failures honestly.
+Continue with native inspection when available; report if the scripted output
+cannot be produced. Keep provider
 changes user-controlled: do not scrape credentials, hand-export secret overrides,
 or silently switch to an unconfigured provider.
 

package/packages/pi-vision/skills/vision-tools/references/long-screenshot-ocr.md

@@ -12,7 +12,7 @@ beyond a temporary file's lifetime. Inspect the script's help before choosing
 options:
 
 ```bash
-python3 scripts/long_screenshot_ocr.py --help
+python3 "<skill-dir>/scripts/long_screenshot_ocr.py" --help
 ```
 
 Prefer native chunk reading by the main agent; the glance-backed script is
@@ -22,7 +22,7 @@ splitter; verify joins even when the cut falls in a low-content band.
 ### Native chunk reading
 
 ```bash
-python3 scripts/long_screenshot_ocr.py work/page.png --split-only
+python3 "<skill-dir>/scripts/long_screenshot_ocr.py" work/page.png --split-only
 ```
 
 This writes ordered chunk images and `manifest.json` without vision calls.
@@ -38,10 +38,10 @@ Choose the content mode; this path makes configured vision calls:
 
 ```bash
 # Web pages, documents, logs, tables, and other general content
-python3 scripts/long_screenshot_ocr.py work/page.png -o work/page.ocr.md
+python3 "<skill-dir>/scripts/long_screenshot_ocr.py" work/page.png -o work/page.ocr.md
 
 # Chat histories: preserve message grouping, senders, timestamps, and quotes
-python3 scripts/long_screenshot_ocr.py work/chat.png --mode chat -o work/chat.ocr.md
+python3 "<skill-dir>/scripts/long_screenshot_ocr.py" work/chat.png --mode chat -o work/chat.ocr.md
 ```
 
 Without `-o`, write `<input-stem>.ocr.md`; store chunks, sidecars, the manifest,
@@ -63,7 +63,7 @@ Use `--resume` after an interrupted run. A chunk is reused only when its image,
 mode, and custom prompt fingerprint still match:
 
 ```bash
-python3 scripts/long_screenshot_ocr.py work/chat.png --mode chat --resume -o work/chat.ocr.md
+python3 "<skill-dir>/scripts/long_screenshot_ocr.py" work/chat.png --mode chat --resume -o work/chat.ocr.md
 ```
 
 If the defaults produce awkward chunks, rerun with `--target-height`,
@@ -85,8 +85,8 @@ context; do not make tiny OCR tiles unless the source text is unusually small.
    unresolved, targeted specialist OCR is available:
 
    ```bash
-   glance work/page_chunks/chunk_002.png --ocr "Re-check the final five lines carefully."
-   glance work/page_chunks/chunk_002.png --region X1,Y1,X2,Y2 --ocr
+   python3 "<skill-dir>/bin/glance" work/page_chunks/chunk_002.png --ocr "Re-check the final five lines carefully."
+   python3 "<skill-dir>/bin/glance" work/page_chunks/chunk_002.png --region X1,Y1,X2,Y2 --ocr
    ```
 
 5. Keep visible spelling and punctuation verbatim. Write `[unreadable]` for

package/packages/pi-vision/skills/vision-tools/references/restore-graphic.md

@@ -25,16 +25,16 @@ pixels as foreground.
 
 ```bash
 # Known tight region
-python3 scripts/extract_fg.py shot.png \
+python3 "<skill-dir>/scripts/extract_fg.py" shot.png \
   --region X1,Y1,X2,Y2 -o asset.png
 
 # Dark or gray line art
-python3 scripts/extract_fg.py shot.png \
+python3 "<skill-dir>/scripts/extract_fg.py" shot.png \
   --region X1,Y1,X2,Y2 --mode dark -o asset.png
 
 # Center and enlarge a small visual before automatic extraction
-crop shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/asset4x.png
-python3 scripts/extract_fg.py work/asset4x.png
+python3 "<skill-dir>/bin/crop" shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/asset4x.png
+python3 "<skill-dir>/scripts/extract_fg.py" work/asset4x.png
 ```
 
 Use `--exclude-color '#RRGGBB'` when a connected background color would
@@ -47,9 +47,9 @@ clean alpha edges, and no neighboring fragments before reuse.
 ## Rebuild an SVG only when the deliverable needs one
 
 ```bash
-trace asset.png -o asset.svg
-trace asset.png --polygon -o asset.svg
-trace shot.png --region X1,Y1,X2,Y2 -o asset.svg
+python3 "<skill-dir>/bin/trace" asset.png -o asset.svg
+python3 "<skill-dir>/bin/trace" asset.png --polygon -o asset.svg
+python3 "<skill-dir>/bin/trace" shot.png --region X1,Y1,X2,Y2 -o asset.svg
 ```
 
 Ship traced paths directly for organic or irregular shapes. For rectangles,

package/packages/pi-vision/skills/vision-tools/references/restore-ui.md

@@ -140,13 +140,13 @@ extraction, tighten the final region to the visual's own ink; adjacent text or
 rules inside the region can become foreground components too.
 
 ```bash
-crop shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/icon4x.png
-python3 scripts/extract_fg.py work/icon4x.png
+python3 "<skill-dir>/bin/crop" shot.png --region X1,Y1,X2,Y2 --scale 4 -o work/icon4x.png
+python3 "<skill-dir>/scripts/extract_fg.py" work/icon4x.png
 
 # Or extract directly from a known tight region:
-python3 scripts/extract_fg.py shot.png \
+python3 "<skill-dir>/scripts/extract_fg.py" shot.png \
   --region X1,Y1,X2,Y2 -o work/icon.png
-python3 scripts/extract_fg.py shot.png \
+python3 "<skill-dir>/scripts/extract_fg.py" shot.png \
   --region X1,Y1,X2,Y2 --mode dark -o work/logo.png
 ```
 

package/packages/pi-vision/skills/vision-tools/scripts/long_screenshot_ocr.py

@@ -456,13 +456,13 @@ def command_for_path(path: Path) -> list[str]:
 
 
 def resolve_glance_command() -> list[str]:
+    bundled_glance = Path(__file__).resolve().parents[1] / "bin" / "glance"
+    if bundled_glance.is_file():
+        return [sys.executable, str(bundled_glance)]
     discovered = shutil.which("glance")
     if discovered:
         return command_for_path(Path(discovered))
-    repository_glance = Path(__file__).resolve().parents[3] / "bin" / "glance"
-    if repository_glance.is_file():
-        return command_for_path(repository_glance)
-    raise FileNotFoundError("glance is not on PATH; install the toolkit first")
+    raise FileNotFoundError("glance is not in this skill directory or on PATH")
 
 
 def ocr_prompt(mode: str, index: int, total: int, custom: str | None) -> str:

package/packages/pi-vision/test/skill-cli.test.mjs

@@ -0,0 +1,71 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const skill = fileURLToPath(new URL('../skills/vision-tools/', import.meta.url));
+
+test('skill command examples invoke bundled Python scripts independently of PATH and cwd', () => {
+  const docs = [join(skill, 'SKILL.md'), ...readdirSync(join(skill, 'references')).map(name => join(skill, 'references', name))];
+  const launchers = new Set();
+  for (const doc of docs) {
+    const source = readFileSync(doc, 'utf8');
+    for (const [, commands] of source.matchAll(/```bash\n([\s\S]*?)```/g)) {
+      assert.equal(/^\s*(?:crop|detect|glance|ground|trace|vision-doctor)\s+\S/m.test(commands), false, `${doc}: bare launcher command`);
+    }
+    assert.equal(/python3 scripts\//.test(source), false, `${doc}: cwd-relative script path`);
+    for (const [, relative] of source.matchAll(/python3 "<skill-dir>\/([^"]+)"/g)) {
+      assert.ok(existsSync(join(skill, relative)), `${doc}: missing bundled script ${relative}`);
+      if (relative.startsWith('bin/')) launchers.add(relative.slice(4));
+    }
+  }
+  assert.deepEqual([...launchers].sort(), ['crop', 'detect', 'glance', 'ground', 'trace', 'vision-doctor'].sort());
+});
+
+test('automated OCR finds bundled glance without PATH, including non-executable paths with spaces', t => {
+  const python = [['python3'], ['python'], ['py', '-3']].find(([command, ...args]) => {
+    const result = spawnSync(command, [...args, '--version'], { encoding: 'utf8', timeout: 10_000 });
+    return result.status === 0 && /^Python 3\./.test(result.stdout);
+  });
+  if (!python) return t.skip('Python 3 is not installed');
+  const code = `
+import importlib.util
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+from unittest.mock import patch
+
+source = Path(sys.argv[1])
+spec = importlib.util.spec_from_file_location("long_screenshot_ocr", source)
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+spec.loader.exec_module(module)
+with tempfile.TemporaryDirectory(prefix="vision skill ") as directory:
+    skill = Path(directory)
+    script = skill / "scripts" / "long_screenshot_ocr.py"
+    script.parent.mkdir()
+    script.touch()
+    glance = skill / "bin" / "glance"
+    glance.parent.mkdir()
+    glance.write_text('print("bundled glance reached")', encoding="utf-8")
+    with patch.object(module, "__file__", str(script)), patch.object(module.shutil, "which", return_value=None):
+        command = module.resolve_glance_command()
+    assert command == [sys.executable, str(glance)], command
+    result = subprocess.run(command, capture_output=True, text=True, check=True)
+    assert result.stdout.strip() == "bundled glance reached", result.stdout
+    with patch.object(module, "__file__", str(script)), patch.object(module.shutil, "which", return_value="/unrelated/glance"):
+        assert module.resolve_glance_command() == command, "prefer the packaged script over unrelated PATH commands"
+    glance.unlink()
+    external = skill / "custom_glance.py"
+    external.touch()
+    with patch.object(module, "__file__", str(script)), patch.object(module.shutil, "which", return_value=str(external)):
+        assert module.resolve_glance_command() == [sys.executable, str(external)], "retain the external fallback"
+`;
+  const result = spawnSync(python[0], [...python.slice(1), '-c', code, join(skill, 'scripts', 'long_screenshot_ocr.py')], {
+    encoding: 'utf8', timeout: 20_000, env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' },
+  });
+  assert.equal(result.status, 0, result.stderr || result.error?.message);
+});

package/packages/pi-wait/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-wait
 
+![wait joining a background shell job and returning its output](screenshot.png)
+
+*The agent starts a build in the background, then calls `wait` on `shell:1`. The job's output comes back in the same turn. Needs pi-bg-bash.*
+
 ## Purpose and registrations
 
 Registers the `wait` tool, joining 1..64 unique explicit `shell:<id>` / `agent:<id>` jobs. Returns results in requested order. Timeout releases claims without stopping work; abort/session changes invalidate the join. No commands or configuration files; no external CLI/model service.