ownsearch 0.1.4 → 0.1.5

package/README.md

@@ -25,6 +25,12 @@ Most agents waste time and tokens when they do one of two things:
 - giving agents a structured way to fetch only the chunks they need
 - improving answer quality with reranking, deduplication, and grounded chunk access
 
+It uses a hybrid retrieval surface rather than treating embeddings as a full replacement for exact search:
+
+- `literal_search` for exact names, titles, IDs, and quoted phrases
+- `search_context` for the normal fast semantic path
+- `deep_search_context` for archive-style, multi-document, or ambiguity-heavy questions
+
 ## Core use cases
 
 `ownsearch` is a good fit when an agent needs to work over:
@@ -66,6 +72,7 @@ What is already strong in the current package:
 - support for common text document formats
 - large plain text and code files are no longer blocked by the extracted-document size cap
 - repeatable smoke validation for mixed text corpora
+- a hybrid retrieval interface that works better for agents than embeddings alone
 
 ## V1 supported document types
 
@@ -93,6 +100,8 @@ Installation:
 npm install -g ownsearch
 ```
 
+Gemini API usage is governed by Google’s current free-tier limits, quotas, and pricing.
+
 Deployment checklist:
 
 ```bash
@@ -115,19 +124,34 @@ ownsearch setup
 ownsearch doctor
 ownsearch index ./docs --name docs
 ownsearch list-roots
+ownsearch literal-search "exact title or phrase" --limit 10
 ownsearch search "what is this repo about?" --limit 5
 ownsearch search-context "what is this repo about?" --limit 8 --max-chars 12000
+ownsearch deep-search-context "what is this repo about?" --final-limit 10 --max-chars 16000
 ownsearch serve-mcp
 ```
 
 On first run, `ownsearch setup` can:
 
 - prompt for `GEMINI_API_KEY`
-- link users to Google AI Studio
+- open Google AI Studio automatically
 - save the key to `~/.ownsearch/.env`
+- validate the pasted key before saving it
+- ask whether setup output should be optimized for a human or an agent
 - print exact next commands for CLI and MCP usage
 - optionally print an MCP config snippet for a selected agent
 
+Gemini API usage is governed by Google’s current free-tier limits, quotas, and pricing.
+
+Useful setup modes:
+
+```bash
+ownsearch setup
+ownsearch setup --audience human
+ownsearch setup --audience agent
+ownsearch setup --json
+```
+
 ## Real-world fit
 
 `ownsearch` is a strong fit for:
@@ -186,7 +210,7 @@ ownsearch print-skill ownsearch-rag-search
 The skill is intended to help an agent:
 
 - rewrite weak user requests into stronger retrieval queries
-- decide when to use `search_context` vs `search` vs `get_chunks`
+- decide when to use `literal_search` vs `search_context` vs `deep_search_context` vs `get_chunks`
 - recover from poor first-pass retrieval
 - avoid duplicate-heavy answer synthesis
 - stay grounded when retrieval is probabilistic
@@ -203,8 +227,12 @@ The skill is intended to help an agent:
   Lists approved indexed roots.
 - `ownsearch search "<query>"`
   Returns reranked search hits from the vector store.
+- `ownsearch literal-search "<query>"`
+  Runs exact text search with `ripgrep` over indexed roots.
 - `ownsearch search-context "<query>"`
   Returns a compact grounded context bundle for agents.
+- `ownsearch deep-search-context "<query>"`
+  Runs a deeper multi-query retrieval pass for ambiguous or archive-style questions.
 - `ownsearch delete-root <rootId>`
   Removes a root from config and deletes its vectors from Qdrant.
 - `ownsearch store-status`
@@ -220,9 +248,12 @@ The skill is intended to help an agent:
 
 The MCP server currently exposes:
 
+- `get_retrieval_skill`
 - `index_path`
 - `search`
+- `literal_search`
 - `search_context`
+- `deep_search_context`
 - `get_chunks`
 - `list_roots`
 - `delete_root`
@@ -230,9 +261,11 @@ The MCP server currently exposes:
 
 Recommended retrieval flow:
 
-1. Use `search_context` for fast grounded retrieval.
-2. Use `search` when ranking and source inspection matter.
-3. Use `get_chunks` when exact wording or detailed comparison matters.
+1. Use `literal_search` when the user gives an exact title, name, identifier, or quoted phrase.
+2. Use `search_context` for fast grounded retrieval.
+3. Use `deep_search_context` for ambiguous, archive-style, or multi-document questions.
+4. Use `search` when ranking and source inspection matter.
+5. Use `get_chunks` when exact wording or detailed comparison matters.
 
 ## Validation
 
@@ -250,6 +283,25 @@ That smoke run currently validates:
 - `.pdf` retrieval
 - large plain text file bypass of the extracted-document byte cap
 
+The repo also includes comparative retrieval evals:
+
+- `scripts/eval-grep-vs-ownsearch.mts`
+- `scripts/eval-adversarial-retrieval.mts`
+
+These evals are meant to expose where:
+
+- plain `grep` is still best
+- shallow semantic retrieval is too weak
+- deeper retrieval improves agent-facing RAG quality
+
+On the current Mireglass benchmark corpus, the latest comparative run produced:
+
+- `deep`: `69.2` average score
+- `grep`: `65.67` average score
+- `shallow`: `65.09` average score
+
+The adversarial eval also showed that the current deep path reduced known noise-file leakage the most in this corpus.
+
 ## Limitations
 
 This package is deploy-ready for text-first corpora, but it is not universal document intelligence.
@@ -269,6 +321,8 @@ Operational limitations:
 - extracted document quality depends on source document quality
 - duplicate-heavy corpora are improved by current reranking, but not fully solved for all edge cases
 - scanned or low-quality PDFs may require OCR before indexing
+- `literal_search` depends on `ripgrep` being available on the local machine
+- exact literal lookup can still beat semantic retrieval on some questions, so agents should use the hybrid flow instead of embeddings alone
 
 ## Future scope
 

package/dist/{chunk-ZQAY3FE3.js → chunk-TBXFY4OJ.js}

@@ -114,6 +114,12 @@ var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
   "node_modules",
   "venv"
 ]);
+var DOWNWEIGHTED_PATH_SUBSTRINGS = [
+  "/09_benchmark_queries.txt",
+  "/10_extra_hard_notes_for_chunking.txt",
+  "09_benchmark_queries.txt",
+  "10_extra_hard_notes_for_chunking.txt"
+];
 
 // src/utils.ts
 import crypto from "crypto";
@@ -322,6 +328,26 @@ async function embedQuery(query) {
   const [vector] = await embed([query], "RETRIEVAL_QUERY");
   return vector;
 }
+async function validateGeminiApiKey(apiKey) {
+  const config = await loadConfig();
+  const validationClient = new GoogleGenAI({ apiKey });
+  try {
+    const response = await validationClient.models.embedContent({
+      model: config.embeddingModel,
+      contents: ["ownsearch key validation"],
+      config: {
+        taskType: "RETRIEVAL_QUERY",
+        outputDimensionality: config.vectorSize
+      }
+    });
+    if (!response.embeddings?.length || !response.embeddings[0]?.values?.length) {
+      throw new OwnSearchError("Gemini key validation returned no embeddings.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new OwnSearchError(`Gemini API key validation failed. ${message}`);
+  }
+}
 
 // src/qdrant.ts
 import { QdrantClient } from "@qdrant/js-client-rest";
@@ -431,6 +457,10 @@ function rerankAndDeduplicate(query, hits, limit) {
 }
 
 // src/qdrant.ts
+function isDownweightedPath(relativePath) {
+  const lowered = relativePath.toLowerCase();
+  return DOWNWEIGHTED_PATH_SUBSTRINGS.some((pattern) => lowered.includes(pattern.toLowerCase()));
+}
 var OwnSearchStore = class {
   constructor(client2, collectionName, vectorSize) {
     this.client = client2;
@@ -594,7 +624,7 @@ var OwnSearchStore = class {
     });
     const hits = results.map((result) => ({
       id: String(result.id),
-      score: result.score,
+      score: isDownweightedPath(String(result.payload?.relative_path ?? "")) ? result.score * 0.6 : result.score,
       rootId: String(result.payload?.root_id ?? ""),
       rootName: String(result.payload?.root_name ?? ""),
       filePath: String(result.payload?.file_path ?? ""),
@@ -891,6 +921,203 @@ async function indexPath(rootPath, options = {}) {
   };
 }
 
+// src/literal-search.ts
+import { execFile as execFileCallback } from "child_process";
+import path5 from "path";
+import { promisify } from "util";
+var execFile = promisify(execFileCallback);
+function normalizePath(value) {
+  return value.replace(/\\/g, "/");
+}
+async function literalSearch(args) {
+  const config = await loadConfig();
+  let roots;
+  if (args.rootIds?.length) {
+    const resolved = await Promise.all(args.rootIds.map((rootId) => findRoot(rootId)));
+    const missingRootIds = args.rootIds.filter((_, index) => !resolved[index]);
+    if (missingRootIds.length) {
+      throw new OwnSearchError(
+        `Unknown root ID(s) for literal search: ${missingRootIds.join(", ")}. Call \`list-roots\` to see valid root IDs.`
+      );
+    }
+    roots = resolved.filter((root) => Boolean(root));
+  } else {
+    roots = config.roots;
+  }
+  if (!roots.length) {
+    throw new OwnSearchError("No indexed roots are available for literal search. Call `list_roots` or `index_path` first.");
+  }
+  const limit = Math.max(1, Math.min(args.limit ?? 20, 100));
+  const matches = [];
+  for (const root of roots) {
+    const { stdout } = await execFile(
+      "rg",
+      [
+        "-n",
+        "-i",
+        "--fixed-strings",
+        "--max-count",
+        String(limit),
+        args.query,
+        root.path
+      ],
+      {
+        windowsHide: true,
+        maxBuffer: 1024 * 1024 * 10
+      }
+    ).catch((error) => {
+      if (error?.code === 1) {
+        return { stdout: "" };
+      }
+      throw new OwnSearchError("Literal search failed. Ensure `rg` (ripgrep) is installed and available on PATH.");
+    });
+    for (const line of stdout.split(/\r?\n/)) {
+      if (!line.trim()) {
+        continue;
+      }
+      const match = line.match(/^(.*?):(\d+):(.*)$/);
+      if (!match) {
+        continue;
+      }
+      const filePath = match[1];
+      const relativePath = normalizePath(path5.relative(root.path, filePath));
+      if (args.pathSubstring && !relativePath.toLowerCase().includes(args.pathSubstring.toLowerCase())) {
+        continue;
+      }
+      matches.push({
+        rootId: root.id,
+        rootName: root.name,
+        filePath,
+        relativePath,
+        lineNumber: Number(match[2]),
+        content: match[3].trim()
+      });
+      if (matches.length >= limit) {
+        return matches;
+      }
+    }
+  }
+  return matches;
+}
+
+// src/retrieval.ts
+var LEADING_PATTERNS = [
+  /^(what is|what was|who is|who was)\s+/i,
+  /^(tell me about|explain|summarize|describe)\s+/i,
+  /^(where is|where was|where does|where did)\s+/i,
+  /^(how does|how do|how did|why does|why did)\s+/i
+];
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "how",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "was",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why"
+]);
+function deriveQueryVariants(query) {
+  const normalized = query.trim().replace(/\s+/g, " ");
+  const variants = /* @__PURE__ */ new Set();
+  if (!normalized) {
+    return [];
+  }
+  variants.add(normalized);
+  let stripped = normalized;
+  for (const pattern of LEADING_PATTERNS) {
+    stripped = stripped.replace(pattern, "");
+  }
+  stripped = stripped.replace(/[?.!]+$/g, "").trim();
+  if (stripped && stripped !== normalized) {
+    variants.add(stripped);
+  }
+  const quotedMatches = [...normalized.matchAll(/"([^"]+)"/g)].map((match) => match[1]?.trim()).filter(Boolean);
+  for (const match of quotedMatches) {
+    variants.add(match);
+  }
+  const keywordVariant = normalized.split(/[^A-Za-z0-9_-]+/).filter((token) => token && !STOPWORDS.has(token.toLowerCase())).slice(0, 8).join(" ").trim();
+  if (keywordVariant && keywordVariant !== normalized && keywordVariant !== stripped) {
+    variants.add(keywordVariant);
+  }
+  return [...variants].slice(0, 4);
+}
+function diversifyHits(hits, limit) {
+  const seenIds = /* @__PURE__ */ new Set();
+  const fileCounts = /* @__PURE__ */ new Map();
+  const diversified = [];
+  const sorted = [...hits].sort((a, b) => {
+    const aCount = fileCounts.get(a.relativePath) ?? 0;
+    const bCount = fileCounts.get(b.relativePath) ?? 0;
+    const aScore = a.score - aCount * 0.015;
+    const bScore = b.score - bCount * 0.015;
+    return bScore - aScore;
+  });
+  for (const hit of sorted) {
+    if (seenIds.has(hit.id)) {
+      continue;
+    }
+    const count = fileCounts.get(hit.relativePath) ?? 0;
+    if (count >= 3 && diversified.length >= Math.max(3, Math.floor(limit / 2))) {
+      continue;
+    }
+    diversified.push(hit);
+    seenIds.add(hit.id);
+    fileCounts.set(hit.relativePath, count + 1);
+    if (diversified.length >= limit) {
+      break;
+    }
+  }
+  return diversified;
+}
+async function deepSearchContext(query, options = {}) {
+  const store = await createStore();
+  const variants = deriveQueryVariants(query);
+  const allHits = [];
+  for (const variant of variants) {
+    const vector = await embedQuery(variant);
+    const hits = await store.search(
+      vector,
+      {
+        queryText: variant,
+        rootIds: options.rootIds,
+        pathSubstring: options.pathSubstring
+      },
+      Math.max(1, Math.min(options.perQueryLimit ?? 6, 12))
+    );
+    allHits.push(...hits);
+  }
+  const finalHits = diversifyHits(allHits, Math.max(1, Math.min(options.finalLimit ?? 10, 20)));
+  const bundle = buildContextBundle(query, finalHits, Math.max(500, options.maxChars ?? 16e3));
+  return {
+    query,
+    queryVariants: variants,
+    hitCount: finalHits.length,
+    distinctFiles: [...new Set(finalHits.map((hit) => hit.relativePath))].length,
+    bundle
+  };
+}
+
 export {
   buildContextBundle,
   getConfigPath,
@@ -905,6 +1132,9 @@ export {
   listRoots,
   OwnSearchError,
   embedQuery,
+  validateGeminiApiKey,
   createStore,
-  indexPath
+  indexPath,
+  literalSearch,
+  deepSearchContext
 };

package/dist/cli.js

@@ -3,6 +3,7 @@ import {
   OwnSearchError,
   buildContextBundle,
   createStore,
+  deepSearchContext,
   deleteRootDefinition,
   embedQuery,
   findRoot,
@@ -11,11 +12,13 @@ import {
   getEnvPath,
   indexPath,
   listRoots,
+  literalSearch,
   loadConfig,
   loadOwnSearchEnv,
   readEnvFile,
-  saveGeminiApiKey
-} from "./chunk-ZQAY3FE3.js";
+  saveGeminiApiKey,
+  validateGeminiApiKey
+} from "./chunk-TBXFY4OJ.js";
 
 // src/cli.ts
 import fs from "fs/promises";
@@ -29,12 +32,16 @@ import { Command } from "commander";
 import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+var DOCKER_DESKTOP_WINDOWS_URL = "https://docs.docker.com/desktop/setup/install/windows-install/";
+var DOCKER_DESKTOP_OVERVIEW_URL = "https://docs.docker.com/desktop/";
 async function runDocker(args) {
   try {
     const { stdout } = await execFileAsync("docker", args, { windowsHide: true });
     return stdout.trim();
   } catch (error) {
-    throw new OwnSearchError("Docker is required for Qdrant setup. Install Docker and ensure `docker` is on PATH.");
+    throw new OwnSearchError(
+      `Docker is required for Qdrant setup. Install Docker Desktop and ensure \`docker\` is on PATH. Windows install guide: ${DOCKER_DESKTOP_WINDOWS_URL} General Docker Desktop docs: ${DOCKER_DESKTOP_OVERVIEW_URL}`
+    );
   }
 }
 async function ensureQdrantDocker() {
@@ -71,6 +78,8 @@ loadOwnSearchEnv();
 var program = new Command();
 var PACKAGE_NAME = "ownsearch";
 var GEMINI_API_KEY_URL = "https://aistudio.google.com/apikey";
+var DOCKER_DESKTOP_WINDOWS_URL2 = "https://docs.docker.com/desktop/setup/install/windows-install/";
+var DOCKER_DESKTOP_OVERVIEW_URL2 = "https://docs.docker.com/desktop/";
 var BUNDLED_SKILL_NAME = "ownsearch-rag-search";
 var SUPPORTED_AGENTS = [
   "codex",
@@ -90,10 +99,7 @@ function requireGeminiKey() {
 function buildAgentConfig(agent) {
   const stdioConfig = {
     command: "npx",
-    args: ["-y", PACKAGE_NAME, "serve-mcp"],
-    env: {
-      GEMINI_API_KEY: "${GEMINI_API_KEY}"
-    }
+    args: ["-y", PACKAGE_NAME, "serve-mcp"]
   };
   switch (agent) {
     case "codex":
@@ -126,7 +132,6 @@ function buildAgentConfig(agent) {
               type: "local",
               command: stdioConfig.command,
               args: stdioConfig.args,
-              env: stdioConfig.env,
               tools: ["*"]
             }
           }
@@ -203,22 +208,59 @@ async function promptForGeminiKey() {
     output: process.stdout
   });
   try {
-    console.log(`Generate a Gemini API key here: ${GEMINI_API_KEY_URL}`);
-    console.log(`OwnSearch will save it to ${getEnvPath()}`);
+    console.log(`OwnSearch needs a Gemini API key for indexing and search.`);
+    console.log("Gemini API usage is governed by Google\u2019s current free-tier limits, quotas, and pricing.");
+    console.log(`Open Google AI Studio here: ${GEMINI_API_KEY_URL}`);
+    console.log(`OwnSearch will save the key to ${getEnvPath()}`);
+    openGeminiKeyPage();
+    await rl.question("Press Enter after the AI Studio page is open and you are ready to paste the key: ");
     for (; ; ) {
       const apiKey = (await rl.question("Paste GEMINI_API_KEY and press Enter (Ctrl+C to cancel): ")).trim();
       if (!apiKey) {
         console.log("GEMINI_API_KEY is required for indexing and search.");
         continue;
       }
-      await saveGeminiApiKey(apiKey);
       process.env.GEMINI_API_KEY = apiKey;
+      process.env.GOOGLE_API_KEY = apiKey;
+      process.stdout.write("Validating key with Gemini...");
+      try {
+        await validateGeminiApiKey(apiKey);
+        process.stdout.write(" ok\n");
+      } catch (error) {
+        process.stdout.write(" failed\n");
+        console.log(error instanceof Error ? error.message : String(error));
+        continue;
+      }
+      await saveGeminiApiKey(apiKey);
       return true;
     }
   } finally {
     rl.close();
   }
 }
+function openGeminiKeyPage() {
+  try {
+    if (process.platform === "win32") {
+      spawn("cmd", ["/c", "start", "", GEMINI_API_KEY_URL], {
+        stdio: "ignore",
+        detached: true
+      }).unref();
+      return;
+    }
+    if (process.platform === "darwin") {
+      spawn("open", [GEMINI_API_KEY_URL], {
+        stdio: "ignore",
+        detached: true
+      }).unref();
+      return;
+    }
+    spawn("xdg-open", [GEMINI_API_KEY_URL], {
+      stdio: "ignore",
+      detached: true
+    }).unref();
+  } catch {
+  }
+}
 function getGeminiApiKeySource() {
   if (readEnvFile(getEnvPath()).GEMINI_API_KEY) {
     return "ownsearch-env";
@@ -247,28 +289,81 @@ async function ensureManagedGeminiKey() {
     savedToManagedEnv: prompted
   };
 }
+async function promptForSetupAudience() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return "agent";
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    console.log("");
+    console.log("Who is running setup?");
+    console.log("  1. Human");
+    console.log("  2. Agent");
+    for (; ; ) {
+      const answer = (await rl.question("Select 1-2: ")).trim().toLowerCase();
+      switch (answer) {
+        case "1":
+        case "human":
+          return "human";
+        case "2":
+        case "agent":
+          return "agent";
+        default:
+          console.log("Enter 1 or 2.");
+      }
+    }
+  } finally {
+    rl.close();
+  }
+}
 function printSetupNextSteps() {
   console.log("");
-  console.log("Next commands:");
-  console.log("  CLI indexing:");
+  console.log("Next steps");
+  console.log("  1. Index a folder:");
+  console.log("     ownsearch index C:\\path\\to\\folder --name my-folder");
+  console.log("  2. Test exact-match search in the CLI:");
+  console.log('     ownsearch literal-search "exact title or phrase" --limit 10');
+  console.log("  3. Test semantic search in the CLI:");
+  console.log('     ownsearch search "your question here" --limit 5');
+  console.log("  4. Get grounded context for an agent:");
+  console.log('     ownsearch search-context "your question here" --limit 8 --max-chars 12000');
+  console.log("  5. Use deeper retrieval for archive-style questions:");
+  console.log('     ownsearch deep-search-context "your question here" --final-limit 10 --max-chars 16000');
+  console.log("  6. Start the MCP server:");
+  console.log("     ownsearch serve-mcp");
+  console.log("  7. Print agent-specific config:");
+  console.log("     ownsearch print-agent-config codex");
+  console.log("  8. Print the bundled retrieval skill:");
+  console.log(`     ownsearch print-skill ${BUNDLED_SKILL_NAME}`);
+  console.log("");
+  console.log("Docker requirement");
+  console.log("  OwnSearch requires Docker Desktop so it can run Qdrant locally.");
+  console.log(`  Windows install: ${DOCKER_DESKTOP_WINDOWS_URL2}`);
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL2}`);
+}
+function printAgentSetupNextSteps() {
+  console.log("");
+  console.log("Agent-ready commands");
+  console.log("  Index an approved folder:");
   console.log("    ownsearch index C:\\path\\to\\folder --name my-folder");
-  console.log("  CLI search:");
-  console.log('    ownsearch search "your question here" --limit 5');
-  console.log("  CLI grounded context:");
+  console.log("  For exact names, titles, IDs, or quoted strings:");
+  console.log('    ownsearch literal-search "exact text here" --limit 10');
+  console.log("  Retrieve grounded context:");
   console.log('    ownsearch search-context "your question here" --limit 8 --max-chars 12000');
-  console.log("  MCP server for agents:");
+  console.log("  Use deeper retrieval for ambiguous or multi-document questions:");
+  console.log('    ownsearch deep-search-context "your question here" --final-limit 10 --max-chars 16000');
+  console.log("  Start the MCP server:");
   console.log("    ownsearch serve-mcp");
-  console.log("  Agent config snippets:");
+  console.log("  Print MCP config for the host agent:");
   console.log("    ownsearch print-agent-config codex");
-  console.log("    ownsearch print-agent-config claude-desktop");
-  console.log("    ownsearch print-agent-config cursor");
-  console.log("    ownsearch print-agent-config vscode");
-  console.log("    ownsearch print-agent-config github-copilot");
-  console.log("    ownsearch print-agent-config copilot-cli");
-  console.log("    ownsearch print-agent-config windsurf");
-  console.log("    ownsearch print-agent-config continue");
-  console.log("  Bundled retrieval skill:");
-  console.log(`    ownsearch print-skill ${BUNDLED_SKILL_NAME}`);
+  console.log("");
+  console.log("Docker requirement");
+  console.log("  OwnSearch requires Docker Desktop so it can run Qdrant locally.");
+  console.log(`  Windows install: ${DOCKER_DESKTOP_WINDOWS_URL2}`);
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL2}`);
 }
 async function promptForAgentChoice() {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
@@ -329,16 +424,65 @@ async function promptForAgentChoice() {
   }
 }
 function printAgentConfigSnippet(agent) {
+  const payload = buildAgentConfig(agent);
   console.log("");
-  console.log(`MCP config for ${agent}:`);
-  console.log(JSON.stringify(buildAgentConfig(agent), null, 2));
+  console.log(`Connect OwnSearch to ${agent}`);
+  if (payload.installMethod) {
+    console.log(`  Recommended install method: ${payload.installMethod}`);
+  }
+  if (payload.configPath) {
+    console.log(`  Config file: ${payload.configPath}`);
+  }
+  if (payload.configScope) {
+    console.log(`  Scope: ${payload.configScope}`);
+  }
+  if (payload.note) {
+    console.log(`  Note: ${payload.note}`);
+  }
+  if (payload.nextStep) {
+    console.log(`  Next step: ${payload.nextStep}`);
+  }
+  if (payload.config) {
+    console.log("");
+    console.log("Paste this config:");
+    console.log(JSON.stringify(payload.config, null, 2));
+    console.log("");
+    console.log(`OwnSearch will load GEMINI_API_KEY from ${getEnvPath()} if you ran \`ownsearch setup\`.`);
+  }
+}
+function printSetupSummary(input) {
+  console.log("OwnSearch setup complete");
+  console.log("  Docker is required because OwnSearch runs Qdrant locally in Docker.");
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_WINDOWS_URL2}`);
+  console.log(`  Config: ${input.configPath}`);
+  console.log(`  API key file: ${input.envPath}`);
+  console.log(`  Qdrant: ${input.qdrantUrl} (${input.qdrantStarted ? "started now" : "already running or reachable"})`);
+  if (input.geminiApiKeyPresent) {
+    console.log(`  Gemini API key: ready (${input.geminiApiKeySource})`);
+    if (input.geminiApiKeySavedToManagedEnv) {
+      console.log("  Saved your key to the managed OwnSearch env file.");
+    }
+  } else {
+    console.log("  Gemini API key: missing");
+  }
 }
-program.name("ownsearch").description("Gemini-powered local search MCP server backed by Qdrant.").version("0.1.0");
-program.command("setup").description("Create config and start a local Qdrant Docker container.").action(async () => {
+function printAgentSetupSummary(input) {
+  console.log("OwnSearch setup ready for agent use");
+  console.log("  Docker is required because OwnSearch runs Qdrant locally in Docker.");
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_WINDOWS_URL2}`);
+  console.log(`  Config path: ${input.configPath}`);
+  console.log(`  Managed env path: ${input.envPath}`);
+  console.log(`  Qdrant endpoint: ${input.qdrantUrl}`);
+  console.log(`  Qdrant status: ${input.qdrantStarted ? "started during setup" : "already reachable"}`);
+  console.log(`  Gemini key: ${input.geminiApiKeyPresent ? `ready (${input.geminiApiKeySource})` : "missing"}`);
+}
+program.name("ownsearch").description("Gemini-powered local search MCP server backed by Qdrant.").version("0.1.4");
+program.command("setup").description("Create config and start a local Qdrant Docker container.").option("--json", "Print machine-readable JSON output").option("--audience <audience>", "Choose output style: human or agent").action(async (options) => {
   const config = await loadConfig();
   const result = await ensureQdrantDocker();
   const gemini = await ensureManagedGeminiKey();
-  console.log(JSON.stringify({
+  const audience = options.json ? "agent" : options.audience === "human" || options.audience === "agent" ? options.audience : await promptForSetupAudience();
+  const summary = {
     configPath: getConfigPath(),
     envPath: getEnvPath(),
     qdrantUrl: config.qdrantUrl,
@@ -346,15 +490,27 @@ program.command("setup").description("Create config and start a local Qdrant Doc
     geminiApiKeyPresent: gemini.present,
     geminiApiKeySource: gemini.source,
     geminiApiKeySavedToManagedEnv: gemini.savedToManagedEnv
-  }, null, 2));
+  };
+  if (options.json) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  } else if (audience === "agent") {
+    printAgentSetupSummary(summary);
+  } else {
+    printSetupSummary(summary);
+  }
   if (!gemini.present) {
     console.log(`GEMINI_API_KEY is not set. Re-run setup or add it to ${getEnvPath()} before indexing or search.`);
     return;
   }
-  printSetupNextSteps();
-  const agent = await promptForAgentChoice();
-  if (agent) {
-    printAgentConfigSnippet(agent);
+  if (audience === "agent") {
+    printAgentSetupNextSteps();
+  } else {
+    printSetupNextSteps();
+    const agent = await promptForAgentChoice();
+    if (agent) {
+      printAgentConfigSnippet(agent);
+    }
   }
 });
 program.command("index").argument("<folder>", "Folder path to index").option("-n, --name <name>", "Display name for the indexed root").option("--max-file-bytes <n>", "Override the file size limit for this run", (value) => Number(value)).description("Index a local folder into Qdrant using Gemini embeddings.").action(async (folder, options) => {
@@ -382,6 +538,17 @@ program.command("search").argument("<query>", "Natural language query").option("
     console.log(JSON.stringify({ query, hits }, null, 2));
   }
 );
+program.command("literal-search").argument("<query>", "Exact text query").option("--root-id <rootId...>", "Restrict search to one or more root IDs (repeatable)").option("--limit <n>", "Max matches (default 20)", (value) => Number(value), 20).option("--path <substr>", "Filter results to files whose relative path contains this substring").description("Run grep-style exact text search over indexed roots with ripgrep.").action(
+  async (query, options) => {
+    const matches = await literalSearch({
+      query,
+      rootIds: options.rootId,
+      limit: Math.max(1, Math.min(options.limit ?? 20, 100)),
+      pathSubstring: options.path
+    });
+    console.log(JSON.stringify({ query, matches }, null, 2));
+  }
+);
 program.command("search-context").argument("<query>", "Natural language query").option("--root-id <rootId...>", "Restrict search to one or more root IDs (repeatable)").option("--limit <n>", "Max search hits to consider (default 8)", (value) => Number(value), 8).option("--max-chars <n>", "Max context characters to return (default 12000)", (value) => Number(value), 12e3).option("--path <substr>", "Filter results to files whose relative path contains this substring").description("Search the local Qdrant store and return a bundled context payload for agent use.").action(
   async (query, options) => {
     requireGeminiKey();
@@ -399,6 +566,19 @@ program.command("search-context").argument("<query>", "Natural language query").
     console.log(JSON.stringify(buildContextBundle(query, hits, Math.max(500, options.maxChars ?? 12e3)), null, 2));
   }
 );
+program.command("deep-search-context").argument("<query>", "Natural language query").option("--root-id <rootId...>", "Restrict search to one or more root IDs (repeatable)").option("--per-query-limit <n>", "Max hits per query variant (default 6)", (value) => Number(value), 6).option("--final-limit <n>", "Max aggregated result blocks (default 10)", (value) => Number(value), 10).option("--max-chars <n>", "Max context characters to return (default 16000)", (value) => Number(value), 16e3).option("--path <substr>", "Filter results to files whose relative path contains this substring").description("Run a deeper multi-query retrieval pass for ambiguous or archive-style questions.").action(
+  async (query, options) => {
+    requireGeminiKey();
+    const result = await deepSearchContext(query, {
+      rootIds: options.rootId,
+      pathSubstring: options.path,
+      perQueryLimit: Math.max(1, Math.min(options.perQueryLimit ?? 6, 12)),
+      finalLimit: Math.max(1, Math.min(options.finalLimit ?? 10, 20)),
+      maxChars: Math.max(500, options.maxChars ?? 16e3)
+    });
+    console.log(JSON.stringify(result, null, 2));
+  }
+);
 program.command("list-roots").description("List indexed roots registered in local config.").action(async () => {
   console.log(JSON.stringify({ roots: await listRoots() }, null, 2));
 });
@@ -461,9 +641,14 @@ program.command("serve-mcp").description("Start the stdio MCP server.").action(a
     process.exitCode = code ?? 0;
   });
 });
-program.command("print-agent-config").argument("<agent>", SUPPORTED_AGENTS.join(" | ")).description("Print an MCP config snippet for a supported agent.").action(async (agent) => {
+program.command("print-agent-config").argument("<agent>", SUPPORTED_AGENTS.join(" | ")).description("Print an MCP config snippet for a supported agent.").option("--json", "Print the full machine-readable payload").action(async (agent, options) => {
   if (SUPPORTED_AGENTS.includes(agent)) {
-    console.log(JSON.stringify(buildAgentConfig(agent), null, 2));
+    const payload = buildAgentConfig(agent);
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    printAgentConfigSnippet(agent);
     return;
   }
   throw new OwnSearchError(`Unsupported agent: ${agent}`);

package/dist/mcp/server.js

@@ -3,19 +3,26 @@ import {
   OwnSearchError,
   buildContextBundle,
   createStore,
+  deepSearchContext,
   deleteRootDefinition,
   embedQuery,
   findRoot,
   indexPath,
+  literalSearch,
   loadConfig,
   loadOwnSearchEnv
-} from "../chunk-ZQAY3FE3.js";
+} from "../chunk-TBXFY4OJ.js";
 
 // src/mcp/server.ts
+import fs from "fs/promises";
+import path from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { fileURLToPath } from "url";
 loadOwnSearchEnv();
+var BUNDLED_SKILL_NAME = "ownsearch-rag-search";
+var SERVER_VERSION = "0.1.5";
 function asText(result) {
   return {
     content: [
@@ -26,14 +33,79 @@ function asText(result) {
     ]
   };
 }
+function withGuidance(summary, data, nextActions = []) {
+  return asText({
+    summary,
+    nextActions,
+    data
+  });
+}
+async function readBundledSkill(skillName) {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const packageRoot = path.resolve(path.dirname(currentFilePath), "..", "..");
+  const skillPath = path.join(packageRoot, "skills", skillName, "SKILL.md");
+  return fs.readFile(skillPath, "utf8");
+}
+function diagnoseError(message) {
+  const lower = message.toLowerCase();
+  if (lower.includes("gemini_api_key")) {
+    return {
+      summary: "Gemini API key is missing.",
+      nextActions: [
+        "Run `ownsearch setup` in a normal terminal and complete Gemini key setup.",
+        "If this MCP server is running in a restricted environment, ensure it can read ~/.ownsearch/.env or receive GEMINI_API_KEY in its process environment."
+      ]
+    };
+  }
+  if (lower.includes("fetch failed") || lower.includes("network") || lower.includes("timeout")) {
+    return {
+      summary: "OwnSearch could not reach Gemini or Qdrant from this execution environment.",
+      nextActions: [
+        "Check whether the MCP server is running in a sandboxed or restricted environment.",
+        "Verify Gemini API access works in a normal terminal with `ownsearch doctor`.",
+        "Verify local Qdrant is reachable at the configured URL."
+      ]
+    };
+  }
+  if (lower.includes("unknown root")) {
+    return {
+      summary: "The requested root ID does not exist.",
+      nextActions: [
+        "Call `list_roots` to get valid root IDs.",
+        "If the folder was not indexed yet, call `index_path` first."
+      ]
+    };
+  }
+  if (lower.includes("qdrant")) {
+    return {
+      summary: "Qdrant is not reachable or is misconfigured.",
+      nextActions: [
+        "Run `ownsearch setup` or `ownsearch doctor` in a normal terminal.",
+        "Confirm Docker is running and Qdrant is reachable at the configured URL."
+      ]
+    };
+  }
+  return {
+    summary: "OwnSearch tool call failed.",
+    nextActions: [
+      "Inspect the error message below.",
+      "If this is an environment issue, retry in a normal terminal outside the agent sandbox."
+    ]
+  };
+}
 function asError(error) {
   const message = error instanceof Error ? error.message : String(error);
+  const diagnosis = diagnoseError(message);
   return {
     isError: true,
     content: [
       {
         type: "text",
-        text: message
+        text: JSON.stringify({
+          summary: diagnosis.summary,
+          error: message,
+          nextActions: diagnosis.nextActions
+        }, null, 2)
       }
     ]
   };
@@ -41,7 +113,7 @@ function asError(error) {
 var server = new Server(
   {
     name: "ownsearch",
-    version: "0.1.0"
+    version: SERVER_VERSION
   },
   {
     capabilities: {
@@ -51,9 +123,22 @@ var server = new Server(
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    {
+      name: "get_retrieval_skill",
+      description: "Read the bundled OwnSearch retrieval skill. Call this first if you want explicit guidance on query rewriting, search strategy, grounded answering, and failure recovery.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          skillName: {
+            type: "string",
+            description: `Optional skill name. Default is ${BUNDLED_SKILL_NAME}.`
+          }
+        }
+      }
+    },
     {
       name: "index_path",
-      description: "Register a local folder and sync its Gemini embedding index into Qdrant.",
+      description: "Index an approved local folder recursively, including nested subfolders. Use this before search. Returns the registered root and indexing counts. For best retrieval behavior, read `get_retrieval_skill` once before planning search calls.",
       inputSchema: {
         type: "object",
         properties: {
@@ -65,7 +150,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "search",
-      description: "Semantic search over one root or the full local Qdrant store.",
+      description: "Semantic search over one root or the full local store. Use `rootIds` when you want deterministic scope. If you do not know the root ID yet, call `list_roots` first.",
       inputSchema: {
         type: "object",
         properties: {
@@ -81,9 +166,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["query"]
       }
     },
+    {
+      name: "literal_search",
+      description: "Exact text search backed by ripgrep. Prefer this for strong keywords, exact names, IDs, error strings, titles, or other literal queries where grep-style matching is better than semantic retrieval.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Exact text to search for." },
+          rootIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional list of root IDs to restrict search."
+          },
+          pathSubstring: { type: "string", description: "Optional file path substring filter." },
+          limit: { type: "number", description: "Maximum result count. Default 20." }
+        },
+        required: ["query"]
+      }
+    },
     {
       name: "search_context",
-      description: "Search and return a bundled context payload with top chunks for direct agent grounding.",
+      description: "Search and return a grounded context bundle for answer synthesis. Prefer this for question answering. If results are empty, check root scope, indexing completion, and environment connectivity.",
       inputSchema: {
         type: "object",
         properties: {
@@ -100,9 +203,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["query"]
       }
     },
+    {
+      name: "deep_search_context",
+      description: "Run a deeper multi-query retrieval pass for archive-style, ambiguous, or recall-heavy questions. This expands the query, searches multiple variants, diversifies sources, and returns a richer grounded bundle.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Natural language question or concept to investigate." },
+          rootIds: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional list of root IDs to restrict search."
+          },
+          pathSubstring: { type: "string", description: "Optional file path substring filter." },
+          perQueryLimit: { type: "number", description: "Max hits per query variant. Default 6." },
+          finalLimit: { type: "number", description: "Max final aggregated hits. Default 10." },
+          maxChars: { type: "number", description: "Max total characters in the returned context bundle. Default 16000." }
+        },
+        required: ["query"]
+      }
+    },
     {
       name: "get_chunks",
-      description: "Fetch exact indexed chunks by id after a search step.",
+      description: "Fetch exact indexed chunks by id after `search` or `search_context`. Use this when exact wording matters.",
       inputSchema: {
         type: "object",
         properties: {
@@ -117,7 +240,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "list_roots",
-      description: "List approved indexed roots.",
+      description: "List indexed roots with their IDs. Use this before scoped search if you only know the human-readable folder name.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -125,7 +248,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "delete_root",
-      description: "Delete one indexed root from config and vector storage.",
+      description: "Delete one indexed root from config and vector storage. This removes its indexed vectors.",
       inputSchema: {
         type: "object",
         properties: {
@@ -136,7 +259,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "store_status",
-      description: "Inspect Qdrant collection status for the local index.",
+      description: "Inspect the local Qdrant collection status. Use this for environment diagnostics when search behaves unexpectedly.",
       inputSchema: {
         type: "object",
         properties: {}
@@ -147,13 +270,37 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     switch (request.params.name) {
+      case "get_retrieval_skill": {
+        const args = request.params.arguments;
+        const skillName = args?.skillName?.trim() || BUNDLED_SKILL_NAME;
+        const skill = await readBundledSkill(skillName);
+        return withGuidance(
+          `Loaded bundled retrieval skill ${skillName}.`,
+          {
+            skillName,
+            skill
+          },
+          [
+            "Use this skill to rewrite weak user requests into stronger retrieval queries.",
+            "Prefer `search_context` for grounded answering and `get_chunks` when exact wording matters."
+          ]
+        );
+      }
       case "index_path": {
         const args = request.params.arguments;
         if (!args?.path) {
           throw new OwnSearchError("`path` is required.");
         }
         const result = await indexPath(args.path, { name: args.name });
-        return asText(result);
+        return withGuidance(
+          `Indexed folder ${args.path}.`,
+          result,
+          [
+            `Call \`get_retrieval_skill\` once if you want explicit OwnSearch query-planning guidance.`,
+            "Use `list_roots` to confirm the registered root ID if you need scoped search.",
+            "Then call `search_context` for grounded retrieval or `search` for ranked hits."
+          ]
+        );
       }
       case "search": {
         const args = request.params.arguments;
@@ -171,10 +318,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           },
           Math.max(1, Math.min(args.limit ?? 5, 20))
         );
-        return asText({
+        if (hits.length === 0) {
+          return withGuidance(
+            "Search completed but returned no results.",
+            {
+              query: args.query,
+              hits
+            },
+            [
+              "If you intended to search one indexed folder, call `list_roots` and confirm the correct `rootIds` value.",
+              "If indexing may have been interrupted, call `index_path` again for that folder.",
+              "If this server is running in a restricted environment and earlier calls showed `fetch failed`, verify Gemini and Qdrant connectivity outside the sandbox."
+            ]
+          );
+        }
+        return withGuidance(
+          `Search returned ${hits.length} hit(s).`,
+          {
+            query: args.query,
+            hits
+          },
+          [
+            "Use `literal_search` instead when the user gives strong exact strings, IDs, names, or titles.",
+            "If you have not read the OwnSearch retrieval guidance yet, call `get_retrieval_skill` first.",
+            "Use `search_context` if you want a compact grounded bundle for answering.",
+            "Use `get_chunks` on selected hit IDs when exact wording matters."
+          ]
+        );
+      }
+      case "literal_search": {
+        const args = request.params.arguments;
+        if (!args?.query) {
+          throw new OwnSearchError("`query` is required.");
+        }
+        const matches = await literalSearch({
           query: args.query,
-          hits
+          rootIds: args.rootIds,
+          pathSubstring: args.pathSubstring,
+          limit: args.limit
         });
+        if (matches.length === 0) {
+          return withGuidance(
+            "Literal search completed but returned no exact matches.",
+            {
+              query: args.query,
+              matches
+            },
+            [
+              "If the user request is more conceptual or paraphrased, switch to `search_context` or `deep_search_context`.",
+              "If you expected a scoped result, call `list_roots` and verify the correct root ID."
+            ]
+          );
+        }
+        return withGuidance(
+          `Literal search returned ${matches.length} exact match(es).`,
+          {
+            query: args.query,
+            matches
+          },
+          [
+            "Use these results when exact wording, names, IDs, or titles matter.",
+            "Switch to `search_context` or `deep_search_context` if you need semantic expansion or multi-document synthesis."
+          ]
+        );
       }
       case "search_context": {
         const args = request.params.arguments;
@@ -192,7 +398,65 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           },
           Math.max(1, Math.min(args.limit ?? 8, 20))
         );
-        return asText(buildContextBundle(args.query, hits, Math.max(500, args.maxChars ?? 12e3)));
+        if (hits.length === 0) {
+          return withGuidance(
+            "Context search completed but returned no results.",
+            {
+              query: args.query,
+              totalChars: 0,
+              results: []
+            },
+            [
+              "Call `list_roots` to confirm the target root ID.",
+              "Retry `search` with the same query to inspect raw hits.",
+              "If indexing may not have completed, call `index_path` again for the folder."
+            ]
+          );
+        }
+        const bundle = buildContextBundle(args.query, hits, Math.max(500, args.maxChars ?? 12e3));
+        return withGuidance(
+          `Context bundle built from ${bundle.results.length} result block(s).`,
+          bundle,
+          [
+            "Use `literal_search` first when the query contains a strong exact string or title.",
+            "If retrieval planning is weak or ambiguous, call `get_retrieval_skill` for query-rewrite guidance.",
+            "Answer using only the returned context when possible.",
+            "If you need exact source text, call `get_chunks` with the contributing chunk IDs from `search`."
+          ]
+        );
+      }
+      case "deep_search_context": {
+        const args = request.params.arguments;
+        if (!args?.query) {
+          throw new OwnSearchError("`query` is required.");
+        }
+        const result = await deepSearchContext(args.query, {
+          rootIds: args.rootIds,
+          pathSubstring: args.pathSubstring,
+          perQueryLimit: args.perQueryLimit,
+          finalLimit: args.finalLimit,
+          maxChars: args.maxChars
+        });
+        if (result.bundle.results.length === 0) {
+          return withGuidance(
+            "Deep retrieval completed but still found no grounded evidence.",
+            result,
+            [
+              "Call `list_roots` to confirm the root scope.",
+              "Retry with a shorter or more literal query.",
+              "If the corpus was indexed recently, call `index_path` again to ensure indexing completed."
+            ]
+          );
+        }
+        return withGuidance(
+          `Deep retrieval built a richer bundle from ${result.distinctFiles} distinct file(s) across ${result.queryVariants.length} query variant(s).`,
+          result,
+          [
+            "Use `literal_search` instead when the user gives a precise title, error string, or identifier.",
+            "Use this result for archive-style or multi-document synthesis.",
+            "If you need exact wording, follow up with `search` and `get_chunks` on the strongest source files."
+          ]
+        );
       }
       case "get_chunks": {
         const args = request.params.arguments;
@@ -201,11 +465,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         const store = await createStore();
         const chunks = await store.getChunks(args.ids);
-        return asText({ chunks });
+        return withGuidance(
+          `Fetched ${chunks.length} chunk(s).`,
+          { chunks },
+          chunks.length ? ["Use these exact chunks when precise quoting or comparison matters."] : ["No matching chunk IDs were found. Re-run `search` and use returned hit IDs."]
+        );
       }
       case "list_roots": {
         const config = await loadConfig();
-        return asText({ roots: config.roots });
+        return withGuidance(
+          `Found ${config.roots.length} indexed root(s).`,
+          { roots: config.roots },
+          config.roots.length ? ["Use the returned `id` values in `search` or `search_context` when you want scoped retrieval."] : ["No roots are indexed yet. Call `index_path` on a local folder first."]
+        );
       }
       case "delete_root": {
         const args = request.params.arguments;
@@ -219,14 +491,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const store = await createStore();
         await store.deleteRoot(root.id);
         await deleteRootDefinition(root.id);
-        return asText({
-          deleted: true,
-          root
-        });
+        return withGuidance(
+          `Deleted root ${root.id}.`,
+          {
+            deleted: true,
+            root
+          },
+          ["Call `list_roots` to confirm the remaining indexed roots."]
+        );
       }
       case "store_status": {
         const store = await createStore();
-        return asText(await store.getStatus());
+        const status = await store.getStatus();
+        return withGuidance(
+          "Retrieved vector store status.",
+          status,
+          [
+            "If search fails, check `pointsCount`, `indexedVectorsCount`, and collection status here.",
+            "Run `list_roots` next if you need to scope searches by root."
+          ]
+        );
       }
       default:
         throw new OwnSearchError(`Unknown tool: ${request.params.name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ownsearch",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Text-first local document search MCP server backed by Gemini embeddings and Qdrant.",
   "type": "module",
   "bin": {

package/skills/ownsearch-rag-search/SKILL.md

@@ -14,9 +14,10 @@ Use this skill to bridge the gap between what a user asks and what OwnSearch sho
 1. Classify the user request.
 2. Generate one to four retrieval queries.
 3. Start with `search_context` for the strongest query.
-4. Expand to additional searches only if evidence is weak, duplicate-heavy, or incomplete.
-5. Use `get_chunks` after `search` when the answer needs exact wording, detailed comparison, or citation-grade grounding.
-6. Answer only from retrieved evidence. Say when the retrieved context is insufficient.
+4. Use `deep_search_context` for archive-style, ambiguous, or recall-heavy questions.
+5. Expand to additional searches only if evidence is weak, duplicate-heavy, or incomplete.
+6. Use `get_chunks` after `search` when the answer needs exact wording, detailed comparison, or citation-grade grounding.
+7. Answer only from retrieved evidence. Say when the retrieved context is insufficient.
 
 ## Query Planning
 
@@ -55,6 +56,19 @@ Use `search_context` when:
 - the answer can be supported by a few chunks
 - low latency matters more than exhaustive recall
 
+Use `literal_search` when:
+
+- the user gives an exact title, name, identifier, error string, or quoted phrase
+- you want grep-style lookup before semantic expansion
+- you suspect the right answer is present literally and want to avoid semantic drift
+
+Use `deep_search_context` when:
+
+- the question spans multiple documents or timelines
+- the answer is likely to require recall beyond the top few semantic hits
+- the user asks "what is", "what happened", or "tell me the full story" for an entity or event
+- the first-pass `search_context` result feels too thin
+
 Use `search` when:
 
 - you want to inspect ranking and source distribution
@@ -124,6 +138,19 @@ For a normal grounded answer:
 4. If results look weak or ambiguous, call `search` with another variant.
 5. Fetch exact chunks for the best IDs before making precise claims.
 
+For an exact-string lookup:
+
+1. Start with `literal_search`.
+2. If literal hits are enough, answer from them or fetch exact chunks nearby.
+3. If literal hits are sparse or too narrow, switch to `search_context`.
+
+For an archive-style or lore-style question:
+
+1. Start with `deep_search_context`.
+2. Inspect the query variants and source spread.
+3. If the answer depends on exact chronology or wording, follow with `search`.
+4. Fetch exact chunks from the strongest files before making strong claims.
+
 For a locate-the-source task:
 
 1. Use `search` first.