ownsearch 0.1.6 → 0.1.8

package/README.md

@@ -61,13 +61,20 @@ Typical agent workflows:
 - reranks and deduplicates result sets before returning them
 - lets agents retrieve ranked hits, exact chunks, or bundled grounded context
 
+Incremental indexing behavior:
+
+- if a file is unchanged, OwnSearch skips it
+- if a file is updated, OwnSearch re-indexes only that file's chunks
+- if a new file appears, OwnSearch indexes only the new file
+- if a file is deleted, OwnSearch removes that file's chunks from the index
+
 ## Current power
 
 What is already strong in the current package:
 
 - local-first setup with Docker-backed Qdrant
 - deterministic readiness checks through `ownsearch doctor`
-- multi-platform MCP config generation
+- multi-platform MCP config installation
 - bundled retrieval skill for better query planning
 - support for common text document formats
 - large plain text and code files are no longer blocked by the extracted-document size cap
@@ -134,12 +141,15 @@ ownsearch serve-mcp
 On first run, `ownsearch setup` can:
 
 - prompt for `GEMINI_API_KEY`
-- open Google AI Studio automatically
+- explain the key-setup flow before opening Google AI Studio
+- open Google AI Studio after the user confirms they are ready
 - 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
+- explain that the MCP server exposes built-in retrieval guidance for agents
 - print exact next commands for CLI and MCP usage
-- optionally print an MCP config snippet for a selected agent
+- offer to install MCP config automatically for supported agents
+- fall back to a manual config snippet inside setup if automatic installation is not supported or fails
 
 Gemini API usage is governed by Google’s current free-tier limits, quotas, and pricing.
 
@@ -170,17 +180,16 @@ It is less suitable when:
 
 ## Agent integration
 
-To print MCP config snippets:
+To let OwnSearch install MCP config automatically:
 
 ```bash
-ownsearch print-agent-config codex
-ownsearch print-agent-config cursor
-ownsearch print-agent-config vscode
-ownsearch print-agent-config github-copilot
-ownsearch print-agent-config copilot-cli
-ownsearch print-agent-config windsurf
-ownsearch print-agent-config continue
-ownsearch print-agent-config claude-desktop
+ownsearch install-agent-config codex
+ownsearch install-agent-config cursor
+ownsearch install-agent-config vscode
+ownsearch install-agent-config github-copilot
+ownsearch install-agent-config copilot-cli
+ownsearch install-agent-config windsurf
+ownsearch install-agent-config continue
 ```
 
 Supported config targets currently include:
@@ -196,8 +205,9 @@ Supported config targets currently include:
 
 Notes:
 
-- `claude-desktop` currently returns guidance rather than a raw JSON snippet because current Claude Desktop docs prefer desktop extensions (`.mcpb`) over manual JSON server configs
-- all other supported targets return concrete MCP config payloads
+- `claude-desktop` is not auto-installed because current Claude Desktop docs prefer desktop extensions (`.mcpb`) over manual JSON server configs
+- supported agents are installed with a safe merge that preserves existing MCP servers
+- if automatic installation is not supported or fails, setup falls back to showing a manual config snippet
 
 ## Bundled skill
 
@@ -215,6 +225,14 @@ The skill is intended to help an agent:
 - avoid duplicate-heavy answer synthesis
 - stay grounded when retrieval is probabilistic
 
+The MCP server also exposes the same guidance directly:
+
+- resource: `ownsearch://skills/retrieval`
+- prompt: `ownsearch-retrieval-guide`
+- tool: `get_retrieval_skill`
+
+That lets an attached agent load the OwnSearch retrieval playbook through MCP instead of relying on external repo knowledge.
+
 ## CLI commands
 
 - `ownsearch setup`
@@ -239,8 +257,8 @@ The skill is intended to help an agent:
   Shows collection status and vector configuration.
 - `ownsearch serve-mcp`
   Starts the stdio MCP server.
-- `ownsearch print-agent-config <agent>`
-  Prints MCP config snippets or platform guidance.
+- `ownsearch install-agent-config <agent>`
+  Safely merges OwnSearch into a supported agent MCP config when the platform can be updated automatically.
 - `ownsearch print-skill [skill]`
   Prints a bundled OwnSearch skill.
 
@@ -259,6 +277,11 @@ The MCP server currently exposes:
 - `delete_root`
 - `store_status`
 
+In addition to tools, the MCP server exposes:
+
+- resource: `ownsearch://skills/retrieval`
+- prompt: `ownsearch-retrieval-guide`
+
 Recommended retrieval flow:
 
 1. Use `literal_search` when the user gives an exact title, name, identifier, or quoted phrase.
@@ -287,21 +310,144 @@ The repo also includes comparative retrieval evals:
 
 - `scripts/eval-grep-vs-ownsearch.mts`
 - `scripts/eval-adversarial-retrieval.mts`
+- `scripts/eval-agent-tooling-efficiency.mts`
+- `scripts/eval-dnd-agent-efficiency.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
+- the retrieval layer improves agent efficiency compared with normal CLI-style tool usage
+
+Run them with:
+
+```bash
+npm run eval:agent-efficiency
+npm run eval:dnd-agent-efficiency
+```
+
+### Benchmark sources
+
+These benchmark results are from local corpora checked in under:
+
+- `_testing/mireglass_test`
+  - a small synthetic archive corpus used to probe ambiguity, aliasing, contradiction handling, and source diversification
+- `_testing/dnd_test`
+  - a larger PDF-heavy rules corpus containing:
+  - `phb.pdf`
+  - `PlayerDnDBasicRules_v0.2.pdf`
+  - `D&D 5e - DM's Basic Rules v 0.3.pdf`
+  - `Dungeon Master's Guide.pdf`
+
+The eval scripts are designed to be reproducible from the repo, not hand-scored screenshots or one-off demos.
+
+### Mireglass retrieval benchmark
+
+Command:
+
+```bash
+npm run eval:agent-efficiency
+```
+
+This benchmark compares:
+
+- a CLI-agent style baseline that uses lexical search plus targeted file reads
+- `search_context`
+- `deep_search_context`
+
+Latest Mireglass result:
+
+| Method | Avg quality | Avg efficiency | Avg latency | Avg chars | Avg commands | Quality wins | Efficiency wins |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| `cli_baseline` | `0.352` | `0.117` | `32.8 ms` | `2466.5` | `4.00` | `0/8` | `0/8` |
+| `search_context` | `0.687` | `0.493` | `564.0 ms` | `8811.5` | `1.00` | `3/8` | `6/8` |
+| `deep_search_context` | `0.722` | `0.436` | `1633.4 ms` | `9019.8` | `1.00` | `5/8` | `2/8` |
+
+Quality bar chart:
 
-On the current Mireglass benchmark corpus, the latest comparative run produced:
+```text
+cli_baseline        0.352  #######
+search_context      0.687  ##############
+deep_search_context 0.722  ##############
+```
+
+Efficiency bar chart:
+
+```text
+cli_baseline        0.117  ##
+search_context      0.493  ##########
+deep_search_context 0.436  #########
+```
 
-- `deep`: `69.2` average score
-- `grep`: `65.67` average score
-- `shallow`: `65.09` average score
+Takeaway:
+
+- `deep_search_context` was best on archive-style answer quality
+- `search_context` was usually the best default on efficiency
+- the CLI baseline needed more tool steps and still produced weaker evidence bundles
 
 The adversarial eval also showed that the current deep path reduced known noise-file leakage the most in this corpus.
 
+### D&D corpus benchmark
+
+Command:
+
+```bash
+npm run eval:dnd-agent-efficiency
+```
+
+This benchmark compares:
+
+- `cli_extract_cold`
+  - a realistic CLI-agent baseline that extracts PDF text fresh for each question, then does lexical ranking and excerpt selection
+- `cli_extract_warm`
+  - the same baseline with the extracted corpus already in memory
+- `search_context`
+- `deep_search_context`
+
+Latest D&D result:
+
+| Method | Avg quality | Avg efficiency | Avg latency | Avg chars | Avg commands | Quality wins | Efficiency wins |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| `cli_extract_cold` | `0.605` | `0.129` | `4850.7 ms` | `3692.8` | `4.00` | `0/6` | `0/6` |
+| `cli_extract_warm` | `0.605` | `0.318` | `25.5 ms` | `3692.8` | `4.00` | `0/6` | `0/6` |
+| `search_context` | `0.864` | `0.717` | `665.2 ms` | `9577.3` | `1.00` | `5/6` | `5/6` |
+| `deep_search_context` | `0.880` | `0.716` | `1615.3 ms` | `7978.3` | `1.00` | `1/6` | `1/6` |
+
+Quality bar chart:
+
+```text
+cli_extract_cold    0.605  ############
+cli_extract_warm    0.605  ############
+search_context      0.864  #################
+deep_search_context 0.880  ##################
+```
+
+Efficiency bar chart:
+
+```text
+cli_extract_cold    0.129  ###
+cli_extract_warm    0.318  ######
+search_context      0.717  ##############
+deep_search_context 0.716  ##############
+```
+
+Takeaway:
+
+- on a larger PDF-heavy rules corpus, `search_context` was the best default for agent efficiency
+- `deep_search_context` was slightly stronger on raw quality but usually not enough to justify the extra latency on straightforward rules questions
+- even a warmed CLI extraction baseline was materially worse for grounded retrieval quality than the indexed search layer
+
+### Trust notes
+
+These numbers are useful, but they are not universal truths.
+
+- The benchmark corpora are local and finite.
+- The scoring functions are explicit in the scripts and can be inspected or changed.
+- The D&D benchmark favors grounded rules retrieval, not open-ended generation quality.
+- The Mireglass benchmark favors multi-document archive reasoning and contradiction handling.
+- For a new corpus, you should treat these as reference evals and add your own benchmark set before making strong deployment claims.
+
 ## Limitations
 
 This package is deploy-ready for text-first corpora, but it is not universal document intelligence.

package/dist/agent-install-DXYYHX4V.js

@@ -0,0 +1,148 @@
+import {
+  OwnSearchError
+} from "./chunk-GDUOZGEP.js";
+
+// src/agent-install.ts
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { execFile as execFileCallback } from "child_process";
+import { promisify } from "util";
+import TOML from "@iarna/toml";
+var execFile = promisify(execFileCallback);
+var OWNSEARCH_STDIO_CONFIG = {
+  command: "ownsearch",
+  args: ["serve-mcp"]
+};
+function getJsonServerConfig() {
+  return {
+    command: OWNSEARCH_STDIO_CONFIG.command,
+    args: OWNSEARCH_STDIO_CONFIG.args
+  };
+}
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+async function readJsonFile(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeJsonFile(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+async function mergeJsonServerFile(filePath, topLevelKey) {
+  const parsed = await readJsonFile(filePath);
+  const next = { ...parsed };
+  const existingServers = isRecord(next[topLevelKey]) ? { ...next[topLevelKey] } : {};
+  existingServers.ownsearch = getJsonServerConfig();
+  next[topLevelKey] = existingServers;
+  await writeJsonFile(filePath, next);
+  return {
+    agent: "cursor",
+    method: "file-merge",
+    targetPath: filePath,
+    summary: `Updated ${filePath} and merged OwnSearch into ${topLevelKey}.`
+  };
+}
+async function installCodexConfig() {
+  const configPath = path.join(os.homedir(), ".codex", "config.toml");
+  await ensureDir(path.dirname(configPath));
+  let parsed = {};
+  try {
+    const raw = await fs.readFile(configPath, "utf8");
+    parsed = TOML.parse(raw);
+  } catch {
+    parsed = {};
+  }
+  const mcpServers = isRecord(parsed.mcp_servers) ? { ...parsed.mcp_servers } : {};
+  mcpServers.ownsearch = {
+    command: OWNSEARCH_STDIO_CONFIG.command,
+    args: OWNSEARCH_STDIO_CONFIG.args
+  };
+  parsed.mcp_servers = mcpServers;
+  await fs.writeFile(configPath, TOML.stringify(parsed), "utf8");
+  return {
+    agent: "codex",
+    method: "file-merge",
+    targetPath: configPath,
+    summary: `Updated ${configPath} and merged OwnSearch into [mcp_servers].`
+  };
+}
+async function installVsCodeConfig(agent) {
+  const payload = JSON.stringify({
+    name: "ownsearch",
+    command: OWNSEARCH_STDIO_CONFIG.command,
+    args: OWNSEARCH_STDIO_CONFIG.args
+  });
+  const commands = process.platform === "win32" ? ["code.cmd", "code"] : ["code"];
+  let lastError;
+  for (const command of commands) {
+    try {
+      await execFile(command, ["--add-mcp", payload], {
+        windowsHide: true
+      });
+      return {
+        agent,
+        method: "cli",
+        command,
+        summary: `Added OwnSearch to VS Code via \`${command} --add-mcp\`.`
+      };
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw new OwnSearchError(
+    "Could not add OwnSearch to VS Code automatically because the `code` CLI was not found. Install the VS Code shell command or use `ownsearch print-agent-config vscode`."
+  );
+}
+async function installContinueConfig() {
+  const filePath = path.join(os.homedir(), ".continue", "mcpServers", "ownsearch.json");
+  await writeJsonFile(filePath, {
+    mcpServers: {
+      ownsearch: getJsonServerConfig()
+    }
+  });
+  return {
+    agent: "continue",
+    method: "file-merge",
+    targetPath: filePath,
+    summary: `Wrote Continue MCP config to ${filePath}.`
+  };
+}
+async function installAgentConfig(agent) {
+  switch (agent) {
+    case "codex":
+      return installCodexConfig();
+    case "vscode":
+    case "github-copilot":
+      return installVsCodeConfig(agent);
+    case "cursor": {
+      const result = await mergeJsonServerFile(path.join(os.homedir(), ".cursor", "mcp.json"), "mcpServers");
+      return { ...result, agent: "cursor" };
+    }
+    case "windsurf": {
+      const result = await mergeJsonServerFile(path.join(os.homedir(), ".codeium", "mcp_config.json"), "mcpServers");
+      return { ...result, agent: "windsurf" };
+    }
+    case "copilot-cli": {
+      const result = await mergeJsonServerFile(path.join(os.homedir(), ".copilot", "mcp-config.json"), "mcpServers");
+      return { ...result, agent: "copilot-cli" };
+    }
+    case "continue":
+      return installContinueConfig();
+    default:
+      throw new OwnSearchError(`Automatic MCP installation is not supported for ${agent}.`);
+  }
+}
+export {
+  installAgentConfig
+};

package/dist/cli.js

@@ -26,21 +26,22 @@ loadOwnSearchEnv();
 var program = new Command();
 var PACKAGE_NAME = "ownsearch";
 var GEMINI_API_KEY_URL = "https://aistudio.google.com/apikey";
-var DOCKER_DESKTOP_WINDOWS_URL = "https://docs.docker.com/desktop/setup/install/windows-install/";
 var DOCKER_DESKTOP_OVERVIEW_URL = "https://docs.docker.com/desktop/";
+var DOCKER_DESKTOP_WINDOWS_URL = "https://docs.docker.com/desktop/setup/install/windows-install/";
+var DOCKER_DESKTOP_MAC_URL = "https://docs.docker.com/desktop/setup/install/mac-install/";
+var DOCKER_ENGINE_LINUX_URL = "https://docs.docker.com/engine/install/";
 var BUNDLED_SKILL_NAME = "ownsearch-rag-search";
-var SUPPORTED_AGENTS = [
+var SHOULD_SHOW_PROGRESS = process.stderr.isTTY;
+var PACKAGE_VERSION = "0.1.8";
+var AUTO_INSTALL_AGENTS = /* @__PURE__ */ new Set([
   "codex",
-  "claude-desktop",
   "continue",
   "copilot-cli",
   "cursor",
   "github-copilot",
   "vscode",
   "windsurf"
-];
-var SHOULD_SHOW_PROGRESS = process.stderr.isTTY;
-var PACKAGE_VERSION = "0.1.5";
+]);
 function requireGeminiKey() {
   if (!process.env.GEMINI_API_KEY) {
     throw new OwnSearchError("Set GEMINI_API_KEY before running OwnSearch.");
@@ -53,8 +54,26 @@ function progress(message, enabled = SHOULD_SHOW_PROGRESS) {
   process.stderr.write(`${message}
 `);
 }
+function getDockerInstallLabel() {
+  if (process.platform === "win32") {
+    return "Windows install";
+  }
+  if (process.platform === "darwin") {
+    return "macOS install";
+  }
+  return "Linux install";
+}
+function getDockerInstallUrl() {
+  if (process.platform === "win32") {
+    return DOCKER_DESKTOP_WINDOWS_URL;
+  }
+  if (process.platform === "darwin") {
+    return DOCKER_DESKTOP_MAC_URL;
+  }
+  return DOCKER_ENGINE_LINUX_URL;
+}
 async function loadDockerModule() {
-  return import("./docker-YQNVOH2N.js");
+  return import("./docker-T4PNVYXI.js");
 }
 async function loadGeminiModule() {
   return import("./gemini-VERDPJ32.js");
@@ -74,6 +93,15 @@ async function loadContextModule() {
 async function loadRetrievalModule() {
   return import("./retrieval-ZCY6DDUD.js");
 }
+async function loadAgentInstallModule() {
+  return import("./agent-install-DXYYHX4V.js");
+}
+function isAutoInstallAgent(agent) {
+  return AUTO_INSTALL_AGENTS.has(agent);
+}
+function isInstallableAgentName(agent) {
+  return AUTO_INSTALL_AGENTS.has(agent);
+}
 function buildAgentConfig(agent) {
   const stdioConfig = {
     command: PACKAGE_NAME,
@@ -190,12 +218,18 @@ async function promptForGeminiKey() {
     output: process.stdout
   });
   try {
-    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()}`);
+    console.log("OwnSearch needs a Gemini API key for indexing and search.");
+    console.log("Gemini API usage is governed by Google's current free-tier limits, quotas, and pricing.");
+    console.log("");
+    console.log("Next step:");
+    console.log("  1. OwnSearch will open Google AI Studio in your browser.");
+    console.log("  2. You create or copy a Gemini API key there.");
+    console.log(`  3. You paste the key here, and OwnSearch saves it to ${getEnvPath()}.`);
+    console.log("");
+    console.log(`AI Studio URL: ${GEMINI_API_KEY_URL}`);
+    await rl.question("Press Enter when you are ready for OwnSearch to open AI Studio: ");
     openGeminiKeyPage();
-    await rl.question("Press Enter after the AI Studio page is open and you are ready to paste the key: ");
+    await rl.question("Press Enter after AI Studio is open and you have copied the key: ");
     for (; ; ) {
       const apiKey = (await rl.question("Paste GEMINI_API_KEY and press Enter (Ctrl+C to cancel): ")).trim();
       if (!apiKey) {
@@ -317,14 +351,14 @@ function printSetupNextSteps() {
   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("  7. Let OwnSearch install MCP config for a supported agent:");
+  console.log("     ownsearch install-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_URL}`);
+  console.log("  OwnSearch requires Docker so it can run Qdrant locally.");
+  console.log(`  ${getDockerInstallLabel()}: ${getDockerInstallUrl()}`);
   console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL}`);
 }
 function printAgentSetupNextSteps() {
@@ -340,12 +374,12 @@ function printAgentSetupNextSteps() {
   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("  Print MCP config for the host agent:");
-  console.log("    ownsearch print-agent-config codex");
+  console.log("  Let OwnSearch install MCP config automatically:");
+  console.log("    ownsearch install-agent-config codex");
   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_URL}`);
+  console.log("  OwnSearch requires Docker so it can run Qdrant locally.");
+  console.log(`  ${getDockerInstallLabel()}: ${getDockerInstallUrl()}`);
   console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL}`);
 }
 async function promptForAgentChoice() {
@@ -431,12 +465,63 @@ function printAgentConfigSnippet(agent) {
     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\`.`);
+    if (isAutoInstallAgent(agent)) {
+      console.log(`To let OwnSearch install this automatically, run \`ownsearch install-agent-config ${agent}\`.`);
+    }
+  }
+}
+function printAgentInstallSummary(result) {
+  console.log("");
+  console.log(`OwnSearch installed MCP config for ${result.agent}`);
+  console.log(`  Result: ${result.summary}`);
+  if (result.targetPath) {
+    console.log(`  Config path: ${result.targetPath}`);
+  }
+  if (result.command) {
+    console.log(`  Installer command: ${result.command}`);
+  }
+  console.log("  MCP guidance is built in:");
+  console.log("    resource: ownsearch://skills/retrieval");
+  console.log("    prompt: ownsearch-retrieval-guide");
+  console.log("    tool fallback: get_retrieval_skill");
+}
+async function maybeInstallAgentConfig(agent) {
+  if (!isAutoInstallAgent(agent) || !process.stdin.isTTY || !process.stdout.isTTY) {
+    printAgentConfigSnippet(agent);
+    return;
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    console.log("");
+    console.log(`OwnSearch can install the MCP server for ${agent} automatically without removing other MCP servers.`);
+    const answer = (await rl.question("Install it now? [Y/n]: ")).trim().toLowerCase();
+    if (answer === "n" || answer === "no") {
+      printAgentConfigSnippet(agent);
+      return;
+    }
+  } finally {
+    rl.close();
+  }
+  try {
+    progress(`OwnSearch setup: installing MCP config for ${agent}...`);
+    const { installAgentConfig } = await loadAgentInstallModule();
+    const result = await installAgentConfig(agent);
+    printAgentInstallSummary(result);
+  } catch (error) {
+    console.log("");
+    console.log(`OwnSearch could not install MCP config for ${agent} automatically.`);
+    console.log(error instanceof Error ? error.message : String(error));
+    printAgentConfigSnippet(agent);
   }
 }
 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_URL}`);
+  console.log(`  ${getDockerInstallLabel()}: ${getDockerInstallUrl()}`);
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL}`);
   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"})`);
@@ -448,16 +533,27 @@ function printSetupSummary(input) {
   } else {
     console.log("  Gemini API key: missing");
   }
+  console.log("  MCP guidance:");
+  console.log("    OwnSearch exposes a retrieval resource, prompt, and fallback tool so attached agents can learn the correct retrieval workflow immediately.");
+  console.log("    resource: ownsearch://skills/retrieval");
+  console.log("    prompt: ownsearch-retrieval-guide");
+  console.log("    tool fallback: get_retrieval_skill");
 }
 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_URL}`);
+  console.log(`  ${getDockerInstallLabel()}: ${getDockerInstallUrl()}`);
+  console.log(`  Docker docs: ${DOCKER_DESKTOP_OVERVIEW_URL}`);
   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"}`);
+  console.log("  MCP guidance is built in:");
+  console.log("    resource: ownsearch://skills/retrieval");
+  console.log("    prompt: ownsearch-retrieval-guide");
+  console.log("    tool fallback: get_retrieval_skill");
+  console.log("  Attached agents should load the resource or prompt first, then use literal_search, search_context, or deep_search_context as needed.");
 }
 program.name("ownsearch").description("Gemini-powered local search MCP server backed by Qdrant.").version(PACKAGE_VERSION);
 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) => {
@@ -496,7 +592,7 @@ program.command("setup").description("Create config and start a local Qdrant Doc
     printSetupNextSteps();
     const agent = await promptForAgentChoice();
     if (agent) {
-      printAgentConfigSnippet(agent);
+      await maybeInstallAgentConfig(agent);
     }
   }
 });
@@ -651,17 +747,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.").option("--json", "Print the full machine-readable payload").action(async (agent, options) => {
-  if (SUPPORTED_AGENTS.includes(agent)) {
-    const payload = buildAgentConfig(agent);
-    if (options.json) {
-      console.log(JSON.stringify(payload, null, 2));
-      return;
-    }
-    printAgentConfigSnippet(agent);
-    return;
-  }
-  throw new OwnSearchError(`Unsupported agent: ${agent}`);
+program.command("install-agent-config").argument("<agent>", [...AUTO_INSTALL_AGENTS].join(" | ")).description("Safely install OwnSearch into a supported agent MCP config without removing other MCP servers.").action(async (agent) => {
+  if (!isInstallableAgentName(agent)) {
+    throw new OwnSearchError(`Automatic MCP installation is not supported for ${agent}.`);
+  }
+  progress(`OwnSearch: installing MCP config for ${agent}...`);
+  const { installAgentConfig } = await loadAgentInstallModule();
+  const result = await installAgentConfig(agent);
+  printAgentInstallSummary(result);
 });
 program.command("print-skill").argument("[skill]", `Bundled skill name (default ${BUNDLED_SKILL_NAME})`).description("Print a bundled OwnSearch skill that helps agents query retrieval tools more effectively.").action(async (skill) => {
   const skillName = skill?.trim() || BUNDLED_SKILL_NAME;