pi-ketch 0.1.2 → 0.1.4

package/README.md

@@ -42,13 +42,7 @@ Install Chromium:
 ketch browser install
 ```
 
-The command prints a `Configure with:` command containing the installed browser path. Run that command, for example:
-
-```sh
-ketch config set browser /Users/you/Library/Caches/ketch/browser/chromium-1321438/Chromium.app/Contents/MacOS/Chromium
-```
-
-Verify the setup:
+The installer prints the exact `ketch config set browser ...` command for the browser it installed. Copy and run that command, then verify the setup:
 
 ```sh
 ketch browser status
@@ -61,36 +55,54 @@ For a known URL, start with a normal `ketch_scrape` call. Ketch fetches the page
 
 ### Search backend setup
 
-Once `pi-ketch` is installed, its Ketch tools are the default Pi workflow for web search and URL extraction:
+Web search needs one default backend. Brave is Ketch's default and requires an API key:
+
+```sh
+ketch config set brave_api_key <key>
+```
 
-- Use `ketch_search` instead of another extension's overlapping web-search tool.
-- Use `ketch_scrape` instead of another extension's overlapping page-extraction tool.
+To use another provider by default, select it once in Ketch:
 
-If your Pi setup already enables a competing web-search or web-extraction extension, disable that extension in `~/.pi/agent/settings.json` while keeping it installed. This avoids duplicate tools and conflicting routing instructions; do not uninstall it unless you want to remove it permanently.
+```sh
+ketch config set backend ddg
+# Other choices: searxng, exa, firecrawl, keenable
+```
 
-You only need one working search backend to get started:
+Some providers need credentials or a custom URL. Use Ketch's [configuration reference](https://1broseidon.github.io/ketch/) for the current keys and provider requirements rather than adding secrets to Pi settings.
 
-- **Brave**: direct API search with a Brave API key.
-- **SearXNG**: self-hosted metasearch through a configured SearXNG URL.
+Check what Ketch can use before opening Pi:
 
-You can use either one as the default backend. Routine `ketch_search` calls use that single configured default, which is the recommended behavior for normal searches. Brave is the simplest direct default; SearXNG adds self-hosted metasearch.
+```sh
+ketch config
+ketch doctor
+ketch search "test query"
+```
 
-For contested, multi-part, or deep research, `pi-ketch` can set `allBackends: true`. Ketch then uses `--multi=all` to discover and query every search backend it currently considers usable; users and agents do not need to hardcode provider names. An explicit `multi` list remains available for targeted provider comparisons.
+The operator chooses the backend; the agent normally does not. The bundled skill tells Pi to call `ketch_search` without `backend`, `multi`, or `allBackends`, so routine searches use your configured default. For deep or contested research, the agent may use `allBackends: true` to query every usable provider and fuse the rankings. An explicit `multi` list is reserved for a provider comparison you requested.
 
-Additional search backends—DuckDuckGo, Exa, Firecrawl, and Keenable—are optional. Firecrawl is used here only as an explicit or federated web-search backend; it does not power `ketch_scrape` or `ketch_crawl`.
+If another Pi extension exposes overlapping search or page-extraction tools, disable that extension in `~/.pi/agent/settings.json` to prevent duplicate tools and conflicting routing instructions. You can leave the package installed.
 
 ### Full capability setup
 
-For the complete Ketch feature set, configure the backends for the capabilities you want:
+Configure only the surfaces you plan to use. Each row below maps an agent tool to the Ketch service behind it.
+
+| Pi tool | Ketch capability | Starts with | Optional setup |
+| --- | --- | --- | --- |
+| `ketch_search` | Web search | Your configured default backend | Add more search providers for federated research. Brave and Firecrawl require API keys. |
+| `ketch_scrape` | Page extraction | Direct HTTP fetching and the local page cache | Install Chromium for JavaScript-rendered pages. |
+| `ketch_crawl` | Bounded site crawling | Direct HTTP fetching and the local page cache | Install Chromium for JavaScript-rendered pages. |
+| `ketch_code` | Public OSS code search | grep.app | Sourcegraph needs no setup. GitHub can use `gh auth login`, `GITHUB_TOKEN`, or Ketch's `github_token`. |
+| `ketch_docs` | Library documentation | Context7 | Set `context7_api_key`; this surface requires a Context7 key. |
+
+A practical full setup is:
 
-- Search: one default such as Brave or SearXNG. Configure additional providers only for fallback, explicit comparisons, or `allBackends` deep research.
-- Optional federated search: add providers such as Firecrawl when you want them included in multi-backend web searches.
-- Public code search: grep.app, Sourcegraph, and GitHub. GitHub search uses the `gh` CLI token when available.
-- Library documentation: a Context7 API key for `ketch_docs`.
-- JavaScript-rendered pages: the optional Chromium browser setup above.
-- Caching: enabled automatically through Ketch's local bbolt cache.
+1. Configure and test one default search backend.
+2. Add a Context7 key if you want library documentation.
+3. Authenticate GitHub if you want GitHub Code Search in addition to grep.app and Sourcegraph.
+4. Install Chromium if you need rendered pages.
+5. Add extra search providers only if you expect to use federated research.
 
-Run `ketch doctor` to check every configured surface. A healthy setup reports all applicable checks as `ok`; optional backends without credentials can be left disabled.
+Run `ketch doctor` after changing configuration. It probes configured search providers, code search, Context7, the browser, and the cache. Optional services can remain unconfigured; the tools backed by them will report a precondition error when called.
 
 ## What it adds
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ketch",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Agent-native web research tools for Pi: multi-backend search, public code search, library docs, scraping, crawling, and browser rendering, powered by Ketch.",
   "type": "module",
   "license": "MIT",

package/skills/ketch/SKILL.md

@@ -33,9 +33,9 @@ Do not route routine web search or URL extraction through another extension's ov
 ## Default workflow
 
 1. Choose one surface using the table above.
-2. For routine web search, call `ketch_search` without `backend`, `multi`, or `allBackends`; Ketch will use the user's configured default backend.
-3. For contested, time-sensitive, multi-part, or deep research, use `allBackends: true`; Ketch dynamically queries every backend it currently considers usable, so do not hardcode provider names.
-4. Use an explicit `backend` or `multi` list only when the user requests particular providers or a targeted backend retry is needed.
+2. For every routine web search, call `ketch_search` without `backend`, `multi`, or `allBackends`; Ketch must use the user's single configured default backend. Never automatically send `multi: ["brave", "ddg"]` or any other provider list.
+3. Reserve federated search for deeper work: use `allBackends: true` for contested, time-sensitive, multi-part, or deep research. Ketch dynamically queries every backend it currently considers usable, so do not hardcode provider names.
+4. Use an explicit `multi` list only for deeper corroboration or when the user requests particular providers. Use an explicit single `backend` only for a user request or targeted retry.
 5. Make bounded calls, cite the URL supporting every externally sourced claim, and state material retrieval failures instead of treating missing sources as evidence.
 
 For deep research, read `references/research.md`. For detailed parameters and gotchas, read `references/surfaces.md`. For missing keys, browser setup, or backend failures, read `references/setup.md`.

package/skills/ketch/references/surfaces.md

@@ -2,7 +2,7 @@
 
 ## `ketch_search`
 
-Use for the open web. A routine search should omit `backend`, `multi`, and `allBackends` so Ketch uses the user's configured default. For contested, multi-part, or deep research, set `allBackends: true`; Ketch translates this to `--multi=all` and dynamically queries every backend it currently considers usable. `backend` selects one provider and `multi` selects an explicit provider list; all three modes are mutually exclusive. Set `scrape: true` only when fetched content from every result is needed. Pair it with a low `limit` and explicit `maxChars`.
+Use for the open web. Every routine search must omit `backend`, `multi`, and `allBackends` so Ketch uses the user's single configured default; never automatically submit `multi: ["brave", "ddg"]` or another provider list. Reserve federation for deeper work: set `allBackends: true` for contested, multi-part, or deep research, or use `multi` only for deeper corroboration or a user-requested provider comparison. Ketch translates `allBackends` to `--multi=all` and dynamically queries every backend it currently considers usable. `backend` selects one provider and `multi` selects an explicit provider list; all three modes are mutually exclusive. Set `scrape: true` only when fetched content from every result is needed. Pair it with a low `limit` and explicit `maxChars`.
 
 ## `ketch_code`
 

package/src/index.ts

@@ -17,8 +17,7 @@ export default function ketchExtension(pi: ExtensionAPI): void {
   registerDiagnostics(pi);
 
   pi.on("session_start", (_event, ctx) => {
-    const theme = ctx.ui.theme;
-    ctx.ui.setStatus(STATUS_ID, `${theme.fg("accent", "🌐 ketch:")} ${theme.fg("success", "active")}`);
+    ctx.ui.setStatus(STATUS_ID, "🌐 ketch: active");
   });
 
   pi.on("session_shutdown", (_event, ctx) => {

package/src/schemas.ts

@@ -8,8 +8,8 @@ const DocsBackend = StringEnum(["context7"] as const);
 export const SearchParams = Type.Object({
   query: Type.String({ description: "Web search query." }),
   backend: Type.Optional(SearchBackend),
-  multi: Type.Optional(Type.Array(SearchBackend, { description: "Explicit search backends to query together. Cannot be combined with backend or allBackends.", maxItems: 6 })),
-  allBackends: Type.Optional(Type.Boolean({ description: "Query every search backend Ketch currently considers usable. Intended for deep research, not routine searches." })),
+  multi: Type.Optional(Type.Array(SearchBackend, { description: "Query an explicit backend set only for deep research, corroboration, or a user-requested provider comparison. Never use for routine searches; omit it to use the configured default backend. Cannot be combined with backend or allBackends.", maxItems: 6 })),
+  allBackends: Type.Optional(Type.Boolean({ description: "Query every search backend Ketch currently considers usable. Use only for contested or deep research; never for routine searches." })),
   limit: Type.Optional(Type.Integer({ description: "Maximum results. Defaults to Ketch config; capped at 20.", minimum: 1, maximum: 20 })),
   scrape: Type.Optional(Type.Boolean({ description: "Fetch result pages and include extracted content." })),
   trim: Type.Optional(Type.Boolean({ description: "Strip Markdown formatting from scraped content." })),

package/src/tools/search.ts

@@ -27,12 +27,12 @@ export function registerSearchTool(pi: ExtensionAPI): void {
     defineTool({
       name: "ketch_search",
       label: "Ketch Web Search",
-      description: "Search the live web through Ketch using configured Brave, DuckDuckGo, SearXNG, Exa, Firecrawl, or Keenable backends. Can optionally scrape bounded content from each result.",
+      description: "Search the live web through Ketch. Routine searches must omit backend, multi, and allBackends so Ketch uses one configured default backend. Federated modes are reserved for deeper research. Can optionally scrape bounded content from each result.",
       parameters: SearchParams,
-      promptSnippet: "ketch_search: Search the current external web through Ketch; cite returned URLs.",
+      promptSnippet: "ketch_search: For routine web search, omit backend options and use only Ketch's configured default; cite returned URLs.",
       promptGuidelines: [
-        "Use ketch_search without backend options for routine searches so Ketch uses the user's configured default backend.",
-        "Use ketch_search with allBackends for contested, multi-part, or deep research that needs results from every currently usable backend; cite returned URLs.",
+        "For every routine search, omit backend, multi, and allBackends. Do not automatically send multi: ['brave', 'ddg'] or any other provider list; Ketch must use the user's single configured default backend.",
+        "Use multi only for deeper corroboration or an explicit request to compare particular providers. Prefer allBackends for contested, multi-part, or deep research that needs every currently usable backend.",
         "When ketch_search uses scrape, bound each fetched result with maxChars.",
       ],
       ...ketchRenderers("ketch_search"),