@lincoln504/pi-research 1.7.0 → 1.7.2

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.7.0", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/agent-skill/pi-research/references/configuration.md

@@ -27,7 +27,7 @@ over `config.env` for the CLI only. Precedence:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PI_RESEARCH_MODEL` | _(required)_ | The `provider/model-id` all research runs on. |
-| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (0–3) when `--depth` omitted. `0` is quick (single-pass, no researcher team) and requires `PI_RESEARCH_QUICK_RESEARCH` on the pi extension. |
+| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (0–3) when `--depth` omitted. `0` is quick (single-pass, no researcher team) and requires `PI_RESEARCH_QUICK_RESEARCH` on the pi extension. The agent-facing `research` tool's depth guidance renders relative to this setting — when quick is the configured default, depth 0 is the ordinary choice and 1+ is the escalation; keeping the default (1) renders byte-identically. |
 | `PI_RESEARCH_QUICK_MAX_QUERIES` | `5` | Max queries per `search` call in quick (depth 0) research (1–10). Applies to the CLI and SDK `--depth 0` runs too. |
 | `PI_RESEARCH_MAX_RESEARCHERS` | `3` | Parallel researchers (1–5). |
 | `PI_RESEARCH_TIMEOUT_MS` | `300000` | Per-researcher timeout (180000–1800000). |

package/dist/cli.mjs

@@ -18704,6 +18704,7 @@ var BOT_PATTERNS = [
 ];
 var IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
 var MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+var EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
 
 // src/web-research/types.ts
 var FETCH_LAYER_TIMEOUT = 1e4;
@@ -18924,6 +18925,51 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+var FRONT_MATTER_SLOTS = [
+  ["title", "meta-og:title", "meta-citation_title"],
+  ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+  ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+  [
+    "meta-article:published_time",
+    "meta-citation_publication_date",
+    "meta-citation_date",
+    "meta-dcterms.date",
+    "meta-dc.date",
+    "meta-date",
+    "meta-dcterms.created"
+  ],
+  ["meta-article:modified_time", "meta-dcterms.modified"]
+];
+var MAX_FRONT_MATTER_CHARS = 2e4;
+var FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -18937,7 +18983,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -18948,7 +18994,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {

package/dist/prompts/research-depth-guidance.ts

@@ -0,0 +1,159 @@
+/**
+ * Renders the DEPTH PARAMETER guidance for the agent-facing `research` tool,
+ * relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.
+ *
+ * Background (PR #16, discussion point 2): the tool-usage prompt says
+ * "Always specify a depth" and mapped ~95% of queries to `depth: 1`, so a
+ * user-configured default (e.g. quick/0) was effectively never honored for
+ * agent-initiated research — even with quick set as the default the agent
+ * still sent `depth: 1`. This builder renders the guidance relative to the
+ * configured default: when quick is the configured default, depth 0 becomes
+ * the ordinary choice and depth 1+ reads as the escalation. A user who keeps
+ * the default (1) sees byte-identical guidance — quality-first behavior is
+ * unchanged.
+ *
+ * The anchor is the *effective* default — the depth `execute()` actually
+ * resolves an omitted depth to:
+ *
+ *     effectiveDefault = quickEnabled ? defaultDepth : Math.max(1, defaultDepth)
+ *
+ * Depth 0 is only reachable when quick mode is enabled; otherwise a
+ * configured 0 clamps to 1 at runtime, so the guidance must not advertise it.
+ *
+ * This is a pure function of the two session-static snapshots the tool schema
+ * was built from (see quickResearchEnabledAtRegistration /
+ * defaultDepthAtRegistration in index.ts) so the rendered guidance can never
+ * advertise a depth the registered schema rejects.
+ */
+
+/**
+ * The depth `execute()` applies when the agent omits depth — `Math.max(depthMin,
+ * configured)` where `depthMin = quickEnabled ? 0 : 1` (see
+ * research-tool-definition.ts). This is "the ordinary choice" every rendered
+ * surface steers to, and the value the tool schema's `default` annotation must
+ * match.
+ */
+export function resolveEffectiveDefault(quickEnabled: boolean, defaultDepth: number): number {
+  return quickEnabled ? defaultDepth : Math.max(1, defaultDepth);
+}
+
+/**
+ * Build the DEPTH PARAMETER guidance block (everything between the
+ * "Always specify a depth." lead-in and the "How depth works internally:"
+ * section). The returned string has no leading or trailing newlines; the
+ * caller's template supplies the surrounding blank lines.
+ *
+ * @param quickEnabled Whether quick mode (depth 0) is enabled — the same
+ *   session-static snapshot the tool schema was built from.
+ * @param defaultDepth The user-configured `DEFAULT_RESEARCH_DEPTH` (0–3).
+ */
+export function buildResearchDepthGuidance(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+
+  if (!quickEnabled) {
+    return wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+  }
+  return quickDoc(effectiveDefault) + '\n' + wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+}
+
+/**
+ * The "user says a depth word" mapping. Byte-identical for effectiveDefault in
+ * {1,2,3}; only the "quick" line moves — to 0 — when the configured default IS
+ * 0. "normal" stays 1: the words form a shallow→max scale
+ * (quick < normal < deep < ultra = 0 < 1 < 2 < 3), so "normal" is always the
+ * standard orchestrated run.
+ */
+function wordBlock(effectiveDefault: number): string {
+  const quickTarget = effectiveDefault === 0 ? 0 : 1;
+  return [
+    '**User says a depth word (highest priority):**',
+    '- "quick" / "brief" / "simple" → `depth: ' + quickTarget + '`',
+    '- "normal" / "moderate" / "standard" → `depth: 1`',
+    '- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)',
+    '- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`',
+  ].join('\n');
+}
+
+/**
+ * The "user says nothing about depth — judge complexity:" section. Positions
+ * the effective default as the ordinary choice. effectiveDefault === 1
+ * reproduces the prior static text byte-for-byte.
+ */
+function nothingBlock(effectiveDefault: number): string {
+  const header = '**User says nothing about depth — judge complexity:**';
+  const never = '- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research".';
+  switch (effectiveDefault) {
+    case 0:
+      return [
+        header,
+        '- `depth: 0` — the ordinary choice: a single verifiable fact, a URL, a price, a version number, or a yes/no with a source. One search-and-read pass, no researcher team.',
+        '- `depth: 1` — Coordinated, thorough research: simple facts with sources, lookups, overviews, background research. Escalate here when the question needs more than a single verifiable fact.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 0, 1, or 2.',
+      ].join('\n');
+    case 2:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — the ordinary choice (your configured default): complex multi-faceted topics, policy analysis, tech evaluations, academic-style research.',
+        never,
+      ].join('\n');
+    case 3:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        '- `depth: 3` — the ordinary choice (your configured default): comprehensive, multi-round, exhaustive research.',
+      ].join('\n');
+    case 1:
+    default:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 1 or depth 2.',
+      ].join('\n');
+  }
+}
+
+/**
+ * The quick-mode intro, rendered only when quick mode is enabled. The first
+ * paragraph (what depth 0 is) is constant; the second names the ordinary
+ * choice, relative to the effective default.
+ */
+function quickDoc(effectiveDefault: number): string {
+  const first =
+    '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.';
+  let second: string;
+  switch (effectiveDefault) {
+    case 0:
+      second = '`depth: 0` is the ordinary choice; `depth: 1` is the escalation for coordinated research, `depth: 2` for complex or multi-faceted topics, `depth: 3` only on explicit request.';
+      break;
+    case 2:
+      second = '`depth: 2` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 3` only on explicit request.';
+      break;
+    case 3:
+      second = '`depth: 3` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 2` for complex topics.';
+      break;
+    case 1:
+    default:
+      second = '`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.';
+      break;
+  }
+  return first + '\n\n' + second;
+}
+
+/**
+ * The closing escalation nudge — the tail of the "Do NOT escalate depth just
+ * because a topic is broad" line in the MULTIPLE RESEARCH CALLS section,
+ * rendered relative to the effective default the same way the DEPTH PARAMETER
+ * block is. effectiveDefault === 1 reproduces the prior static text
+ * byte-for-byte, so a user who keeps the default (1) — quick on or off — sees
+ * an unchanged prompt.
+ */
+export function buildEscalationNudge(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+  return effectiveDefault === 1
+    ? 'depth 1 handles most cases well, and the higher depths have their own internal decomposition.'
+    : 'your configured default handles most cases well, and the higher depths have their own internal decomposition.';
+}

package/dist/prompts/research-tool-usage.md

@@ -49,17 +49,7 @@ The `research` tool retrieves from the internet. Do NOT use it when the answer c
 
 **Always specify a depth.** Judge it from the user's language and task complexity.
 
-{{QUICK_MODE_DOC}}
-**User says a depth word (highest priority):**
-- "quick" / "brief" / "simple" → `depth: 1`
-- "normal" / "moderate" / "standard" → `depth: 1`
-- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)
-- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`
-
-**User says nothing about depth — judge complexity:**
-- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.
-- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.
-- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research". If the user does not explicitly request this level, use depth 1 or depth 2.
+{{DEPTH_GUIDANCE}}
 
 **How depth works internally:**
 - `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, a research lead decides whether to continue deeper and writes the final report. Team size and number of rounds scale with complexity. The coordinator and the lead dynamically determine how many researchers are needed each round — it's not a fixed number.
@@ -92,4 +82,4 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.
 
-**Do NOT escalate depth just because a topic is broad** — depth 1 handles most cases well, and the higher depths have their own internal decomposition.
+**Do NOT escalate depth just because a topic is broad** — {{ESCALATION_NUDGE}}

package/dist/thread-worker.mjs

@@ -149,7 +149,7 @@ var init_user_agent = __esm({
 });
 
 // src/web-research/scraper-types.ts
-var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN;
+var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN, EMPTY_FRAGMENT_LINK_PATTERN;
 var init_scraper_types = __esm({
   "src/web-research/scraper-types.ts"() {
     "use strict";
@@ -215,6 +215,7 @@ var init_scraper_types = __esm({
     ];
     IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
     MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+    EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
   }
 });
 
@@ -1559,6 +1560,7 @@ var init_browser_error_utils = __esm({
 // src/web-research/scraper-utils.ts
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
+  cleanConvertedMarkdown: () => cleanConvertedMarkdown,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1569,7 +1571,9 @@ __export(scraper_utils_exports, {
   isBenignScrapeFailure: () => isBenignScrapeFailure,
   isSsrfBlockError: () => isSsrfBlockError,
   ssrfSafeLookup: () => ssrfSafeLookup,
+  stripEmptyFragmentLinks: () => stripEmptyFragmentLinks,
   stripImageLinks: () => stripImageLinks,
+  trimFrontMatter: () => trimFrontMatter,
   validateContent: () => validateContent,
   validateUrlForSSRF: () => validateUrlForSSRF,
   validateUrlForSSRFSync: () => validateUrlForSSRFSync
@@ -1785,6 +1789,34 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -1798,7 +1830,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -1809,7 +1841,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {
@@ -1848,7 +1880,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1858,6 +1890,23 @@ var init_scraper_utils = __esm({
     init_scraper_types();
     init_browser_error_utils();
     cachedSsrfFetcher = void 0;
+    FRONT_MATTER_SLOTS = [
+      ["title", "meta-og:title", "meta-citation_title"],
+      ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+      ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+      [
+        "meta-article:published_time",
+        "meta-citation_publication_date",
+        "meta-citation_date",
+        "meta-dcterms.date",
+        "meta-dc.date",
+        "meta-date",
+        "meta-dcterms.created"
+      ],
+      ["meta-article:modified_time", "meta-dcterms.modified"]
+    ];
+    MAX_FRONT_MATTER_CHARS = 2e4;
+    FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
   }
 });
 

package/docs/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.2] - 2026-09-27
+
+### Changed
+
+- **Scraped pages keep only the useful part of the converter's front matter.** The native converter turns every `<meta>` tag into a front-matter line: 54 lines on a GitHub page (analytics and error-reporting URLs, verification hashes, nonces, app ids), and on arXiv the abstract three times over. Nothing parses these lines; researchers read them and the knowledge store indexes them. `trimFrontMatter` (`src/web-research/scraper-utils.ts`) now keeps the title, description, author and publication/modification dates (first key present per slot: plain, Open Graph, citation or Dublin Core names) and drops the rest; a page with none of them loses the block. GitHub pages shrink by about 11%, arXiv abstract pages by about a third. Side effect: an empty page shell whose front matter alone used to pass the stub check is now treated as a stub, so the browser fallback gets a chance.
+- **Scraped pages no longer carry empty same-page links.** Documentation generators such as Quarto and nbdev put an empty anchor before every code line (`<a href="#cb2-1"></a>`) and next to headings; the native HTML→Markdown converter turned each into `[](#cb2-1)`, so every code block in a research scrape (and in the knowledge store) started each line with one. Both converters now drop links that have no text and point to the same page (`cleanConvertedMarkdown` in `src/web-research/scraper-utils.ts`, run after the existing image-link stripping so heading anchors that wrap an icon — GitHub's `[![](link.svg)](#title)` — go too). Links with text, and empty links to other pages, are kept. On an nbdev documentation page (fastcore.fast.ai/docments.html) this removes 583 such links, 16% of the scraped text.
+
+## [1.7.1] - 2026-09-27
+
+### Changed
+
+- **The remaining static `depth: 1` references in the agent-facing surface now follow the configured default too.** Two spots still said `1` where the runtime applies the configured default: the tool schema's model-facing `default` annotation on the `depth` parameter (hardcoded `default: 1`, so a user who configured default 2 saw `"default": 1` in the schema while the prompt said depth 2 is the ordinary choice), and the closing "Do NOT escalate depth just because a topic is broad" line ("depth 1 handles most cases well"). Both are now rendered against the same effective default the DEPTH PARAMETER block uses — `Math.max(depthMin, configured)` where `depthMin = quickEnabled ? 0 : 1` — via `resolveEffectiveDefault` / `buildEscalationNudge` in `src/prompts/research-depth-guidance.ts`. A user whose effective default is 1 (the default install, quick on or off) sees byte-identical prompt and schema; the tests pin that.
+- **The agent-facing `research` tool-usage prompt now renders its depth guidance relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.** The DEPTH PARAMETER block was static and always steered to `depth: 1` — the "Always specify a depth" prompt mapped ~95% of queries there — so a user-configured default (e.g. quick/0) was effectively never honored for agent-initiated research: even with quick set as the default the agent still sent `depth: 1` (only `/research` and the CLI honored it). The block is now rendered by `buildResearchDepthGuidance` (new `src/prompts/research-depth-guidance.ts`) against the same session-static snapshots the tool schema is built from, so it can never advertise a depth the registered schema rejects. When quick is the configured default, depth 0 becomes the ordinary choice and depth 1+ reads as the escalation — a real cost lever. A user who keeps the default (1) sees **byte-identical** guidance, for both the quick-on and quick-off renderings (the green-light condition on PR #16); `test/unit/prompts/research-depth-guidance.test.ts` pins that byte-identity and the `effectiveDefault` the guidance anchors on (`quickEnabled ? defaultDepth : max(1, defaultDepth)`, the depth `execute()` applies to an omitted depth).
+
 ## [1.7.0] - 2026-09-22
 
 ### Added

package/docs/CONFIGURATION.md

@@ -73,7 +73,7 @@ Research
 |----------|---------|-------|-------------|
 | `PI_RESEARCH_TIMEOUT_MS` (TUI) | `300000` | 180000–1800000 | Per-researcher timeout (3–30 min). |
 | `PI_RESEARCH_MAX_RESEARCHERS` (TUI) | `3` | 1–5 | Parallel researchers. |
-| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` (TUI) `[project]` | `1` | 0–3 | Depth for `/research` and the CLI when `--depth` is omitted (0=quick single-pass — requires `PI_RESEARCH_QUICK_RESEARCH` —, 1=normal, 2=deep, 3=ultra). |
+| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` (TUI) `[project]` | `1` | 0–3 | Depth for `/research` and the CLI when `--depth` is omitted (0=quick single-pass — requires `PI_RESEARCH_QUICK_RESEARCH` —, 1=normal, 2=deep, 3=ultra). The agent-facing `research` tool-usage prompt renders its depth guidance relative to this setting too: when quick is the configured default, depth 0 is the ordinary choice; a user who keeps the default (1) gets byte-identical guidance. |
 | `PI_RESEARCH_QUICK_RESEARCH` (TUI) `[project]` | `false` | `true` · `false` | Opt-in gate for depth-0 (quick) research. When `false` (default), the agent-facing `research` tool keeps its upstream `minimum: 1` schema — agents can neither see nor send depth 0 — and a `DEFAULT_RESEARCH_DEPTH` of 0 resolves to 1. Toggling applies on the next session. |
 | `PI_RESEARCH_QUICK_MAX_QUERIES` | `5` | 1–10 | Max queries per `search` call in quick (depth 0) research. Applies to every quick run — the pi extension tool, the CLI, and the SDK's `--depth 0` — since they share the same researcher session factory. Deliberately below deep research's 30-query cap; the ceiling of 10 keeps quick mode from ever exceeding the old 5–10 prompt guidance. |
 | `PI_RESEARCH_MAX_SCRAPE_BATCHES` (TUI) | `2` | 0–99 | Scrape batches per researcher (0 = unlimited). When prompt caching is known to be active for the resolved research model (Anthropic API models, or a provider route explicitly configured for Anthropic-style cache control), the effective limit is this value plus one — the cached prompt prefix makes the extra batch cheap. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/index.ts

@@ -20,6 +20,7 @@ import { getConfig, validateConfig } from './config.ts';
 import { metrics } from './utils/metrics.ts';
 import { handleResearchConfigCommand } from './research-config.ts';
 import { loadPrompt } from './core/llm/prompts.ts';
+import { buildResearchDepthGuidance, buildEscalationNudge } from './prompts/research-depth-guidance.ts';
 import { clearAllSessionState, addSteeringMessage, getSteeringMessages, normalizeSessionId, getActiveSessionCount, popQueuedMessages, requeuePoppedMessage, getAllTrackedSessions, getPiActiveSessionOrder, getPiActivePanels } from './orchestration/session-state.ts';
 import { initGlobalTuiController, disposeGlobalTuiController } from './tui/tui-controller.ts';
 import { registerCoreServices, initializeCoreServices, disposeCoreServices } from './core/service-initialization.ts';
@@ -332,6 +333,10 @@ export default async function (pi: ExtensionAPI) {
   // live config here would tell the agent depth 0 exists while the tool still
   // rejects it with invalid_parameters until restart.
   const quickResearchEnabledAtRegistration = getConfig(process.cwd(), 'pi').QUICK_RESEARCH === true;
+  // Session-static snapshot of the user's configured DEFAULT_RESEARCH_DEPTH, taken
+  // at the same moment as quickResearchEnabledAtRegistration so the depth guidance
+  // (rendered relative to it) agrees with the schema the session was built with.
+  const defaultDepthAtRegistration = getConfig(process.cwd(), 'pi').DEFAULT_RESEARCH_DEPTH;
 
   // Create and register the health check tool
   const healthTool: ToolDefinition = createHealthTool();
@@ -612,17 +617,16 @@ export default async function (pi: ExtensionAPI) {
       (!event.systemPromptOptions || event.systemPromptOptions.selectedTools?.includes(researchKnowledgeSearchTool.name));
 
     if (isResearchToolAvailable || isKnowledgeSearchAvailable) {
-      // Quick-mode (depth 0) prompt documentation is gated on the SAME session-
-      // static snapshot the tool schema was built from (see
-      // quickResearchEnabledAtRegistration) — not live config — so the prompt can
-      // never advertise a depth the registered schema rejects. A mid-session
-      // QUICK_RESEARCH toggle therefore fully applies on the next session, both
-      // schema and prompt together.
-      const quickModeDoc = quickResearchEnabledAtRegistration
-        ? '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.\n\n`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.\n'
-        : '';
+      // The DEPTH PARAMETER guidance is rendered relative to the user's configured
+      // DEFAULT_RESEARCH_DEPTH (buildResearchDepthGuidance), gated on the SAME
+      // session-static snapshots the tool schema was built from (see
+      // quickResearchEnabledAtRegistration / defaultDepthAtRegistration) — not live
+      // config — so the prompt can never advertise a depth the registered schema
+      // rejects. A mid-session config toggle therefore fully applies on the next
+      // session, both schema and prompt together.
       let researchPrompt = loadPrompt('research-tool-usage')
-        .replace(/\n?\{\{QUICK_MODE_DOC\}\}\n?/, '\n' + quickModeDoc)
+        .replace('{{DEPTH_GUIDANCE}}', buildResearchDepthGuidance(quickResearchEnabledAtRegistration, defaultDepthAtRegistration))
+        .replace('{{ESCALATION_NUDGE}}', buildEscalationNudge(quickResearchEnabledAtRegistration, defaultDepthAtRegistration))
         .replace('{{max_team_size_l1}}', MAX_TEAM_SIZE_LEVEL_1.toString())
         .replace('{{max_team_size_l2}}', MAX_TEAM_SIZE_LEVEL_2.toString())
         .replace('{{max_team_size_l3}}', MAX_TEAM_SIZE_LEVEL_3.toString());

package/src/infrastructure/browser/thread-worker.mjs

@@ -149,7 +149,7 @@ var init_user_agent = __esm({
 });
 
 // src/web-research/scraper-types.ts
-var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN;
+var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN, EMPTY_FRAGMENT_LINK_PATTERN;
 var init_scraper_types = __esm({
   "src/web-research/scraper-types.ts"() {
     "use strict";
@@ -215,6 +215,7 @@ var init_scraper_types = __esm({
     ];
     IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
     MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+    EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
   }
 });
 
@@ -1559,6 +1560,7 @@ var init_browser_error_utils = __esm({
 // src/web-research/scraper-utils.ts
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
+  cleanConvertedMarkdown: () => cleanConvertedMarkdown,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1569,7 +1571,9 @@ __export(scraper_utils_exports, {
   isBenignScrapeFailure: () => isBenignScrapeFailure,
   isSsrfBlockError: () => isSsrfBlockError,
   ssrfSafeLookup: () => ssrfSafeLookup,
+  stripEmptyFragmentLinks: () => stripEmptyFragmentLinks,
   stripImageLinks: () => stripImageLinks,
+  trimFrontMatter: () => trimFrontMatter,
   validateContent: () => validateContent,
   validateUrlForSSRF: () => validateUrlForSSRF,
   validateUrlForSSRFSync: () => validateUrlForSSRFSync
@@ -1785,6 +1789,34 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -1798,7 +1830,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -1809,7 +1841,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {
@@ -1848,7 +1880,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1858,6 +1890,23 @@ var init_scraper_utils = __esm({
     init_scraper_types();
     init_browser_error_utils();
     cachedSsrfFetcher = void 0;
+    FRONT_MATTER_SLOTS = [
+      ["title", "meta-og:title", "meta-citation_title"],
+      ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+      ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+      [
+        "meta-article:published_time",
+        "meta-citation_publication_date",
+        "meta-citation_date",
+        "meta-dcterms.date",
+        "meta-dc.date",
+        "meta-date",
+        "meta-dcterms.created"
+      ],
+      ["meta-article:modified_time", "meta-dcterms.modified"]
+    ];
+    MAX_FRONT_MATTER_CHARS = 2e4;
+    FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
   }
 });
 

package/src/prompts/research-depth-guidance.ts

@@ -0,0 +1,159 @@
+/**
+ * Renders the DEPTH PARAMETER guidance for the agent-facing `research` tool,
+ * relative to the user's configured `DEFAULT_RESEARCH_DEPTH`.
+ *
+ * Background (PR #16, discussion point 2): the tool-usage prompt says
+ * "Always specify a depth" and mapped ~95% of queries to `depth: 1`, so a
+ * user-configured default (e.g. quick/0) was effectively never honored for
+ * agent-initiated research — even with quick set as the default the agent
+ * still sent `depth: 1`. This builder renders the guidance relative to the
+ * configured default: when quick is the configured default, depth 0 becomes
+ * the ordinary choice and depth 1+ reads as the escalation. A user who keeps
+ * the default (1) sees byte-identical guidance — quality-first behavior is
+ * unchanged.
+ *
+ * The anchor is the *effective* default — the depth `execute()` actually
+ * resolves an omitted depth to:
+ *
+ *     effectiveDefault = quickEnabled ? defaultDepth : Math.max(1, defaultDepth)
+ *
+ * Depth 0 is only reachable when quick mode is enabled; otherwise a
+ * configured 0 clamps to 1 at runtime, so the guidance must not advertise it.
+ *
+ * This is a pure function of the two session-static snapshots the tool schema
+ * was built from (see quickResearchEnabledAtRegistration /
+ * defaultDepthAtRegistration in index.ts) so the rendered guidance can never
+ * advertise a depth the registered schema rejects.
+ */
+
+/**
+ * The depth `execute()` applies when the agent omits depth — `Math.max(depthMin,
+ * configured)` where `depthMin = quickEnabled ? 0 : 1` (see
+ * research-tool-definition.ts). This is "the ordinary choice" every rendered
+ * surface steers to, and the value the tool schema's `default` annotation must
+ * match.
+ */
+export function resolveEffectiveDefault(quickEnabled: boolean, defaultDepth: number): number {
+  return quickEnabled ? defaultDepth : Math.max(1, defaultDepth);
+}
+
+/**
+ * Build the DEPTH PARAMETER guidance block (everything between the
+ * "Always specify a depth." lead-in and the "How depth works internally:"
+ * section). The returned string has no leading or trailing newlines; the
+ * caller's template supplies the surrounding blank lines.
+ *
+ * @param quickEnabled Whether quick mode (depth 0) is enabled — the same
+ *   session-static snapshot the tool schema was built from.
+ * @param defaultDepth The user-configured `DEFAULT_RESEARCH_DEPTH` (0–3).
+ */
+export function buildResearchDepthGuidance(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+
+  if (!quickEnabled) {
+    return wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+  }
+  return quickDoc(effectiveDefault) + '\n' + wordBlock(effectiveDefault) + '\n\n' + nothingBlock(effectiveDefault);
+}
+
+/**
+ * The "user says a depth word" mapping. Byte-identical for effectiveDefault in
+ * {1,2,3}; only the "quick" line moves — to 0 — when the configured default IS
+ * 0. "normal" stays 1: the words form a shallow→max scale
+ * (quick < normal < deep < ultra = 0 < 1 < 2 < 3), so "normal" is always the
+ * standard orchestrated run.
+ */
+function wordBlock(effectiveDefault: number): string {
+  const quickTarget = effectiveDefault === 0 ? 0 : 1;
+  return [
+    '**User says a depth word (highest priority):**',
+    '- "quick" / "brief" / "simple" → `depth: ' + quickTarget + '`',
+    '- "normal" / "moderate" / "standard" → `depth: 1`',
+    '- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)',
+    '- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`',
+  ].join('\n');
+}
+
+/**
+ * The "user says nothing about depth — judge complexity:" section. Positions
+ * the effective default as the ordinary choice. effectiveDefault === 1
+ * reproduces the prior static text byte-for-byte.
+ */
+function nothingBlock(effectiveDefault: number): string {
+  const header = '**User says nothing about depth — judge complexity:**';
+  const never = '- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research".';
+  switch (effectiveDefault) {
+    case 0:
+      return [
+        header,
+        '- `depth: 0` — the ordinary choice: a single verifiable fact, a URL, a price, a version number, or a yes/no with a source. One search-and-read pass, no researcher team.',
+        '- `depth: 1` — Coordinated, thorough research: simple facts with sources, lookups, overviews, background research. Escalate here when the question needs more than a single verifiable fact.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 0, 1, or 2.',
+      ].join('\n');
+    case 2:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — the ordinary choice (your configured default): complex multi-faceted topics, policy analysis, tech evaluations, academic-style research.',
+        never,
+      ].join('\n');
+    case 3:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        '- `depth: 3` — the ordinary choice (your configured default): comprehensive, multi-round, exhaustive research.',
+      ].join('\n');
+    case 1:
+    default:
+      return [
+        header,
+        '- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.',
+        '- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.',
+        never + ' If the user does not explicitly request this level, use depth 1 or depth 2.',
+      ].join('\n');
+  }
+}
+
+/**
+ * The quick-mode intro, rendered only when quick mode is enabled. The first
+ * paragraph (what depth 0 is) is constant; the second names the ordinary
+ * choice, relative to the effective default.
+ */
+function quickDoc(effectiveDefault: number): string {
+  const first =
+    '**Depth 0 (quick) is available on this host.** Use `depth: 0` for a single verifiable fact, a URL, a price, a version number, or a yes/no with a source — or when the user says "just check", "one-liner", or "don\'t overdo it". It runs one search-and-read pass with no researcher team and answers concisely.';
+  let second: string;
+  switch (effectiveDefault) {
+    case 0:
+      second = '`depth: 0` is the ordinary choice; `depth: 1` is the escalation for coordinated research, `depth: 2` for complex or multi-faceted topics, `depth: 3` only on explicit request.';
+      break;
+    case 2:
+      second = '`depth: 2` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 3` only on explicit request.';
+      break;
+    case 3:
+      second = '`depth: 3` is the ordinary choice (your configured default); `depth: 1` for simple lookups, `depth: 2` for complex topics.';
+      break;
+    case 1:
+    default:
+      second = '`depth: 1` remains the normal choice. `depth: 2` is the escalation for complex or multi-faceted questions; `depth: 3` only on explicit request.';
+      break;
+  }
+  return first + '\n\n' + second;
+}
+
+/**
+ * The closing escalation nudge — the tail of the "Do NOT escalate depth just
+ * because a topic is broad" line in the MULTIPLE RESEARCH CALLS section,
+ * rendered relative to the effective default the same way the DEPTH PARAMETER
+ * block is. effectiveDefault === 1 reproduces the prior static text
+ * byte-for-byte, so a user who keeps the default (1) — quick on or off — sees
+ * an unchanged prompt.
+ */
+export function buildEscalationNudge(quickEnabled: boolean, defaultDepth: number): string {
+  const effectiveDefault = resolveEffectiveDefault(quickEnabled, defaultDepth);
+  return effectiveDefault === 1
+    ? 'depth 1 handles most cases well, and the higher depths have their own internal decomposition.'
+    : 'your configured default handles most cases well, and the higher depths have their own internal decomposition.';
+}

package/src/prompts/research-tool-usage.md

@@ -49,17 +49,7 @@ The `research` tool retrieves from the internet. Do NOT use it when the answer c
 
 **Always specify a depth.** Judge it from the user's language and task complexity.
 
-{{QUICK_MODE_DOC}}
-**User says a depth word (highest priority):**
-- "quick" / "brief" / "simple" → `depth: 1`
-- "normal" / "moderate" / "standard" → `depth: 1`
-- "deep" / "thorough" / "in-depth" → `depth: 2` (never depth 3)
-- "ultra" / "exhaustive" / "comprehensive" / "deep-dive" / "maximum" → `depth: 3`
-
-**User says nothing about depth — judge complexity:**
-- `depth: 1` — Simple facts, lookups, news, definitions, "what is X", overviews, background research. This covers ~95%+ of queries.
-- `depth: 2` — Complex multi-faceted topics: policy analysis, tech evaluations, academic-style research.
-- `depth: 3` — **ABSOLUTELY NEVER without explicit user request.** The user MUST use trigger words like "ultra", "exhaustive", "comprehensive deep-dive", or "maximum research". If the user does not explicitly request this level, use depth 1 or depth 2.
+{{DEPTH_GUIDANCE}}
 
 **How depth works internally:**
 - `depth: 1-3` — AI-orchestrated: coordinator plans a team, researchers execute, a research lead decides whether to continue deeper and writes the final report. Team size and number of rounds scale with complexity. The coordinator and the lead dynamically determine how many researchers are needed each round — it's not a fixed number.
@@ -92,4 +82,4 @@ The coordinator will plan as many researchers as needed (up to the max). You do
 - **Group related topics**: If topics share ANY scope or could inform each other, combine them into a single `research` call. The internal coordinator will decompose them into parallel researcher agents. Do NOT split related sub-topics into separate calls.
 - Example: `research("Python async performance and Rust async performance comparison")` — NOT separate calls for Python and Rust, since the comparison IS the research goal.
 
-**Do NOT escalate depth just because a topic is broad** — depth 1 handles most cases well, and the higher depths have their own internal decomposition.
+**Do NOT escalate depth just because a topic is broad** — {{ESCALATION_NUDGE}}

package/src/tools/research-tool-definition.ts

@@ -93,8 +93,16 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
   // a mid-session QUICK_RESEARCH toggle takes effect on the next session. When
   // disabled (the default) the schema is byte-identical to the upstream
   // minimum: 1 surface — agents can neither see nor send depth 0.
-  const quickEnabled = getConfig(undefined, iface).QUICK_RESEARCH === true;
+  const toolConfig = getConfig(undefined, iface);
+  const quickEnabled = toolConfig.QUICK_RESEARCH === true;
   const depthMin = quickEnabled ? 0 : 1;
+  // The depth execute() applies to an omitted depth: Math.max(depthMin,
+  // configured DEFAULT_RESEARCH_DEPTH) — the same value the agent-facing DEPTH
+  // guidance renders relative to (buildResearchDepthGuidance). The annotation
+  // must match it, or a user who configured e.g. default 2 sees `default: 1`
+  // in the model-facing schema while the prompt says "depth 2 is the ordinary
+  // choice (your configured default)".
+  const effectiveDefault = Math.max(depthMin, toolConfig.DEFAULT_RESEARCH_DEPTH);
 
   const parameters = Type.Object({
     query: Type.String({
@@ -110,7 +118,7 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
         '2: Deep (multi-round, exhaustive).',
         '3: Ultra (maximum depth, extreme rigor).',
       ].join('\n'),
-      default: 1,
+      default: effectiveDefault,
     })),
     model: Type.Optional(Type.String({
       description: 'Optional model ID override for coordination.',

package/src/web-research/scraper-types.ts

@@ -54,6 +54,13 @@ export const BOT_PATTERNS: ReadonlyArray<[string, string]> = [
 
 export const IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
 export const MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+/**
+ * `[](#fragment)` — a link with no text to a spot on the same page (optional
+ * title). Documentation generators put one before every code line (Quarto,
+ * nbdev: `<a href="#cb2-1" aria-hidden="true"></a>`) and next to headings; the
+ * converters turn each into `[](#cb2-1)`, which carries no text.
+ */
+export const EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
 
 export type { ScrapeLayerResult } from './types.ts';
 

package/src/web-research/scraper-utils.ts

@@ -15,6 +15,7 @@ import {
   FILTERED_TAGS,
   IMAGE_LINK_PATTERN,
   MARKDOWN_IMAGE_PATTERN,
+  EMPTY_FRAGMENT_LINK_PATTERN,
   BOT_PATTERNS,
   INTERNAL_NETWORK_PATTERNS,
   type NativeHtmlToMarkdownModule,
@@ -485,6 +486,76 @@ function isMappedLoopback(ip: string): boolean {
   return mapped !== null && /^127\./.test(mapped);
 }
 
+/**
+ * Drop empty same-page links (`[](#cb2-1)`): per-line code anchors and heading
+ * anchors that documentation generators emit. They carry no text, but repeat on
+ * every code line and every heading, so they cost tokens and add noise to the
+ * knowledge store index. Links with text, and empty links to other pages, stay.
+ */
+export function stripEmptyFragmentLinks(markdown: string): string {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, '');
+}
+
+/**
+ * Front-matter keys kept by trimFrontMatter, one slot per piece of information;
+ * the first key present in a slot wins (the native converter prefixes <meta>
+ * names with `meta-`, keeping Open Graph / Dublin Core / citation prefixes).
+ */
+const FRONT_MATTER_SLOTS: ReadonlyArray<readonly string[]> = [
+  ['title', 'meta-og:title', 'meta-citation_title'],
+  ['meta-description', 'description', 'meta-og:description', 'meta-twitter:description'],
+  ['meta-author', 'meta-article:author', 'meta-citation_author', 'meta-dc.creator', 'meta-dcterms.creator'],
+  ['meta-article:published_time', 'meta-citation_publication_date', 'meta-citation_date', 'meta-dcterms.date',
+    'meta-dc.date', 'meta-date', 'meta-dcterms.created'],
+  ['meta-article:modified_time', 'meta-dcterms.modified'],
+];
+/** Front matter longer than this is not the converter's (e.g. a Markdown file's own); leave it. */
+const MAX_FRONT_MATTER_CHARS = 20_000;
+/** A front-matter entry starts with `key:`; other lines continue the previous value. */
+const FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+
+/**
+ * Trim the front matter the native converter builds from <meta> tags to the
+ * lines a reader can use: title, description, author, publication and
+ * modification date. The rest (analytics and error-reporting URLs, verification
+ * hashes, nonces, app ids, Open Graph / Twitter duplicates of the title and
+ * description, viewport, robots…) is noise: 54 lines on a GitHub page. Nothing
+ * in pi-research parses these lines. The block is dropped when none of the kept
+ * keys is present.
+ */
+export function trimFrontMatter(markdown: string): string {
+  if (!markdown.startsWith('---\n')) return markdown;
+  const close = markdown.indexOf('\n---\n', 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+
+  const entries: Array<{ key: string; lines: string[] }> = [];
+  for (const line of markdown.slice(4, close).split('\n')) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1]!.toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1]!.lines.push(line);
+  }
+  const kept: string[] = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== undefined);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, '');
+  return kept.length ? `---\n${kept.join('\n')}\n---\n\n${rest}` : rest;
+}
+
+/**
+ * Converter post-processing, shared by the native and the JS converter. The
+ * front matter is trimmed first. Images go before empty links: a heading anchor
+ * often wraps an icon (GitHub: `[![](link.svg)](#title)`) and only becomes an
+ * empty link once the image is gone. Removing a link that stood on its own line
+ * leaves extra blank lines, so they are collapsed again.
+ */
+export function cleanConvertedMarkdown(markdown: string): string {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
 /**
  * Strip image links from markdown
  */
@@ -511,7 +582,7 @@ export function createNativeMarkdownConverter(
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false,
     });
-    return stripImageLinks(result.content ?? '');
+    return cleanConvertedMarkdown(result.content ?? '');
   };
 }
 
@@ -527,7 +598,7 @@ export function createJsMarkdownConverter(): (html: string) => Promise<string> {
 
   return async (html: string): Promise<string> => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }