@mrclrchtr/supi-web 1.3.0 → 1.4.0

package/README.md

@@ -1,11 +1,9 @@
 # @mrclrchtr/supi-web
 
-Fetch web pages as clean Markdown and query library documentation via [Context7](https://context7.com) for the [pi coding agent](https://github.com/earendil-works/pi).
+Adds web-page fetching and library-documentation lookup tools to the [pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
 
-Included in `@mrclrchtr/supi`, or install standalone:
-
 ```bash
 pi install npm:@mrclrchtr/supi-web
 ```
@@ -16,90 +14,79 @@ For local development:
 pi install ./packages/supi-web
 ```
 
-After editing the source, run `/reload` to pick up changes.
-
-## Package surfaces
-
-- `@mrclrchtr/supi-web/api` — programmatic exports (conversion helpers, fetch utilities, tool factories)
-- `@mrclrchtr/supi-web/extension` — aggregated pi extension entrypoint that registers all three tools
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+After editing the source, run `/reload`.
 
-## What it adds
+## What you get
 
-Registers three agent-callable tools:
+After install, pi gets three tools:
 
-| Tool | Purpose |
-|------|---------|
-| `web_fetch_md` | Fetch an `http(s)` URL and return clean Markdown |
-| `web_docs_search` | Search Context7 for libraries by name |
-| `web_docs_fetch` | Retrieve up-to-date documentation for a specific library via Context7 |
+- `web_fetch_md` — fetch a web page and convert it to Markdown
+- `web_docs_search` — search Context7 for a library ID
+- `web_docs_fetch` — fetch up-to-date documentation for a specific Context7 library
 
-## web_fetch_md — Web Page to Markdown
+## Choose the right tool
 
-### Parameters
+### `web_fetch_md`
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `url` | `string` | **required** | `http://` or `https://` URL to fetch |
-| `output_mode` | `"auto" \| "inline" \| "file"` | `"auto"` | `auto` returns inline if ≤15,000 chars, else writes to temp file |
-| `abs_links` | `boolean` | `true` | Absolutize relative links and image sources |
-| `timeout_ms` | `number` | `30000` | Fetch timeout in milliseconds |
+Use this for general web pages.
 
-### Content negotiation
+Important behavior:
 
-The tool tries multiple strategies to get clean Markdown:
+- accepts only real `http://` or `https://` URLs
+- defaults to `output_mode: auto`
+- returns Markdown inline when the result is at most **15,000 characters**
+- otherwise writes the Markdown to a temporary `.md` file and returns the file path
+- absolutizes links and image URLs by default
+- wraps plain-text responses as fenced code blocks instead of pretending they are prose
 
-1. **HEAD negotiation** — checks `content-type` for Markdown
-2. **Sniffing** — range GET of first 8KB to detect Markdown/plain text vs HTML
-3. **Sibling probing** — tries `.md` / `.markdown` variants (e.g. `page.md` for `page.html`)
-4. **HTML conversion** — full GET → JSDOM + Readability + Turndown → clean Markdown
+The fetch pipeline tries several strategies in order:
 
-## web_docs_search — Library Lookup
+1. Markdown-aware content negotiation
+2. content sniffing
+3. sibling `.md` / `.markdown` probing
+4. HTML fetch followed by Readability + Turndown conversion
 
-Searches Context7's library index and returns a Markdown table of matching libraries with metadata.
+### `web_docs_search`
 
-### Parameters
+Use this when you need a Context7 library ID first.
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `library_name` | `string` | **required** | Library name to search for (e.g. `"react"`, `"next.js"`, `"fastapi"`) |
-| `query` | `string` | **required** | What the agent is trying to do — used for relevance ranking |
+It returns a Markdown table of matching libraries with fields such as:
 
-### Output
+- ID
+- name
+- description
+- trust score
+- benchmark score
+- snippet count
+- versions
 
-Returns a Markdown table with columns: Name, ID, Description, Trust Score, Benchmark Score, Snippet Count, Versions. The agent picks a library ID from these results to pass to `web_docs_fetch`.
+### `web_docs_fetch`
 
-## web_docs_fetch — Documentation Retrieval
+Use this when you already know the Context7 library ID and want current docs or snippets for a specific question.
 
-Fetches up-to-date documentation context for a specific library via Context7's API.
+- `library_id` is required
+- `query` is required
+- `raw: true` returns JSON-serialized snippet objects instead of plain text Markdown
 
-### Parameters
+## Context7 notes
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `library_id` | `string` | **required** | Context7 library ID (e.g. `/facebook/react`, `/vercel/next.js/v15.1.8`) |
-| `query` | `string` | **required** | Specific question about the library |
-| `raw` | `boolean` | `false` | When `true`, returns JSON-serialized snippet objects instead of plain text Markdown |
+`web_docs_search` and `web_docs_fetch` use Context7 through `@upstash/context7-sdk`.
 
-### API Key (optional)
+If `CONTEXT7_API_KEY` is set, the SDK will use it automatically.
 
-The tool reads the `CONTEXT7_API_KEY` environment variable automatically when set. Without a key, it works with lower rate limits. Get a key at [context7.com/dashboard](https://context7.com/dashboard).
-
-### Source files
+## Package surfaces
 
-- `src/api.ts` — public package exports
-- `src/extension.ts` — aggregated extension entrypoint
-- `src/web.ts` — `web_fetch_md` tool registration
-- `src/docs.ts` — `web_docs_search` + `web_docs_fetch` tool registration
-- `src/context7-client.ts` — thin wrapper around `@upstash/context7-sdk`
-- `src/fetch.ts` — HTTP fetch logic
-- `src/convert.ts` — HTML to Markdown conversion
+- `@mrclrchtr/supi-web/api` — conversion helpers, fetch helpers, and extension exports
+- `@mrclrchtr/supi-web/extension` — extension entrypoint that registers all three tools
 
-## Commands
+## Source
 
-```bash
-pnpm vitest run packages/supi-web/
-pnpm exec tsc --noEmit -p packages/supi-web/tsconfig.json
-pnpm exec biome check packages/supi-web/
-```
+- `src/web.ts` — `web_fetch_md`
+- `src/docs.ts` — `web_docs_search` and `web_docs_fetch`
+- `src/fetch.ts` — HTTP fetching and negotiation
+- `src/convert.ts` — HTML-to-Markdown conversion
+- `src/context7-client.ts` — Context7 client wrapper
+- `src/temp-file.ts` — temp-file output helper
+- `src/tool/web-fetch-md-guidance.ts` — model-facing prompt surfaces for `web_fetch_md`
+- `src/tool/web-docs-search-guidance.ts` — model-facing prompt surfaces for `web_docs_search`
+- `src/tool/web-docs-fetch-guidance.ts` — model-facing prompt surfaces for `web_docs_fetch`

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

package/node_modules/@mrclrchtr/supi-core/src/extension.ts

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -64,14 +64,14 @@ export {
   walkProject,
 } from "./project-roots.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-web",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi Web extension — fetch web pages as clean Markdown (web_fetch_md) and library docs via Context7 (web_docs_search, web_docs_fetch)",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     "@mozilla/readability": "^0.6.0",
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
-    "@mrclrchtr/supi-core": "1.3.0"
+    "@mrclrchtr/supi-core": "1.4.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -44,7 +44,8 @@
   },
   "pi": {
     "extensions": [
-      "./src/extension.ts"
+      "./src/extension.ts",
+      "node_modules/@mrclrchtr/supi-core/src/extension.ts"
     ]
   },
   "main": "src/api.ts",

package/src/docs.ts

@@ -8,43 +8,29 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { Context7Error, getContext, searchLibrary } from "./context7-client.ts";
+import {
+  promptGuidelines as fetchPromptGuidelines,
+  promptSnippet as fetchPromptSnippet,
+  toolDescription as fetchToolDescription,
+} from "./tool/web-docs-fetch-guidance.ts";
+import {
+  promptGuidelines as searchPromptGuidelines,
+  promptSnippet as searchPromptSnippet,
+  toolDescription as searchToolDescription,
+} from "./tool/web-docs-search-guidance.ts";
 
 const SEARCH_TOOL_NAME = "web_docs_search";
 const SEARCH_TOOL_LABEL = "Web Docs Search";
 const FETCH_TOOL_NAME = "web_docs_fetch";
 const FETCH_TOOL_LABEL = "Web Docs Fetch";
 
-const SEARCH_TOOL_DESCRIPTION = `Search for libraries via Context7. Returns a Markdown table of matching libraries with metadata (ID, name, description, trust score, benchmark score, snippet count, versions). Use the library ID from results with web_docs_fetch to retrieve documentation.`;
-
-const FETCH_TOOL_DESCRIPTION = `Retrieve documentation context for a specific library via Context7. Returns up-to-date code snippets and documentation prose as Markdown, tailored to the query. Use web_docs_search first to find the library ID. Set raw=true to get JSON-serialized snippet objects instead of plain text. Requires a Context7 library ID (e.g. /facebook/react, /vercel/next.js).`;
-
-const SEARCH_PROMPT_SNIPPET =
-  "web_docs_search — search Context7 for libraries matching a name, returns library IDs for use with web_docs_fetch";
-
-const FETCH_PROMPT_SNIPPET =
-  "web_docs_fetch — retrieve up-to-date documentation context from Context7 for a specific library";
-
-const SEARCH_PROMPT_GUIDELINES = [
-  "Use web_docs_search to find Context7 library IDs by name before calling web_docs_fetch.",
-  "Pass a descriptive query along with the library name for better relevance ranking.",
-  "Review the search results carefully — pick the library ID that best matches the user's need.",
-];
-
-const FETCH_PROMPT_GUIDELINES = [
-  "Use web_docs_fetch to get up-to-date, version-specific documentation for any library.",
-  "The library_id must be a Context7 library ID like /facebook/react or /vercel/next.js.",
-  "Set raw=true only when you need structured JSON snippets instead of plain text Markdown.",
-  "If the library ID is unknown, call web_docs_search first to find it.",
-  "Prefer descriptive, specific queries over vague ones for better results.",
-];
-
 export default function docsExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: SEARCH_TOOL_NAME,
     label: SEARCH_TOOL_LABEL,
-    description: SEARCH_TOOL_DESCRIPTION,
-    promptSnippet: SEARCH_PROMPT_SNIPPET,
-    promptGuidelines: SEARCH_PROMPT_GUIDELINES,
+    description: searchToolDescription,
+    promptSnippet: searchPromptSnippet,
+    promptGuidelines: searchPromptGuidelines,
     parameters: Type.Object({
       library_name: Type.String({
         description: "Library name to search for (e.g. react, next.js, fastapi)",
@@ -59,9 +45,9 @@ export default function docsExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: FETCH_TOOL_NAME,
     label: FETCH_TOOL_LABEL,
-    description: FETCH_TOOL_DESCRIPTION,
-    promptSnippet: FETCH_PROMPT_SNIPPET,
-    promptGuidelines: FETCH_PROMPT_GUIDELINES,
+    description: fetchToolDescription,
+    promptSnippet: fetchPromptSnippet,
+    promptGuidelines: fetchPromptGuidelines,
     parameters: Type.Object({
       library_id: Type.String({
         description:

package/src/tool/web-docs-fetch-guidance.ts

@@ -0,0 +1,14 @@
+// Prompt guidance and tool description for the web_docs_fetch tool.
+
+export const toolDescription = `Retrieve up-to-date documentation context for a specific library via Context7. Returns Markdown documentation and code snippets tailored to the query, or JSON-serialized snippet objects when \`raw: true\`. Use web_docs_fetch after web_docs_search or whenever the exact Context7 library ID is already known. Requires a Context7 library ID (e.g. /facebook/react, /vercel/next.js).`;
+
+export const promptSnippet =
+  "web_docs_fetch — retrieve focused, up-to-date Context7 docs for a known library ID";
+
+export const promptGuidelines = [
+  "Use web_docs_fetch after web_docs_search, or use web_docs_fetch directly when the exact Context7 `library_id` is already known.",
+  "Use web_docs_fetch only with Context7 library IDs such as `/facebook/react` or `/vercel/next.js`.",
+  "Use web_docs_fetch with a specific, task-oriented `query` to retrieve focused version-aware documentation instead of a vague broad dump.",
+  "Use web_docs_fetch with `raw: true` only when you need structured JSON snippet objects instead of Markdown documentation.",
+  "Call web_docs_search before web_docs_fetch when the correct `library_id` is unknown or ambiguous.",
+];

package/src/tool/web-docs-search-guidance.ts

@@ -0,0 +1,12 @@
+// Prompt guidance and tool description for the web_docs_search tool.
+
+export const toolDescription = `Search Context7 for library IDs and metadata before fetching docs. Returns a Markdown table of matching libraries (ID, name, description, trust score, benchmark score, snippet count, versions). Use web_docs_search when you know the library name but not the exact Context7 library ID.`;
+
+export const promptSnippet =
+  "web_docs_search — find Context7 library IDs and candidate versions before calling web_docs_fetch";
+
+export const promptGuidelines = [
+  "Use web_docs_search before web_docs_fetch when you do not already know the exact Context7 `library_id`.",
+  "Use web_docs_search with both `library_name` and a descriptive `query` so Context7 can rank results for the user's actual task.",
+  "Review web_docs_search results carefully and choose the `library_id` that best matches the user's framework, package scope, and version needs.",
+];

package/src/tool/web-fetch-md-guidance.ts

@@ -0,0 +1,44 @@
+import { spawnSync } from "node:child_process";
+
+// Prompt guidance and tool description for the web_fetch_md tool.
+
+const INLINE_MAX_CHARS = 15_000;
+
+export const toolDescription = `Fetch a web page and convert it to clean Markdown for LLM ingestion.
+
+Use web_fetch_md when the user provides a public URL or asks you to inspect public web content. Only accepts real \`http://\` or \`https://\` URLs. If the page is access-controlled (login, paywall, private content), stop and ask the user for an allowed source or exported content.
+
+Output modes:
+- \`auto\` (default): returns Markdown inline if ≤${INLINE_MAX_CHARS.toLocaleString()} characters; otherwise writes to a temporary file and returns the path.
+- \`inline\`: always returns Markdown inline.
+- \`file\`: always writes to a temporary file and returns the path.
+
+Links and images are absolutized by default. Use \`abs_links: false\` to keep them as-is.`;
+
+export const promptSnippet =
+  "web_fetch_md — fetch a public URL and convert the response to clean Markdown for LLM ingestion";
+
+function isGhAvailable(): boolean {
+  try {
+    const result = spawnSync("gh", ["--version"], { stdio: "ignore" });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function buildPromptGuidelines(): string[] {
+  const guidelines = [
+    "Use web_fetch_md to fetch a public web page and convert it to clean Markdown for the model.",
+    "Use web_fetch_md only with real `http://` or `https://` URLs; if a page is access-controlled, stop and ask the user for an allowed source or exported content.",
+    "Use web_fetch_md with `output_mode: auto` unless you have a specific reason to force inline output or a temp file path.",
+    "Use web_fetch_md with `output_mode: inline` only when you need the Markdown directly in context, and use web_fetch_md with `output_mode: file` when you explicitly want a saved temp file path.",
+    "Use web_fetch_md with `abs_links: false` only when relative links or images are intentionally desired.",
+  ];
+  if (isGhAvailable()) {
+    guidelines.push(
+      "Use bash with the `gh` CLI instead of web_fetch_md for GitHub URLs when `gh` is available.",
+    );
+  }
+  return guidelines;
+}

package/src/web.ts

@@ -2,55 +2,21 @@
  * SuPi Web extension entry point — registers the `web_fetch_md` tool with pi.
  */
 
-import { spawnSync } from "node:child_process";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { htmlToMarkdown, wrapAsCodeBlock } from "./convert.ts";
 import { FetchError, fetchWithNegotiation, isValidHttpUrl } from "./fetch.ts";
 import { writeTempFile } from "./temp-file.ts";
+import {
+  buildPromptGuidelines,
+  promptSnippet,
+  toolDescription,
+} from "./tool/web-fetch-md-guidance.ts";
 
 const TOOL_NAME = "web_fetch_md";
 const TOOL_LABEL = "Web Fetch";
 const INLINE_MAX_CHARS = 15_000;
 
-const TOOL_DESCRIPTION = `Fetch a web page and convert it to clean Markdown for LLM ingestion.
-
-Only accepts real \`http://\` or \`https://\` URLs. If the page is access-controlled (login, paywall, private content), stop and ask the user for an allowed source or exported content.
-
-Output modes:
-- \`auto\` (default): returns Markdown inline if ≤${INLINE_MAX_CHARS.toLocaleString()} characters; otherwise writes to a temporary file and returns the path.
-- \`inline\`: always returns Markdown inline.
-- \`file\`: always writes to a temporary file and returns the path.
-
-Links and images are absolutized by default. Use \`abs_links: false\` to keep them as-is.`;
-
-const PROMPT_SNIPPET =
-  "web_fetch_md — fetch a URL and convert it to clean Markdown suitable for LLM ingestion.";
-
-function isGhAvailable(): boolean {
-  try {
-    const result = spawnSync("gh", ["--version"], { stdio: "ignore" });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-
-function buildPromptGuidelines(): string[] {
-  const guidelines = [
-    "Use web_fetch_md to fetch web pages and convert them to clean Markdown for LLM ingestion.",
-    "Only accept real `http://` or `https://` URLs; stop and ask the user for an allowed source if the page is access-controlled.",
-    "Prefer `output_mode: auto` (default) so large pages are written to temp files instead of flooding the context window.",
-    "Set `abs_links: false` only when relative links are intentional (e.g., local documentation).",
-  ];
-  if (isGhAvailable()) {
-    guidelines.push(
-      "For GitHub URLs (e.g., repos, issues, PRs, releases), prefer the `gh` CLI via `bash` over this tool.",
-    );
-  }
-  return guidelines;
-}
-
 const OutputModeEnum = Type.Union(
   [Type.Literal("auto"), Type.Literal("inline"), Type.Literal("file")],
   { default: "auto", description: "Output mode: auto, inline, or file" },
@@ -60,8 +26,8 @@ export default function webExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: TOOL_NAME,
     label: TOOL_LABEL,
-    description: TOOL_DESCRIPTION,
-    promptSnippet: PROMPT_SNIPPET,
+    description: toolDescription,
+    promptSnippet,
     promptGuidelines: buildPromptGuidelines(),
     parameters: Type.Object({
       url: Type.String({ description: "http(s) URL to fetch" }),