@saifymatteo/pi-extensions 0.1.1 → 0.1.2

package/README.md

@@ -2,8 +2,12 @@
 
 Reusable pieces of a personal Pi setup, packaged separately from the setup itself.
 
+![Demo: every extension in this collection loaded into one Pi session](demo.gif)
+
 **Work in progress.** Packages are licensed AGPL-3.0-only ([NOTICE.md](NOTICE.md)) and publish through GitHub Actions when tagged: each extension individually, plus the root as the all-in-one collection [`@saifymatteo/pi-extensions`](https://github.com/saifymatteo/pi-extensions). Git is local for now, with no GitHub repository yet.
 
+Each package README opens with a screenshot of what it adds. The screenshots are real captures, not mockups: stock Pi 1.4.0 driven by a scripted demo model, in an isolated agent home. The catalogue below shows them as thumbnails; click one for the package README.
+
 ## Start here
 
 Use Node.js 24 or newer. From this repository:
@@ -27,6 +31,8 @@ Host-provided Pi packages (`@earendil-works/*`) are declared only as package pee
 - `pack:check`: asks npm to show each standalone package's and the root collection's prospective contents without publishing or creating archives.
 - `smoke`: loads each package through isolated host help/startup. Checks module/factory loading, not session events, interactive rendering, models, external CLIs, or backend compatibility. The host is located automatically (`PI_HOST`, `pi` on PATH, then `pi-bolt` for a Pi-Bolt build, then the local `~/.pi-bolt` install). Pi-Bolt is optional; set `PI_HOST` to another executable to compare hosts. A pass here does not prove compatibility with a different host build.
 - `context`: measures what each package adds to the first-turn context window. Current result: the whole collection costs about **1.7k tokens** on top of stock Pi, and 17 of 22 packages contribute nothing (they register hooks, commands, or UI patches only). Measured by capturing the actual request Pi sends to a local provider, against the pinned stock host, with machine state excluded. First-turn static cost only: runtime injections (tool results, hook-driven messages) are not measured. Not part of the `check` gate.
+- `screenshots`: regenerates each `packages/<name>/screenshot.png` (`npm run screenshots -- pi-bg-bash` for one). Drives the pinned stock host in a pseudo-terminal against a scripted local model and fake service endpoints, in a throwaway `/tmp/demo` home, with a stubbed clipboard. macOS only for now (font path, clipboard stub). Needs `agent-browser` on PATH. One-time setup: `npm ci --prefix scripts/screenshots`, then make node-pty's helper executable (`chmod +x scripts/screenshots/node_modules/node-pty/prebuilds/*/spawn-helper`) if npm skipped its install script. Not part of the `check` gate.
+- `demo`: re-records the root `demo.gif` (also the gallery preview via `pi.image`): one session with the whole root collection loaded, same harness and setup as `screenshots`. `DRY=1` prints each scene's screen without rendering. Not part of the `check` gate.
 
 ## Isolated sessions
 
@@ -50,46 +56,46 @@ Each directory under `packages/` is an independently loadable, independently pub
 
 ### Session and model navigation
 
-| Package | Purpose |
-| --- | --- |
-| [pi-session-id](packages/pi-session-id) | Copy the current session ID |
-| [pi-session-finder](packages/pi-session-finder) | Search saved sessions across projects; open or fork them |
-| [pi-session-nav](packages/pi-session-nav) | Jump between messages in the active context (compaction-aware) |
-| [pi-session-rename](packages/pi-session-rename) | Generate session titles from the first prompt using configured models |
-| [pi-session-retention](packages/pi-session-retention) | Inspect and manage stored sessions; review deletion behavior before use |
-| [pi-model-go](packages/pi-model-go) | `/model-go`: cost-aware model picker with Go-plan pricing and intelligence scores |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-session-id](packages/pi-session-id) | Copy the current session ID | <a href="packages/pi-session-id"><img src="packages/pi-session-id/screenshot.png" width="280" alt="pi-session-id screenshot"></a> |
+| [pi-session-finder](packages/pi-session-finder) | Search saved sessions across projects; open or fork them | <a href="packages/pi-session-finder"><img src="packages/pi-session-finder/screenshot.png" width="280" alt="pi-session-finder screenshot"></a> |
+| [pi-session-nav](packages/pi-session-nav) | Jump between messages in the active context (compaction-aware) | <a href="packages/pi-session-nav"><img src="packages/pi-session-nav/screenshot.png" width="280" alt="pi-session-nav screenshot"></a> |
+| [pi-session-rename](packages/pi-session-rename) | Generate session titles from the first prompt using configured models | <a href="packages/pi-session-rename"><img src="packages/pi-session-rename/screenshot.png" width="280" alt="pi-session-rename screenshot"></a> |
+| [pi-session-retention](packages/pi-session-retention) | Inspect and manage stored sessions; review deletion behavior before use | <a href="packages/pi-session-retention"><img src="packages/pi-session-retention/screenshot.png" width="280" alt="pi-session-retention screenshot"></a> |
+| [pi-model-go](packages/pi-model-go) | `/model-go`: cost-aware model picker with Go-plan pricing and intelligence scores | <a href="packages/pi-model-go"><img src="packages/pi-model-go/screenshot.png" width="280" alt="pi-model-go screenshot"></a> |
 
 ### Transcript and terminal UI
 
-| Package | Purpose |
-| --- | --- |
-| [pi-compact-tools](packages/pi-compact-tools) | Group consecutive tool calls into one collapsible card |
-| [pi-clipboard-image](packages/pi-clipboard-image) | Attach clipboard images or copied image files (Alt+V) |
-| [pi-codeblock-borders](packages/pi-codeblock-borders) | Render code fences as rules with titles, line numbers, and highlights |
-| [pi-user-image-previews](packages/pi-user-image-previews) | Collapsible inline previews for newly submitted attachments |
-| [pi-claude-usage](packages/pi-claude-usage) | Show Claude 5h/7d subscription usage in the footer |
-| [pi-prestart-working](packages/pi-prestart-working) | Labelled "Working" spinner while `before_agent_start` hooks run |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-compact-tools](packages/pi-compact-tools) | Group consecutive tool calls into one collapsible card | <a href="packages/pi-compact-tools"><img src="packages/pi-compact-tools/screenshot.png" width="280" alt="pi-compact-tools screenshot"></a> |
+| [pi-clipboard-image](packages/pi-clipboard-image) | Attach clipboard images or copied image files (Alt+V) | <a href="packages/pi-clipboard-image"><img src="packages/pi-clipboard-image/screenshot.png" width="280" alt="pi-clipboard-image screenshot"></a> |
+| [pi-codeblock-borders](packages/pi-codeblock-borders) | Render code fences as rules with titles, line numbers, and highlights | <a href="packages/pi-codeblock-borders"><img src="packages/pi-codeblock-borders/screenshot.png" width="280" alt="pi-codeblock-borders screenshot"></a> |
+| [pi-user-image-previews](packages/pi-user-image-previews) | Collapsible inline previews for newly submitted attachments | <a href="packages/pi-user-image-previews"><img src="packages/pi-user-image-previews/screenshot.png" width="280" alt="pi-user-image-previews screenshot"></a> |
+| [pi-claude-usage](packages/pi-claude-usage) | Show Claude 5h/7d subscription usage in the footer | <a href="packages/pi-claude-usage"><img src="packages/pi-claude-usage/screenshot.png" width="280" alt="pi-claude-usage screenshot"></a> |
+| [pi-prestart-working](packages/pi-prestart-working) | Labelled "Working" spinner while `before_agent_start` hooks run | <a href="packages/pi-prestart-working"><img src="packages/pi-prestart-working/screenshot.png" width="280" alt="pi-prestart-working screenshot"></a> |
 
 ### Tools and service adapters
 
-| Package | Purpose |
-| --- | --- |
-| [pi-bg-bash](packages/pi-bg-bash) | Add background execution to the built-in bash/powershell tools |
-| [pi-wait](packages/pi-wait) | Join background jobs (shell:/agent:) with lease-based delivery |
-| [pi-codegraph](packages/pi-codegraph) | CodeGraph CLI adapter: explore tool plus index auto-init/sync |
-| [pi-zvec](packages/pi-zvec) | Workspace search via the zg CLI: exact, lexical, semantic, hybrid |
-| [pi-decisions](packages/pi-decisions) | Agent-facing classify tool backed by configured Decisions endpoints |
-| [pi-tts](packages/pi-tts) | Generate WAV files through an OpenAI-compatible speech endpoint |
-| [pi-vision](packages/pi-vision) | Describe images for text-only models via a configured vision chain |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-bg-bash](packages/pi-bg-bash) | Add background execution to the built-in bash/powershell tools | <a href="packages/pi-bg-bash"><img src="packages/pi-bg-bash/screenshot.png" width="280" alt="pi-bg-bash screenshot"></a> |
+| [pi-wait](packages/pi-wait) | Join background jobs (shell:/agent:) with lease-based delivery | <a href="packages/pi-wait"><img src="packages/pi-wait/screenshot.png" width="280" alt="pi-wait screenshot"></a> |
+| [pi-codegraph](packages/pi-codegraph) | CodeGraph CLI adapter: explore tool plus index auto-init/sync | <a href="packages/pi-codegraph"><img src="packages/pi-codegraph/screenshot.png" width="280" alt="pi-codegraph screenshot"></a> |
+| [pi-zvec](packages/pi-zvec) | Workspace search via the zg CLI: exact, lexical, semantic, hybrid | <a href="packages/pi-zvec"><img src="packages/pi-zvec/screenshot.png" width="280" alt="pi-zvec screenshot"></a> |
+| [pi-decisions](packages/pi-decisions) | Agent-facing classify tool backed by configured Decisions endpoints | <a href="packages/pi-decisions"><img src="packages/pi-decisions/screenshot.png" width="280" alt="pi-decisions screenshot"></a> |
+| [pi-tts](packages/pi-tts) | Generate WAV files through an OpenAI-compatible speech endpoint | <a href="packages/pi-tts"><img src="packages/pi-tts/screenshot.png" width="280" alt="pi-tts screenshot"></a> |
+| [pi-vision](packages/pi-vision) | Describe images for text-only models via a configured vision chain | <a href="packages/pi-vision"><img src="packages/pi-vision/screenshot.png" width="280" alt="pi-vision screenshot"></a> |
 
 ### Environment and local observability
 
-| Package | Purpose |
-| --- | --- |
-| [pi-load-pi-dotenv](packages/pi-load-pi-dotenv) | Load the agent-local .env into the environment for tool subprocesses |
-| [pi-root-guard](packages/pi-root-guard) | Block agent writes into the Pi and Claude config roots |
-| [pi-skill-usage-log](packages/pi-skill-usage-log) | Log which skills were actually used; `/skill-usage` summary |
-| [pi-tool-usage-log](packages/pi-tool-usage-log) | Passive log of tool executions (names and status, never contents) |
+| Package | Purpose | Preview |
+| --- | --- | --- |
+| [pi-load-pi-dotenv](packages/pi-load-pi-dotenv) | Load the agent-local .env into the environment for tool subprocesses | <a href="packages/pi-load-pi-dotenv"><img src="packages/pi-load-pi-dotenv/screenshot.png" width="280" alt="pi-load-pi-dotenv screenshot"></a> |
+| [pi-root-guard](packages/pi-root-guard) | Block agent writes into the Pi and Claude config roots | <a href="packages/pi-root-guard"><img src="packages/pi-root-guard/screenshot.png" width="280" alt="pi-root-guard screenshot"></a> |
+| [pi-skill-usage-log](packages/pi-skill-usage-log) | Log which skills were actually used; `/skill-usage` summary | <a href="packages/pi-skill-usage-log"><img src="packages/pi-skill-usage-log/screenshot.png" width="280" alt="pi-skill-usage-log screenshot"></a> |
+| [pi-tool-usage-log](packages/pi-tool-usage-log) | Passive log of tool executions (names and status, never contents) | <a href="packages/pi-tool-usage-log"><img src="packages/pi-tool-usage-log/screenshot.png" width="280" alt="pi-tool-usage-log screenshot"></a> |
 
 ## Individual and collection loading
 
@@ -133,7 +139,7 @@ packages/<extension>/
   src/index.ts       # existing extension implementation
   src/lib/           # only helpers needed by this package, where applicable
   examples/          # sanitized, inert examples where applicable
-scripts/             # boundary checks, isolated sessions, host smoke
+scripts/             # boundary checks, isolated sessions, host smoke, screenshots
 test/                # test-only TS loader and collection behavior checks
 inventory.json       # inclusion/exclusion map
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-extensions",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Independently installable Pi extensions",
@@ -14,7 +14,9 @@
     "pack:check": "node scripts/check-pack.mjs",
     "dev": "node scripts/dev.mjs",
     "smoke": "node scripts/smoke.mjs",
-    "context": "node scripts/context-audit.mjs"
+    "context": "node scripts/context-audit.mjs",
+    "screenshots": "node scripts/screenshots/shots.mjs",
+    "demo": "node scripts/screenshots/demo.mjs"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.4.0",
@@ -27,6 +29,7 @@
     "node": ">=24"
   },
   "pi": {
+    "image": "https://raw.githubusercontent.com/saifymatteo/pi-extensions/main/demo.gif",
     "extensions": [
       "./packages/pi-load-pi-dotenv/src/index.ts",
       "./packages/pi-bg-bash/src/index.ts",
@@ -68,6 +71,7 @@
   ],
   "files": [
     "packages",
+    "!packages/*/screenshot.png",
     "inventory.json",
     "README.md",
     "NOTICE.md",

package/packages/pi-bg-bash/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-bg-bash
 
+![The agent runs npm test in the background, keeps working, and the result arrives as its own row](screenshot.png)
+
+*The agent starts `npm test` with `background: true` and keeps working. When the job exits, its result arrives as a separate row. Ctrl+O expands that row to the output tail.*
+
 ## Purpose and registrations
 
 Overrides `bash` and, when provided by the host, `powershell`, adding `background` and `job`. Registers `/bg`, result/call renderers, timeout injection, sleep-wait guard, session/settlement hooks, and shell provider discovery.

package/packages/pi-bg-bash/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-bg-bash",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/packages/pi-claude-usage/README.md

@@ -1,5 +1,9 @@
 # Claude subscription usage
 
+![Footer showing Claude 5-hour and 7-day usage with reset timers](screenshot.png)
+
+*An extra footer line shows Claude 5-hour and 7-day usage and when each window resets. Its colour changes at 75% and 90%.*
+
 Displays Claude subscription rate-limit windows from provider message diagnostics.
 
 ## Try locally
@@ -14,7 +18,7 @@ This uses your normal personal resources unless you isolate the agent home. Foll
 
 ## Configuration and requirements
 
-Uses rate-limit diagnostics from the external pi-claude-code provider; it does not poll Anthropic. Caches the most recent windows in <agent-dir>/state/claude-usage.json. No additional configuration.
+Uses rate-limit diagnostics from the external pi-claude-code provider; it does not poll Anthropic. Caches the most recent windows in <agent-dir>/state/claude-usage.json. The footer is shown only while the selected model uses the `claude-code` provider, not for Claude models accessed through other providers. Switching providers hides or restores it immediately. No additional configuration.
 
 ## Compatibility and safety
 

package/packages/pi-claude-usage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-claude-usage",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Displays Claude subscription rate-limit windows from provider message diagnostics.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/packages/pi-claude-usage/src/index.ts

@@ -77,7 +77,11 @@ export default function (pi: ExtensionAPI) {
 	let tick: ReturnType<typeof setInterval> | undefined;
 
 	function render() {
-		if (!ctx || !usage) return;
+		if (!ctx) return;
+		if (ctx.model?.provider !== "claude-code" || !usage) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
 		const now = Date.now();
 		const text = formatFooter(usage, now);
 		const p = peak(usage, now);
@@ -115,6 +119,11 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
+	pi.on("model_select", async (_event, sessionCtx) => {
+		ctx = sessionCtx;
+		render();
+	});
+
 	pi.on("session_shutdown", async () => {
 		if (tick) clearInterval(tick);
 		tick = undefined;

package/packages/pi-claude-usage/test/behavior.test.mjs

@@ -0,0 +1,71 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+const cached = { fiveHour: { pct: 42, resetsAt: 4_000_000_000_000 } };
+
+function harness(t, initialModel, cache = cached) {
+  const hooks = {}, statuses = new Map(), timers = new Set(), writes = [];
+  const extension = loadExtension(new URL('../src/index.ts', import.meta.url), {
+    'node:fs': {
+      readFileSync: () => {
+        if (!cache) throw new Error('no cache');
+        return JSON.stringify(cache);
+      },
+      mkdirSync: () => {},
+      writeFileSync: (_path, contents) => writes.push(JSON.parse(contents)),
+    },
+  }, {
+    setInterval: fn => { timers.add(fn); return fn; },
+    clearInterval: fn => timers.delete(fn),
+  });
+  extension.default({ on: (name, fn) => { hooks[name] = fn; } });
+  const ui = {
+    setStatus: (key, value) => { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+    theme: { fg: (_color, value) => value },
+  };
+  const context = model => ({ model, ui });
+  const ctx = context(initialModel);
+  t.after(() => hooks.session_shutdown());
+  return {
+    hooks, ctx, statuses, timers, writes,
+    select: model => hooks.model_select({ model }, context(model)),
+  };
+}
+
+for (const model of [undefined, { provider: 'openai', id: 'gpt-5' }, { provider: 'anthropic', id: 'claude-sonnet-4-6' }]) {
+  test(`cached Claude usage stays hidden for ${model?.provider ?? 'no model'}`, async t => {
+    const h = harness(t, model);
+    await h.hooks.session_start({}, h.ctx);
+    assert.equal(h.statuses.has('claude-usage'), false);
+  });
+}
+
+test('model changes hide and restore cached usage immediately, including timer refreshes', async t => {
+  const h = harness(t, { provider: 'claude-code', id: 'sonnet' });
+  await h.hooks.session_start({}, h.ctx);
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 42%/);
+
+  await h.select({ provider: 'openai', id: 'gpt-5' });
+  assert.equal(h.statuses.has('claude-usage'), false);
+  for (const refresh of h.timers) refresh();
+  assert.equal(h.statuses.has('claude-usage'), false);
+
+  await h.select({ provider: 'claude-code', id: 'sonnet' });
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 42%/);
+});
+
+test('diagnostics update the cache without exposing usage on another provider', async t => {
+  const h = harness(t, { provider: 'openai', id: 'gpt-5' }, null);
+  await h.hooks.session_start({}, h.ctx);
+  await h.hooks.message_end({ message: {
+    role: 'assistant',
+    diagnostics: [{ type: 'claude-code.rate-limit', details: {
+      unifiedWindows: { five_hour: { utilization: 0.75, resetsAt: 4_000_000_000 } },
+    } }],
+  } }, h.ctx);
+  assert.equal(h.statuses.has('claude-usage'), false);
+  assert.equal(h.writes.at(-1).fiveHour.pct, 75);
+  await h.select({ provider: 'claude-code', id: 'sonnet' });
+  assert.match(h.statuses.get('claude-usage'), /^Claude 5h 75%/);
+});

package/packages/pi-clipboard-image/README.md

@@ -1,5 +1,9 @@
 # Clipboard image attachment
 
+![Alt+V pastes a clipboard image into the draft as [Image #1]](screenshot.png)
+
+*Alt+V adds the clipboard image to the draft as `[Image #1]`. Sending the message sends the image to the model with it.*
+
 Attaches clipboard images to the draft, including copied image files on Windows.
 
 ## Try locally

package/packages/pi-clipboard-image/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-clipboard-image",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Attaches clipboard images to the draft, including copied image files on Windows.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/packages/pi-codeblock-borders/README.md

@@ -1,5 +1,9 @@
 # pi-codeblock-borders
 
+![The same reply rendered by stock pi and with codeblock borders](screenshot.png)
+
+*The same reply, rendered by stock pi and then with this extension. Code fences become full-width rules, and `title=`, `:line-numbers` and `{2}` line focus are rendered.*
+
 Render markdown code fences as full-width rules spanning the content area, and upgrade the fence info string with language decoration, titles, and line numbers that Pi's built-in renderer does not support.
 
 ## Running locally

package/packages/pi-codeblock-borders/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-codeblock-borders",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "description": "Decorated code fences",
   "engines": {

package/packages/pi-codegraph/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-codegraph
 
+![codegraph_explore returning source and blast radius, with CodeGraph sync status in the footer](screenshot.png)
+
+*The agent calls `codegraph_explore` and gets back the relevant source with its blast radius (expanded here with Ctrl+O). The footer shows the index status, which is synced after every turn.*
+
 ## Purpose and registrations
 
 Registers `codegraph_explore`, `/codegraph-init`, `/codegraph-sync`, `/codegraph-status`, `/codegraph-unlock`, session startup/shutdown and settle-sync hooks, and footer status.

package/packages/pi-codegraph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-codegraph",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/packages/pi-compact-tools/README.md

@@ -1,5 +1,9 @@
 # Compact tool cards
 
+![Four tool calls folded into one card, then expanded with Ctrl+O](screenshot.png)
+
+*Four tool calls in a row fold into one summary card. Ctrl+O expands it, and each call keeps its own status and output.*
+
 Groups consecutive tool calls into compact expandable transcript cards.
 
 ## Try locally

package/packages/pi-compact-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-compact-tools",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Groups consecutive tool calls into compact expandable transcript cards.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/packages/pi-decisions/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-decisions
 
+![The classify tool returning a structured triage answer with probabilities](screenshot.png)
+
+*The agent calls `classify` against a configured Decisions endpoint and gets structured answers with per-label probabilities.*
+
 ## Purpose and registrations
 
 When configured, registers classifier providers and the `classify` tool (choice/bool/score; JSON state and optional PNG/JPEG/WebP images). No slash commands. Requires Pi's classifier model registry APIs (`findOfType`, `classify`, provider `classifiers`); older hosts may not implement them.

package/packages/pi-decisions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-decisions",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/packages/pi-load-pi-dotenv/README.md

@@ -1,5 +1,9 @@
 # Pi dotenv loader
 
+![Environment variables from ~/.pi/agent/.env reaching a bash tool call](screenshot.png)
+
+*With this extension, variables from `~/.pi/agent/.env`, including `${VAR}` expansion, reach the tools the agent runs. Stock pi passes nothing through.*
+
 Loads environment variables from the Pi agent directory without replacing existing environment values.
 
 ## Try locally

package/packages/pi-load-pi-dotenv/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-load-pi-dotenv",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Loads environment variables from the Pi agent directory without replacing existing environment values.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/packages/pi-model-go/README.md

@@ -1,5 +1,9 @@
 # pi-model-go
 
+![/model-go picker sorted by effective price with credit multipliers and intelligence scores](screenshot.png)
+
+*`/model-go` lists OpenCode Go models sorted by effective price (input ÷ plan credit), with context size, intelligence score and credit multiplier.*
+
 Cost-aware model picker showing registry prices/context, OpenCode Go credit multipliers and stencil.so intelligence scores. Source describes it as a port of rizal72/oc-models-pro.
 
 ## Running locally

package/packages/pi-model-go/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-model-go",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/packages/pi-prestart-working/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-prestart-working
 
+![Spinner labelled with the extension whose before_agent_start hook is running](screenshot.png)
+
+*A slow `before_agent_start` hook normally leaves the UI silent after you press Enter. With this extension, the spinner names the extension that is running.*
+
 ## Purpose and registrations
 
 Shows Pi's native "Working" spinner, labelled with the extension currently blocking (e.g. `⠙ Loading hindsight-coding-agents`), while `before_agent_start` hooks run. Pi only raises its working indicator at `turn_start`, so slow handlers otherwise leave the UI silent. No tools, commands, or configuration.

package/packages/pi-prestart-working/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-prestart-working",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Show a labelled Working spinner while before_agent_start hooks run.",
   "type": "module",
   "license": "AGPL-3.0-only",

package/packages/pi-root-guard/README.md

@@ -1,5 +1,9 @@
 # Agent configuration root guard
 
+![A write into ~/.pi/agent blocked by the guardrail](screenshot.png)
+
+*Stock pi lets the agent rewrite its own config. With the guard, writes into the Pi and Claude config roots are blocked, and the agent is told why.*
+
 Blocks selected write/edit and simple bash writes into Pi and Claude configuration roots.
 
 ## Try locally

package/packages/pi-root-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-root-guard",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Blocks selected write/edit and simple bash writes into Pi and Claude configuration roots.",
   "type": "module",
   "license": "AGPL-3.0-only",

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-session-finder",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-session-id",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-session-nav",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-session-rename",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-session-retention",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-skill-usage-log",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-tool-usage-log",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-tts",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-user-image-previews",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Adds collapsible UI-only previews for newly submitted image attachments.",
   "type": "module",
   "license": "AGPL-3.0-only",

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,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-vision",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

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.

package/packages/pi-wait/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-wait",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [

package/packages/pi-zvec/README.md

@@ -1,5 +1,9 @@
 # @saifymatteo/pi-zvec
 
+![zvec_search hybrid results with Zvec index status in the footer](screenshot.png)
+
+*The agent calls `zvec_search` in hybrid mode, which combines lexical and semantic search (expanded here with Ctrl+O). The footer shows the index status.*
+
 ## Purpose and registrations
 
 Registers `zvec_search` (exact/fts/vector/hybrid/auto), `/zvec-init`, `/zvec-sync`, `/zvec-status`, session and settle-sync hooks, and footer status.

package/packages/pi-zvec/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-zvec",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [