1st-pi 0.1.1 → 0.3.2

package/README.md

@@ -8,6 +8,8 @@
 
 ## 安装
 
+需要 Pi `>=1.1.0`；`@tintinweb/pi-subagents` 0.20 起要求该版本，`pi-btw` 0.7 起要求 `>=0.85.1`。
+
 ### GitHub
 
 ```bash
@@ -121,25 +123,25 @@ Preset 默认开启以下 TUI 增强，session 中持久化的个人选择优先
 
 | 包 | 功能 |
 |---|---|
-| [pi-web-access](https://www.npmjs.com/package/pi-web-access) | Web 搜索、URL/GitHub/YouTube 访问及 librarian skill |
+| [pi-web-access](https://www.npmjs.com/package/pi-web-access) | Web 搜索、URL/GitHub/YouTube 访问、来源检查与可配置 provider routing |
 | [pi-init](https://www.npmjs.com/package/pi-init) | 生成或更新 `AGENTS.md` 的 init skill |
-| [pi-mcp-adapter](https://www.npmjs.com/package/pi-mcp-adapter) | MCP 协议适配 |
 | [pi-everforest-tui](https://www.npmjs.com/package/pi-everforest-tui) | Everforest light/dark themes 与可选 TUI 增强 |
 | [pi-session-name](https://www.npmjs.com/package/pi-session-name) | 自动生成会话标题并同步终端标题 |
 | [@juicesharp/rpiv-ask-user-question](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) | 多问题、选项预览和自由输入的结构化提问 UI |
-| [@narumitw/pi-goal](https://www.npmjs.com/package/@narumitw/pi-goal) | Session-scoped `/goal` 持续执行与完成/阻塞门禁 |
-| [pi-observational-memory](https://www.npmjs.com/package/pi-observational-memory) | 跨压缩保留 observations/reflections 的长会话记忆 |
-| [@ff-labs/pi-fff](https://www.npmjs.com/package/@ff-labs/pi-fff) | 本地 Rust 模糊文件/内容搜索与 `@` 自动补全 |
-| [pi-readseek](https://www.npmjs.com/package/pi-readseek) | Parser-backed code map/search、definition/reference、hashline edit 与 workspace rename；其 edit 可进行带警告的 fuzzy anchor relocation，不等同于严格 stale rejection |
+| [@narumitw/pi-goal](https://www.npmjs.com/package/@narumitw/pi-goal) | Session-scoped `/goal` 持续执行与完成/阻塞门禁；可选 experimental ordered-goal queue |
+| [@ff-labs/pi-fff](https://www.npmjs.com/package/@ff-labs/pi-fff) | 本地 Rust 模糊文件/内容搜索与 `@` 自动补全；`find`/`grep` 支持 workspace-relative 约束和 workspace 外的绝对路径 |
+| [pi-readseek](https://www.npmjs.com/package/pi-readseek) | Parser-backed code map/search、PDF index/view、definition/reference、hashline edit 与 workspace rename；其 edit 可进行带警告的 fuzzy anchor relocation，不等同于严格 stale rejection |
 | [pi-btw](https://www.npmjs.com/package/pi-btw) | 不污染主上下文的并行 `/btw` 旁路对话 |
 | [@mrclrchtr/supi-context](https://www.npmjs.com/package/@mrclrchtr/supi-context) | `/supi-context` 上下文组成与 token 占用报告 |
 | [@tintinweb/pi-subagents](https://www.npmjs.com/package/@tintinweb/pi-subagents) | Claude Code 风格 sub-agents |
 | [@tintinweb/pi-tasks](https://www.npmjs.com/package/@tintinweb/pi-tasks) | Task tracking 与协作 |
-| [@quintinshaw/pi-dynamic-workflows](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows) | 动态 workflows；preset 默认关闭 `workflow/workflows` 关键词自动触发，仅通过 `/workflows`、已保存 workflow 的 slash command 或显式 `/workflows-trigger on` 启用 |
+| [@quintinshaw/pi-dynamic-workflows](https://www.npmjs.com/package/@quintinshaw/pi-dynamic-workflows) | 动态 workflows；3.x 的关键词只授权模型选择 workflow、不再强制触发；preset 默认关闭该关键词入口，仍可通过 `/workflows`、已保存 workflow slash command 或显式 `/workflows-trigger on` 启用 |
 
 这些包位于普通 npm `dependencies`，安装 preset 时由 npm 获取，不会塞入 `1st-pi` tarball。`extensions/packages/*.ts` 是只负责调用 dependency extension entrypoint 的 thin adapters；因此依赖可以正常 hoist，同时 Pi manifest 只引用本包内稳定路径。FFF 也会由 npm 在 macOS、Linux 和 Windows 上选择正确的原生 binary。
 
-Themes 以及 `pi-init` / `pi-web-access` skills 是发布所需的静态资源，会从锁定依赖同步到本包。更新 dependencies 后运行：
+当前 dependency extension 版本以 `package.json` 与 lockfile 为准；维护时使用 npm `latest` 稳定标签，并通过 `npm outdated` 确认没有落后版本。
+
+Themes 以及 `pi-init` skill 是发布所需的静态资源，会从锁定依赖同步到本包。`pi-web-access` 从 0.14.0 起不再提供 `librarian` skill，preset 同步移除该过期副本，保留 extension 自身的搜索、抓取与 source-check surface。更新 dependencies 后运行：
 
 ```bash
 npm run sync:resources
@@ -151,11 +153,12 @@ npm run check:resources
 TUI 与 tool ownership：
 
 - `pi-everforest-tui`：全局主题、editor chrome、working/status/footer、Command Center 与 Theme Lab
-- `@ff-labs/pi-fff`：preset 默认使用 `override` mode，由 FFF 接管 `find`、`grep` 与 `@` autocomplete
-- `pi-readseek`：通过 `readseek.replacedTools` 接管 `read`、`edit`、`write`；结构导航和 hashline 工具继续使用 `readSeek_*` 名称，不与 FFF 争夺 `grep`
+- `@ff-labs/pi-fff`：preset 默认使用 `override` mode，由 FFF 接管 `find`、`grep` 与 `@` autocomplete；`--fff-mode`、`PI_FFF_MODE` 或 `~/.pi/agent/pi-fff.json` 的 `mode` 一旦显式设置，均优先于 preset 默认值
+- `pi-readseek`：通过 `readseek.overrideTools` 接管 `read`、`edit`、`write`；`readSeek_grep` 仍可显式用于生成 edit-ready anchors，但 preset 会移除其“优先于 `grep`”提示，默认内容搜索仍由 FFF `grep` 负责
 - Pi built-ins：继续负责 `bash`、`ls` 及其原生渲染
-- `pi-mcp-adapter`：负责 MCP 工具与渲染
+- Pi 内置 MCP：负责 MCP servers、`/mcp` 与 `pi mcp add/list`，读取 `~/.pi/agent/mcp.json` 与 `.pi/mcp.json`。preset 不再捆绑 `pi-mcp-adapter`；原先放在 `.mcp.json` 或 `~/.config/mcp/mcp.json` 的 servers 需要移入上述文件。曾加载 0.3.0 的用户，`settings.json` 的 `extensions` 中可能残留 adapter 写入的 `-builtin:mcp`，需在 `pi config` → Built-in 重新开启 MCP
 - Tasks、Subagents、Workflows、Goal、BTW、Context 与 Memory：继续使用各 package 自己的领域 UI
+- `workflow` tool 由 `@quintinshaw/pi-dynamic-workflows` 负责。`@tintinweb/pi-subagents` 只保留 `Agent` 等 subagent 能力：全局与项目 `subagents.json` 都未设置 `workflowsEnabled` 时，preset 会在 `~/.pi/agent/subagents.json` 写入 `"workflowsEnabled": false`（保留其他字段，格式损坏的文件不动），关闭其 `SubagentWorkflow`，避免每次启动出现 workflow 冲突 warning（见 [tintinweb/pi-subagents#283](https://github.com/tintinweb/pi-subagents/issues/283)）。已有的显式 `true`/`false` 不会被覆盖；设为 `true` 可强制两套 workflow 并存，不推荐
 
 Workflow 关键词触发在首次加载 preset 时默认写为关闭；已有明确的 `on`/`off` 用户配置会保留，不会被 preset 覆盖。关闭关键词触发不影响 `/workflows` 及已保存 workflow 的 slash commands。
 
@@ -166,7 +169,7 @@ Workflow 关键词触发在首次加载 preset 时默认写为关闭；已有明
 ```json
 {
   "readseek": {
-    "replacedTools": ["read", "edit", "write"]
+    "overrideTools": ["read", "edit", "write"]
   }
 }
 ```

package/extensions/packages/fff.ts

@@ -1,12 +1,28 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "@ff-labs/pi-fff/src/config.ts";
 import registerFff from "@ff-labs/pi-fff/src/index.ts";
+import { registerWithToolTransform } from "./tool-registration-transform.ts";
+
+const PRESET_MODE = "override";
+
+// FFF resolves its mode at session start as flag > env > pi-fff.json > fallback.
+// The preset default fills only the fallback slot, so every explicit choice wins.
+function withPresetModeDefault(pi: ExtensionAPI): void {
+  const getFlag = pi.getFlag.bind(pi);
+  pi.getFlag = ((name: string) => {
+    const value = getFlag(name);
+    if (name !== "fff-mode" || value !== undefined) return value;
+    if (process.env.PI_FFF_MODE || loadConfig().mode) return value;
+    return PRESET_MODE;
+  }) as ExtensionAPI["getFlag"];
+}
 
 export default function fffAdapter(pi: ExtensionAPI): void {
-  const configuredMode = process.env.PI_FFF_MODE;
-  if (!configuredMode) process.env.PI_FFF_MODE = "override";
-  try {
-    registerFff(pi);
-  } finally {
-    if (!configuredMode) delete process.env.PI_FFF_MODE;
-  }
+  withPresetModeDefault(pi);
+  registerWithToolTransform(pi, registerFff, (tool) => ({
+    ...tool,
+    promptGuidelines: tool.promptGuidelines?.map(
+      (guideline) => `${tool.name}: ${guideline}`,
+    ),
+  }));
 }

package/extensions/packages/readseek.ts

@@ -1 +1,17 @@
-export { default } from "pi-readseek";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerReadseek from "pi-readseek";
+import { registerWithToolTransform } from "./tool-registration-transform.ts";
+
+const READSEEK_GREP_PREFERENCE = "Prefer readSeek_grep over grep when both are available;";
+
+export default function readseekAdapter(pi: ExtensionAPI): void {
+  registerWithToolTransform(pi, registerReadseek, (tool) => {
+    if (tool.name !== "readSeek_grep") return tool;
+    return {
+      ...tool,
+      promptGuidelines: tool.promptGuidelines?.filter(
+        (guideline) => !guideline.startsWith(READSEEK_GREP_PREFERENCE),
+      ),
+    };
+  });
+}

package/extensions/packages/subagents.ts

@@ -1 +1,46 @@
-export { default } from "@tintinweb/pi-subagents/src/index.ts";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { loadSettings } from "@tintinweb/pi-subagents/src/settings.ts";
+import registerSubagents from "@tintinweb/pi-subagents/src/index.ts";
+
+type RawSettings = Record<string, unknown>;
+
+function readGlobalSettings(path: string): RawSettings | undefined {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+    return parsed as RawSettings;
+  } catch {
+    // Leave malformed user files untouched; pi-subagents reports them itself.
+    return undefined;
+  }
+}
+
+/**
+ * 1st-pi ships `@quintinshaw/pi-dynamic-workflows` as the sole `workflow`
+ * owner. When `workflowsEnabled` is unset, pi-subagents auto-detects that tool,
+ * stands down, and warns on every startup (tintinweb/pi-subagents#283). Pin the
+ * same outcome globally so the warning disappears, but only when neither the
+ * global nor the project settings already contain an explicit choice.
+ */
+export function applySubagentsPresetDefaults(cwd: string): void {
+  if (typeof loadSettings(cwd).workflowsEnabled === "boolean") return;
+
+  const path = join(getAgentDir(), "subagents.json");
+  const settings = readGlobalSettings(path);
+  if (!settings) return;
+
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({ ...settings, workflowsEnabled: false }, null, 2)}\n`, "utf-8");
+  } catch {
+    // Non-fatal: pi-subagents still stands down automatically, just with a warning.
+  }
+}
+
+export default function subagentsAdapter(...args: Parameters<typeof registerSubagents>): ReturnType<typeof registerSubagents> {
+  applySubagentsPresetDefaults(process.cwd());
+  return registerSubagents(...args);
+}

package/extensions/packages/tool-registration-transform.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type RegisteredTool = Parameters<ExtensionAPI["registerTool"]>[0];
+
+export function registerWithToolTransform(
+  pi: ExtensionAPI,
+  register: (api: ExtensionAPI) => void,
+  transform: (tool: RegisteredTool) => RegisteredTool,
+): void {
+  const originalRegisterTool = pi.registerTool;
+  pi.registerTool = ((tool: RegisteredTool) => {
+    originalRegisterTool.call(pi, transform(tool));
+  }) as ExtensionAPI["registerTool"];
+
+  try {
+    register(pi);
+  } finally {
+    pi.registerTool = originalRegisterTool;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1st-pi",
-  "version": "0.1.1",
+  "version": "0.3.2",
   "description": "est7's Pi coding agent preset — skills, extensions, prompts, and themes.",
   "license": "MIT",
   "author": "est7",
@@ -32,21 +32,19 @@
   },
   "homepage": "https://github.com/est7/1st-pi#readme",
   "dependencies": {
-    "@ff-labs/pi-fff": "^0.9.6",
-    "@juicesharp/rpiv-ask-user-question": "^1.20.0",
-    "@mrclrchtr/supi-context": "^2.4.0",
-    "@narumitw/pi-goal": "^0.15.1",
-    "@quintinshaw/pi-dynamic-workflows": "^2.13.1",
-    "@tintinweb/pi-subagents": "^0.14.1",
-    "@tintinweb/pi-tasks": "^0.7.1",
-    "pi-btw": "^0.4.1",
-    "pi-everforest-tui": "^0.2.0",
+    "@ff-labs/pi-fff": "^0.11.0",
+    "@juicesharp/rpiv-ask-user-question": "^2.12.0",
+    "@mrclrchtr/supi-context": "^8.0.1",
+    "@narumitw/pi-goal": "^0.54.11",
+    "@quintinshaw/pi-dynamic-workflows": "^3.14.0",
+    "@tintinweb/pi-subagents": "^0.20.0",
+    "@tintinweb/pi-tasks": "^0.9.0",
+    "pi-btw": "^0.7.1",
+    "pi-everforest-tui": "^0.2.1",
     "pi-init": "^1.0.0",
-    "pi-mcp-adapter": "^2.11.0",
-    "pi-observational-memory": "^3.0.3",
-    "pi-readseek": "^0.6.6",
-    "pi-session-name": "^0.1.2",
-    "pi-web-access": "^0.13.0"
+    "pi-readseek": "^0.10.4",
+    "pi-session-name": "^0.1.7",
+    "pi-web-access": "^0.38.0"
   },
   "scripts": {
     "sync:resources": "node scripts/sync-package-resources.mjs",
@@ -55,8 +53,8 @@
     "pack:dry-run": "npm pack --dry-run --json"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "@earendil-works/pi-tui": ">=1.1.0"
   },
   "pi": {
     "extensions": [
@@ -66,13 +64,11 @@
       "./extensions/custom-header.ts",
       "./extensions/packages/ask-user.ts",
       "./extensions/packages/goal.ts",
-      "./extensions/packages/observational-memory.ts",
       "./extensions/packages/fff.ts",
       "./extensions/packages/readseek.ts",
       "./extensions/packages/btw.ts",
       "./extensions/packages/supi-context.ts",
       "./extensions/packages/web-access.ts",
-      "./extensions/packages/mcp-adapter.ts",
       "./extensions/packages/session-name.ts",
       "./extensions/packages/tasks.ts",
       "./extensions/packages/subagents.ts"

package/extensions/packages/mcp-adapter.ts

@@ -1 +0,0 @@
-export { default } from "pi-mcp-adapter/index.ts";

package/extensions/packages/observational-memory.ts

@@ -1 +0,0 @@
-export { default } from "pi-observational-memory/src/index.ts";

package/skills/librarian/SKILL.md

@@ -1,195 +0,0 @@
----
-name: librarian
-description: Research open-source libraries with evidence-backed answers and GitHub permalinks. Use when the user asks about library internals, needs implementation details with source code references, wants to understand why something was changed, or needs authoritative answers backed by actual code. Excels at navigating large open-source repos and providing citations to exact lines of code.
----
-
-# Librarian
-
-Answer questions about open-source libraries by finding evidence with GitHub permalinks. Every claim backed by actual code.
-
-## Execution Model
-
-Pi executes tool calls sequentially, even when you emit multiple calls in one turn. But batching independent calls in a single turn still saves LLM round-trips (~5-10s each). Use these patterns:
-
-| Pattern | When | Actually parallel? |
-|---------|------|-------------------|
-| Batch tool calls in one turn | Independent ops (web_search + fetch_content + read) | No, but saves round-trips |
-| `fetch_content({ urls: [...] })` | Multiple URLs to fetch | Yes (3 concurrent) |
-| Bash with `&` + `wait` | Multiple git/gh commands | Yes (OS-level) |
-
-## Step 1: Classify the Request
-
-Before doing anything, classify the request to pick the right research strategy.
-
-| Type | Trigger | Primary Approach |
-|------|---------|-----------------|
-| **Conceptual** | "How do I use X?", "Best practice for Y?" | web_search + fetch_content (README/docs) |
-| **Implementation** | "How does X implement Y?", "Show me the source" | fetch_content (clone) + code search |
-| **Context/History** | "Why was this changed?", "History of X?" | git log + git blame + issue/PR search |
-| **Comprehensive** | Complex or ambiguous requests, "deep dive" | All of the above |
-
-## Step 2: Research by Type
-
-### Conceptual Questions
-
-Batch these in one turn:
-
-1. **web_search**: `"library-name topic"` via Perplexity for recent articles and discussions
-2. **fetch_content**: the library's GitHub repo URL to clone and check README, docs, or examples
-
-Synthesize web results + repo docs. Cite official documentation and link to relevant source files.
-
-### Implementation Questions
-
-The core workflow -- clone, find, permalink:
-
-1. **fetch_content** the GitHub repo URL -- this clones it locally and returns the file tree
-2. Use **bash** to search the cloned repo: `grep -rn "function_name"`, `find . -name "*.ts"`
-3. Use **read** to examine specific files once you've located them
-4. Get the commit SHA: `cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD`
-5. Construct permalink: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`
-
-Batch the initial calls: fetch_content (clone) + web_search (recent discussions) in one turn. Then dig into the clone with grep/read once it's available.
-
-### Context/History Questions
-
-Use git operations on the cloned repo:
-
-```bash
-cd /tmp/pi-github-repos/owner/repo
-
-# Recent changes to a specific file
-git log --oneline -n 20 -- path/to/file.ts
-
-# Who changed what and when
-git blame -L 10,30 path/to/file.ts
-
-# Full diff for a specific commit
-git show <sha> -- path/to/file.ts
-
-# Search commit messages
-git log --oneline --grep="keyword" -n 10
-```
-
-For issues and PRs, use bash:
-
-```bash
-# Search issues
-gh search issues "keyword" --repo owner/repo --state all --limit 10
-
-# Search merged PRs
-gh search prs "keyword" --repo owner/repo --state merged --limit 10
-
-# View specific issue/PR with comments
-gh issue view <number> --repo owner/repo --comments
-gh pr view <number> --repo owner/repo --comments
-
-# Release notes
-gh api repos/owner/repo/releases --jq '.[0:5] | .[].tag_name'
-```
-
-### Comprehensive Research
-
-Combine everything. Batch these in one turn:
-
-1. **web_search**: recent articles and discussions
-2. **fetch_content**: clone the repo (or multiple repos if comparing)
-3. **bash**: `gh search issues "keyword" --repo owner/repo --limit 10 & gh search prs "keyword" --repo owner/repo --state merged --limit 10 & wait`
-
-Then dig into the clone with grep, read, git blame, git log as needed.
-
-## Step 3: Construct Permalinks
-
-Permalinks are the whole point. They make your answers citable and verifiable.
-
-```
-https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>
-```
-
-Getting the SHA from a cloned repo:
-
-```bash
-cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD
-```
-
-Getting the SHA from a tag:
-
-```bash
-gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'
-```
-
-Always use full commit SHAs, not branch names. Branch links break when code changes. Permalinks don't.
-
-## Step 4: Cite Everything
-
-Every code-related claim needs a permalink. Format:
-
-```markdown
-The stale time check happens in [`notifyManager.ts`](https://github.com/TanStack/query/blob/abc123/packages/query-core/src/notifyManager.ts#L42-L50):
-
-\`\`\`typescript
-function isStale(query: Query, staleTime: number): boolean {
-  return query.state.dataUpdatedAt + staleTime < Date.now()
-}
-\`\`\`
-```
-
-For conceptual answers, link to official docs and relevant source files. For implementation answers, every function/class reference should have a permalink.
-
-## Video Analysis
-
-For questions about video tutorials, conference talks, or screen recordings:
-
-```typescript
-// Full extraction (transcript + visual descriptions)
-fetch_content({ url: "https://youtube.com/watch?v=abc" })
-
-// Ask a specific question about a video
-fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are imported in this tutorial?" })
-
-// Single frame at a known moment
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41" })
-
-// Range scan for visual discovery
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00" })
-
-// Custom density across a range
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 3 })
-
-// Whole-video sampling
-fetch_content({ url: "https://youtube.com/watch?v=abc", frames: 6 })
-
-// Analyze a local recording
-fetch_content({ url: "/path/to/demo.mp4", prompt: "What error message appears on screen?" })
-
-// Batch multiple videos with the same question
-fetch_content({
-  urls: ["https://youtube.com/watch?v=abc", "https://youtube.com/watch?v=def"],
-  prompt: "What packages are installed?"
-})
-```
-
-Use single timestamps for known moments, ranges for visual scanning, and frames-alone for a quick overview of the whole video.
-
-The `prompt` parameter only applies to video content (YouTube URLs and local video files). For non-video URLs, it's ignored.
-
-## Failure Recovery
-
-| Failure | Recovery |
-|---------|----------|
-| grep finds nothing | Broaden the query, try concept names instead of exact function names |
-| gh CLI rate limited | Use the already-cloned repo in /tmp/pi-github-repos/ for git operations |
-| Repo too large to clone | fetch_content returns an API-only view automatically; use that or add `forceClone: true` |
-| File not found in clone | Branch name with slashes may have misresolved; list the repo tree and navigate manually |
-| Uncertain about implementation | State your uncertainty explicitly, propose a hypothesis, show what evidence you did find |
-| Video extraction fails | Ensure Chrome is signed into gemini.google.com (free) or set GEMINI_API_KEY |
-| Page returns 403/bot block | Gemini fallback triggers automatically; no action needed if Gemini is configured |
-| web_search fails | Check provider config; try explicit `provider: "gemini"` if Perplexity key is missing |
-
-## Guidelines
-
-- Vary search queries when running multiple searches -- different angles, not the same pattern repeated
-- Prefer recent sources; filter out outdated results when they conflict with newer information
-- For version-specific questions, clone the tagged version: `fetch_content("https://github.com/owner/repo/tree/v1.0.0")`
-- When the repo is already cloned from a previous fetch_content call, reuse it -- check the path before cloning again
-- Answer directly. Skip preamble like "I'll help you with..." -- go straight to findings