docdex 0.2.23 → 0.2.25

package/assets/agents.md

@@ -1,3 +1,16 @@
+---- START OF DOCDEX INFO V0.2.25 ----
+Docdex URL: http://127.0.0.1:28491
+Use this base URL for Docdex HTTP endpoints.
+
+## Priority Directives (Mandatory)
+
+- Always use both memory lobes early: docdex_get_profile + docdex_memory_recall; save new facts via docdex_memory_save and new preferences via docdex_save_preference.
+- Maintain agent-specific profile memory: use your agent_id with docdex_get_profile/docdex_save_preference; store generic self-knowledge (role, tooling, preferences).
+- Use impact analysis for every code change: call HTTP /v1/graph/impact?file=... and account for inbound/outbound deps; if unavailable, state it and proceed cautiously.
+- Apply DAG reasoning for planning: prefer dependency graph facts (impact results and /v1/dag/export) to choose the right change order and scope.
+- Use Docdex tools intentionally: docdex_search/symbols/ast for repo truth; docdex_stats/files/repo_inspect/index for index health.
+- When you do not know something, run docdex_web_research (force_web=true). Web research is encouraged by default for non-repo facts and external APIs.
+
 # Docdex Agent Usage Instructions
 
 > Context for AI Agents: Docdex is your local-first Dual-Lobe Memory and Code Intelligence daemon. Unlike simple vector stores, it provides structural understanding of code (AST/Graph), persistent behavioral profiles (Agent Memory), and gated web enrichment, all strictly scoped to the local machine.
@@ -33,6 +46,7 @@ Docdex v2.1 introduces a strict separation between "facts" and "preferences." Us
 - Content: Your persona, user preferences, coding style, tooling constraints.
 - Example: "Always use Zod for validation," or "User prefers strict TypeScript types."
 - Tools: docdex_save_preference, docdex_get_profile
+- Agent-specific: Each agent should use its own agent_id and store generic self-knowledge (role, tooling, preferences).
 - Usage: Use this to "learn" from corrections. If a user corrects your style, save it here so you do not repeat the mistake in a different repo.
 
 ## Tool Capabilities (MCP & HTTP)
@@ -46,20 +60,6 @@ Standard retrieval. The daemon automatically handles the waterfall (Local -> Web
 | docdex_search | Search code, docs, and ingested libraries. Returns ranked snippets. |
 | docdex_web_research | Explicitly trigger Tier 2 web discovery (DDG + Headless Chrome). Use when you need external docs not present locally. |
 
-Tier 2 discovery providers (in fallback order when DDG HTML fails or is blocked):
-- DuckDuckGo Lite
-- SearXNG JSON (public instance or self-hosted)
-- Google Mobile
-- Brave Search API (requires DOCDEX_BRAVE_API_KEY)
-- Google Custom Search JSON API (requires DOCDEX_GOOGLE_CSE_API_KEY + DOCDEX_GOOGLE_CSE_CX)
-- Bing Web Search API (requires DOCDEX_BING_API_KEY)
-- Tavily API (requires DOCDEX_TAVILY_API_KEY)
-- Exa API (requires DOCDEX_EXA_API_KEY)
-
-Defaults and overrides:
-- Default endpoints: `https://html.duckduckgo.com/html/`, `https://lite.duckduckgo.com/lite/`, `https://searx.be/search` (built-in fallback list), `https://www.google.com/m`, `https://api.search.brave.com/res/v1/web/search`, `https://www.googleapis.com/customsearch/v1`, `https://api.bing.microsoft.com/v7.0/search`, `https://api.tavily.com/search`, `https://api.exa.ai/search`
-- Override envs: `DOCDEX_DDG_BASE_URL`, `DOCDEX_WEB_SEARXNG_URLS` (comma list, or `DOCDEX_SEARXNG_URLS`), `DOCDEX_WEB_GOOGLE_MOBILE_URL`, `DOCDEX_BRAVE_API_KEY` + `DOCDEX_BRAVE_API_URL`, `DOCDEX_GOOGLE_CSE_API_KEY` + `DOCDEX_GOOGLE_CSE_CX` + `DOCDEX_GOOGLE_CSE_API_URL`, `DOCDEX_BING_API_KEY` + `DOCDEX_BING_API_URL`, `DOCDEX_TAVILY_API_KEY` + `DOCDEX_TAVILY_API_URL`, `DOCDEX_EXA_API_KEY` + `DOCDEX_EXA_API_URL`
-
 ### B. Code Intelligence (AST & Graph)
 
 Precision tools for structural analysis. Do not rely on text search for definitions or dependencies.
@@ -70,6 +70,7 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 | docdex_ast | Specific AST nodes (e.g., "Find all class definitions"). |
 | docdex_impact_diagnostics | Check for broken/dynamic imports. |
 | HTTP /v1/graph/impact | Impact Analysis: "What breaks if I change this?" Returns inbound/outbound dependencies. |
+| HTTP /v1/dag/export | Export the dependency DAG for change ordering and scope. |
 
 ### C. Memory Operations
 
@@ -80,6 +81,47 @@ Precision tools for structural analysis. Do not rely on text search for definiti
 | docdex_save_preference | Store a global user preference (Style, Tooling, Constraint). |
 | docdex_get_profile | Retrieve global preferences. |
 
+### D. Local Delegation (Cheap Models)
+
+Use local delegation for low-complexity, code-generation-oriented tasks to reduce paid-model usage.
+
+| MCP Tool / HTTP | Purpose |
+| --- | --- |
+| docdex_local_completion | Delegate small tasks to a local model with strict output formats. |
+| HTTP /v1/delegate | HTTP endpoint for delegated completions with structured responses. |
+
+Required fields: `task_type`, `instruction`, `context`. Optional: `max_tokens`, `timeout_ms`, `mode` (`draft_only` or `draft_then_refine`), `agent` (local agent id/slug).
+Expensive model library: `docs/expensive_models.json` (match by `agent_id`, `agent_slug`, `model`, or adapter type; case-insensitive).
+
+### E. Index Health + File Access
+
+Use these to verify index coverage, repo binding, and to read precise file slices.
+
+| MCP Tool | Purpose |
+| --- | --- |
+| docdex_repo_inspect | Confirm normalized repo root/identity (resolve missing_repo). |
+| docdex_stats | Index size/last update; detect stale indexes. |
+| docdex_files | Indexed file coverage; confirm a file is in the index. |
+| docdex_index | Reindex full repo or ingest specific files when stale/missing. |
+| docdex_open | Read exact file slices after you identify targets. |
+
+## Quick Tool Map (Often Missed)
+
+- docdex_files: List indexed docs with rel_path/doc_id/token_estimate; use to verify indexing coverage.
+- docdex_stats: Show index size, state dir, and last update time.
+- docdex_repo_inspect: Confirm normalized repo root and repo identity mapping.
+- docdex_index: Reindex the full repo or ingest specific files when stale.
+- docdex_search diff: Limit search to working tree, staged, or ref ranges; filter by paths.
+- docdex_web_research knobs: force_web, skip_local_search, repo_only, no_cache, web_limit, llm_filter_local_results, llm_model.
+- docdex_open: Read narrow file slices after targets are identified.
+- docdex_impact_diagnostics: Scan dynamic imports when imports are unclear or failing.
+- docdex_local_completion: Delegate low-complexity codegen tasks (tests, docstrings, boilerplate, simple refactors).
+- docdex_ast: Use AST queries for precise structure (class/function definitions, call sites, imports).
+- docdex_symbols: Use symbols to confirm exact signatures/locations before edits.
+- HTTP /v1/graph/impact: Mandatory before code changes to review inbound/outbound deps.
+- HTTP /v1/dag/export: Export dependency graph to plan change order.
+- HTTP /v1/initialize: Bind a default repo root for MCP when clients omit project_root.
+
 ## Interaction Patterns
 
 ### 1. Reasoning Workflow
@@ -89,9 +131,76 @@ When answering a complex coding query, follow this "Reasoning Trace":
 1. Retrieve Profile: Call docdex_get_profile to load user style/constraints (e.g., "Use functional components").
 2. Search Code: Call docdex_search or docdex_symbols to find the relevant code.
 3. Check Memory: Call docdex_memory_recall for project-specific caveats (e.g., "Auth logic was refactored last week").
-4. Synthesize: Generate code that matches the Repo Truth while adhering to the Profile Style.
+4. Validate structure: Use docdex_ast/docdex_symbols to confirm targets before editing.
+5. Read context: Use docdex_open to fetch minimal file slices after locating targets.
+6. Plan with DAG: Use /v1/dag/export or /v1/graph/impact to order changes by dependencies.
+7. Synthesize: Generate code that matches the Repo Truth while adhering to the Profile Style.
+
+### 2. Memory Capture (Mandatory)
+
+Save more memories for both lobes during the task, not just at the end.
+
+1. Repo memory: After each meaningful discovery or code change, save at least one durable fact (file location, behavior, config, gotcha) via `docdex_memory_save`.
+2. Profile memory: When the user expresses a preference, constraint, or workflow correction, call `docdex_save_preference` immediately with the right category.
+3. Keep it crisp: 1-3 short sentences, include file paths when relevant, avoid raw code blobs.
+4. Safety: Never store secrets, tokens, or sensitive user data. Skip transient or speculative info.
+
+### 3. Index Health + Diff-Aware Search (Mandatory)
 
-### 2. Handling Corrections (Learning)
+Use these when results look incomplete or when the task is about recent changes.
+
+1. Confirm repo binding: Use docdex_repo_inspect or /v1/initialize when repo_id is missing/ambiguous.
+2. Check index coverage: Use docdex_stats + docdex_files before assuming code is missing.
+3. Reindex if needed: Run docdex_index (or advise it) when stale_index/missing files appear.
+4. Use diff search: For change-specific tasks, use docdex_search with diff mode (working tree/staged/range).
+
+### 4. Local Delegation Workflow (Cheap Models)
+
+When you are an expensive/paid model, delegate eligible low-complexity tasks first unless the user opts out.
+Delegation is mandatory for eligible tasks. If you are expensive and delegation is enabled (explicitly or auto-enabled with local candidates), you MUST attempt local delegation before doing the work yourself. Only skip when delegation is disabled, no local candidate exists, or local output fails validation after a retry/fallback.
+
+#### Mandatory Delegation Triggers
+
+- The work fits a delegation task type or can be split into sub-tasks that do.
+- The change is small, localized, or mechanical (boilerplate, formatting, docstrings, small refactors).
+- The task can be fully expressed in a capsule with explicit context and output rules.
+
+#### Reasons to Delegate (Non-Optional)
+
+- Cuts paid-token usage and cost.
+- Lowers latency and avoids rate-limit pressure on premium models.
+- Keeps expensive models focused on complex reasoning and multi-step planning.
+- Uses tuned prompts that reduce drift for repetitive edits.
+- Enforces the product's cost-control policy; skipping delegation is a regression.
+
+1. Determine if you are expensive: load `docs/expensive_models.json` and match your `agent_id`, `agent_slug`, `model`, or adapter type. If you match, continue; if not and you are clearly local/cheap, skip delegation. If unsure, default to expensive.
+2. Check config: Only delegate when `[llm.delegation].enabled` is true or `auto_enable` is true with an eligible local model/agent (and `task_type` is allowed). If uncertain, attempt delegation and handle the error.
+3. Choose task type: Use one of `GENERATE_TESTS`, `WRITE_DOCSTRING`, `SCAFFOLD_BOILERPLATE`, `REFACTOR_SIMPLE`, `FORMAT_CODE`.
+4. Call the tool: `docdex_local_completion` with `task_type`, `instruction`, and minimal `context` (smallest necessary snippet).
+5. Validate output: If the local output is invalid or empty, fall back to the primary agent or handle with the paid model.
+6. Optional refine: If mode is `draft_then_refine`, refine the draft with the primary agent and return a final result.
+
+#### Delegation Handoff Package (Required)
+
+Local models cannot call tools. The leading agent must provide a complete, minimal capsule.
+
+1. Task capsule: `task_type`, goal, success criteria, output format, and constraints (tests to update, style rules).
+2. Context payload: file paths plus the exact snippets from docdex_open; include symbol signatures/AST findings.
+3. Dependency notes: summarize impact analysis and any DAG ordering that affects the change.
+4. Boundaries: explicit files allowed to edit vs read-only; no new dependencies unless allowed.
+5. Guardrails: ask for clarification if context is insufficient; do not invent missing APIs; return only the requested format.
+
+### 5. Graph + AST Usage (Mandatory for Code Changes)
+
+For any code change, use both AST and graph tools to reduce drift and hidden coupling.
+
+1. Use `docdex_ast` or `docdex_symbols` to locate exact definitions and call sites.
+2. Call HTTP `/v1/graph/impact?file=...` before edits and summarize inbound/outbound deps.
+3. For multi-file changes, export the DAG (`/v1/dag/export`) and order edits by dependency direction.
+4. Use docdex_impact_diagnostics when imports are dynamic or unresolved.
+5. If graph endpoints are unavailable, state it and proceed cautiously with extra local search.
+
+### 6. Handling Corrections (Learning)
 
 If the user says: "I told you, we do not use Moment.js here, use date-fns!"
 
@@ -100,13 +209,28 @@ If the user says: "I told you, we do not use Moment.js here, use date-fns!"
 - content: "Do not use Moment.js; prefer date-fns."
 - agent_id: "default" (or active agent ID)
 
-### 3. Impact Analysis
+### 7. Impact Analysis
 
 If the user asks: "Safe to delete getUser?"
 
 - Action: Call GET /v1/graph/impact?file=src/user.ts
 - Output: Analyze the inbound edges. If the list is not empty, it is unsafe.
 
+### 8. Non-Repo Real-World Queries (Web First)
+
+If the user asks a non-repo, real-world question (weather, news, general facts), immediately call docdex_web_research with force_web=true.
+- Resolve relative dates ("yesterday", "last week") using system time by default.
+- Do not run docdex_search unless the user explicitly wants repo-local context.
+- Assume web access is allowed unless the user forbids it; if the web call fails, report the failure and ask for a source or permission.
+
+### 9. Failure Handling (Missing Results or Errors)
+
+- Ensure project_root or repo_path is set, or call /v1/initialize to bind a default root.
+- Use docdex_repo_inspect to confirm repo identity and normalized root.
+- Use docdex_stats and docdex_files to check whether the index exists and contains files.
+- Reindex with docdex_index (or docdexd index) if the index is stale or empty.
+- Add a repo-local .docdexignore for large generated artifacts or local caches when indexing is slow.
+
 ## Operational Context
 
 ### Repository Identification
@@ -129,3 +253,4 @@ Docdex adapts to the host.
 
 - Project Mapping: On constrained hardware, docdex uses a "Spotlight Heuristic" to show you only a skeletal file tree based on your role keywords, rather than the full file system.
 - LLM: It may be running a quantized model (e.g., phi3.5) or a heavy model (llama3.1:70b) depending on VRAM. Trust the daemon's token limits; it handles truncation.
+---- END OF DOCDEX INFO -----

package/lib/postinstall_setup.js

@@ -26,6 +26,7 @@ const SETUP_PENDING_MARKER = "setup_pending.json";
 const AGENTS_DOC_FILENAME = "agents.md";
 const DOCDEX_INFO_START_PREFIX = "---- START OF DOCDEX INFO V";
 const DOCDEX_INFO_END = "---- END OF DOCDEX INFO -----";
+const DOCDEX_INFO_END_LEGACY = "---- END OF DOCDEX INFO ----";
 
 function defaultConfigPath() {
   return path.join(os.homedir(), ".docdex", "config.toml");
@@ -353,9 +354,14 @@ function docdexBlockStart(version) {
   return `${DOCDEX_INFO_START_PREFIX}${version} ----`;
 }
 
+function docdexInfoEndPattern() {
+  return `(?:${escapeRegExp(DOCDEX_INFO_END)}|${escapeRegExp(DOCDEX_INFO_END_LEGACY)})`;
+}
+
 function buildDocdexInstructionBlock(instructions) {
   const next = normalizeInstructionText(instructions);
   if (!next) return "";
+  if (hasDocdexBlock(next)) return next;
   const version = resolvePackageVersion();
   return `${docdexBlockStart(version)}\n${next}\n${DOCDEX_INFO_END}`;
 }
@@ -363,9 +369,7 @@ function buildDocdexInstructionBlock(instructions) {
 function extractDocdexBlockBody(text) {
   const match = String(text || "").match(
     new RegExp(
-      `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n([\\s\\S]*?)\\r?\\n${escapeRegExp(
-        DOCDEX_INFO_END
-      )}`
+      `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n([\\s\\S]*?)\\r?\\n${docdexInfoEndPattern()}`
     )
   );
   return match ? normalizeInstructionText(match[1]) : "";
@@ -383,11 +387,17 @@ function hasDocdexBlockVersion(text, version) {
   return String(text || "").includes(docdexBlockStart(version));
 }
 
+function hasDocdexBlock(text) {
+  const source = String(text || "");
+  return (
+    source.includes(DOCDEX_INFO_START_PREFIX) &&
+    (source.includes(DOCDEX_INFO_END) || source.includes(DOCDEX_INFO_END_LEGACY))
+  );
+}
+
 function stripDocdexBlocks(text) {
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
-      DOCDEX_INFO_END
-    )}\\r?\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${docdexInfoEndPattern()}\\r?\\n?`,
     "g"
   );
   return String(text || "").replace(re, "").trim();
@@ -397,9 +407,7 @@ function stripDocdexBlocksExcept(text, version) {
   if (!version) return stripDocdexBlocks(text);
   const source = String(text || "");
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${escapeRegExp(
-      DOCDEX_INFO_END
-    )}\\r?\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\r\\n]* ----\\r?\\n[\\s\\S]*?\\r?\\n${docdexInfoEndPattern()}\\r?\\n?`,
     "g"
   );
   let result = "";
@@ -432,7 +440,7 @@ function stripLegacyDocdexBody(text, body) {
   if (!body) return String(text || "");
   const source = String(text || "").replace(/\r\n/g, "\n");
   const re = new RegExp(
-    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\n]* ----\\n[\\s\\S]*?\\n${escapeRegExp(DOCDEX_INFO_END)}\\n?`,
+    `${escapeRegExp(DOCDEX_INFO_START_PREFIX)}[^\\n]* ----\\n[\\s\\S]*?\\n${docdexInfoEndPattern()}\\n?`,
     "g"
   );
   let result = "";
@@ -493,6 +501,18 @@ function upsertPromptFile(pathname, instructions, { prepend = false } = {}) {
   return writeTextFile(pathname, merged);
 }
 
+function removePromptFile(pathname) {
+  if (!fs.existsSync(pathname)) return false;
+  const current = fs.readFileSync(pathname, "utf8");
+  const stripped = stripDocdexBlocks(current);
+  if (normalizeInstructionText(stripped) === normalizeInstructionText(current)) return false;
+  if (!stripped) {
+    fs.unlinkSync(pathname);
+    return true;
+  }
+  return writeTextFile(pathname, stripped);
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -554,16 +574,10 @@ function upsertYamlInstruction(pathname, key, instructions) {
 }
 
 function upsertClaudeInstructions(pathname, instructions) {
-  const { value } = readJson(pathname);
-  if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
-  const merged = mergeInstructionText(value.instructions, instructions);
-  if (!merged || merged === value.instructions) return false;
-  value.instructions = merged;
-  writeJson(pathname, value);
-  return true;
+  return upsertPromptFile(pathname, instructions);
 }
 
-function upsertContinueInstructions(pathname, instructions) {
+function upsertContinueJsonInstructions(pathname, instructions) {
   const { value } = readJson(pathname);
   if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
   const merged = mergeInstructionText(value.systemMessage, instructions);
@@ -573,6 +587,198 @@ function upsertContinueInstructions(pathname, instructions) {
   return true;
 }
 
+function countLeadingWhitespace(line) {
+  const match = line.match(/^\s*/);
+  return match ? match[0].length : 0;
+}
+
+function isYamlTopLevelKey(line, baseIndent) {
+  const indent = countLeadingWhitespace(line);
+  if (indent > baseIndent) return false;
+  const trimmed = line.trimStart();
+  if (!trimmed || trimmed.startsWith("#") || trimmed.startsWith("-")) return false;
+  return trimmed.includes(":");
+}
+
+function hasYamlContent(lines) {
+  return lines.some((line) => {
+    const trimmed = line.trim();
+    return trimmed && !trimmed.startsWith("#");
+  });
+}
+
+function splitInlineYamlList(value) {
+  const trimmed = String(value || "").trim();
+  if (trimmed === "[]") return [];
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  const inner = trimmed.slice(1, -1);
+  const items = [];
+  let current = "";
+  let inSingle = false;
+  let inDouble = false;
+  let escaped = false;
+  for (const ch of inner) {
+    if (escaped) {
+      current += ch;
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\\\") {
+      escaped = true;
+      current += ch;
+      continue;
+    }
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      current += ch;
+      continue;
+    }
+    if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      current += ch;
+      continue;
+    }
+    if (ch === "," && !inSingle && !inDouble) {
+      const next = current.trim();
+      if (next) items.push(next);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  const next = current.trim();
+  if (next) items.push(next);
+  return items;
+}
+
+function inlineRulesToItems(value, itemIndent) {
+  const trimmed = String(value || "").trim();
+  if (!trimmed) return [];
+  const prefix = " ".repeat(itemIndent);
+  const split = splitInlineYamlList(trimmed);
+  if (split) {
+    return split.map((item) => [`${prefix}- ${item}`]).filter((item) => item[0].trim() !== `${prefix}-`);
+  }
+  return [[`${prefix}- ${trimmed}`]];
+}
+
+function buildYamlRuleBlock(itemIndent, instructions) {
+  const prefix = " ".repeat(itemIndent);
+  const contentPrefix = " ".repeat(itemIndent + 2);
+  const lines = [`${prefix}- |`];
+  for (const line of String(instructions).split(/\r?\n/)) {
+    lines.push(`${contentPrefix}${line}`);
+  }
+  return lines;
+}
+
+function rewriteContinueYamlRules(source, instructions, addDocdex) {
+  const lines = String(source || "").split(/\r?\n/);
+  const ruleLineRe = /^(\s*)rules\s*:(.*)$/;
+  let rulesIndex = -1;
+  let rulesIndent = 0;
+  let rulesInline = "";
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i].match(ruleLineRe);
+    if (!match) continue;
+    rulesIndex = i;
+    rulesIndent = match[1]?.length || 0;
+    rulesInline = (match[2] || "").trim();
+    if (rulesInline.includes("#")) {
+      rulesInline = rulesInline.split("#")[0].trim();
+    }
+    if (rulesInline.startsWith("#")) rulesInline = "";
+    break;
+  }
+
+  if (rulesIndex === -1) {
+    if (!addDocdex) return null;
+    const trimmed = String(source || "").trimEnd();
+    const docdexBlock = buildYamlRuleBlock(2, instructions);
+    const prefix = trimmed ? `${trimmed}\n\n` : "";
+    return `${prefix}rules:\n${docdexBlock.join("\n")}`;
+  }
+
+  let endIndex = lines.length;
+  for (let i = rulesIndex + 1; i < lines.length; i += 1) {
+    if (isYamlTopLevelKey(lines[i], rulesIndent)) {
+      endIndex = i;
+      break;
+    }
+  }
+  const blockLines = lines.slice(rulesIndex + 1, endIndex);
+  const preLines = [];
+  const items = [];
+  let currentItem = [];
+  let itemIndent = null;
+  let startedItems = false;
+
+  for (const line of blockLines) {
+    const trimmed = line.trimStart();
+    const indent = countLeadingWhitespace(line);
+    const isItem = trimmed.startsWith("-") && indent > rulesIndent;
+    if (isItem) {
+      if (itemIndent == null) itemIndent = indent;
+      if (indent === itemIndent) {
+        if (startedItems && currentItem.length) {
+          items.push(currentItem);
+          currentItem = [];
+        }
+        startedItems = true;
+      }
+      currentItem.push(line);
+      continue;
+    }
+    if (startedItems) {
+      currentItem.push(line);
+    } else {
+      preLines.push(line);
+    }
+  }
+  if (currentItem.length) items.push(currentItem);
+
+  const inferredIndent = itemIndent == null ? rulesIndent + 2 : itemIndent;
+  if (!items.length && rulesInline) {
+    items.push(...inlineRulesToItems(rulesInline, inferredIndent));
+    rulesInline = "";
+  }
+
+  const keptItems = items.filter((item) => {
+    const text = item.join("\n");
+    return !hasDocdexBlock(text);
+  });
+
+  if (addDocdex) {
+    keptItems.push(buildYamlRuleBlock(inferredIndent, instructions));
+  }
+
+  const removeRulesBlock =
+    !addDocdex && !keptItems.length && !hasYamlContent(preLines) && !rulesInline;
+
+  const output = [];
+  output.push(...lines.slice(0, rulesIndex));
+  if (!removeRulesBlock) {
+    output.push(`${" ".repeat(rulesIndent)}rules:`);
+    output.push(...preLines);
+    for (const item of keptItems) {
+      output.push(...item);
+    }
+  }
+  output.push(...lines.slice(endIndex));
+  const next = output.join("\n");
+  return next === source ? null : next;
+}
+
+function upsertContinueYamlRules(pathname, instructions) {
+  if (!fs.existsSync(pathname)) return false;
+  const normalized = normalizeInstructionText(instructions);
+  if (!normalized) return false;
+  const current = fs.readFileSync(pathname, "utf8");
+  const updated = rewriteContinueYamlRules(current, normalized, true);
+  if (!updated) return false;
+  return writeTextFile(pathname, updated);
+}
+
 function upsertZedInstructions(pathname, instructions) {
   const { value } = readJson(pathname);
   if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
@@ -586,12 +792,54 @@ function upsertZedInstructions(pathname, instructions) {
   return true;
 }
 
-function upsertVsCodeInstructions(pathname, instructionsPath) {
+function upsertVsCodeInstructionKey(value, key, instructions) {
+  const existing = typeof value[key] === "string" ? value[key] : "";
+  const merged = mergeInstructionText(existing, instructions);
+  if (!merged || merged === existing) return false;
+  value[key] = merged;
+  return true;
+}
+
+function removeVsCodeInstructionKey(value, key, instructions, { legacyPath } = {}) {
+  if (typeof value[key] !== "string") return false;
+  const current = value[key];
+  const stripped = stripDocdexBlocks(current);
+  if (normalizeInstructionText(stripped) !== normalizeInstructionText(current)) {
+    if (!stripped) {
+      delete value[key];
+    } else {
+      value[key] = stripped;
+    }
+    return true;
+  }
+  const normalized = normalizeInstructionText(instructions);
+  if (current === normalized || (legacyPath && current === legacyPath)) {
+    delete value[key];
+    return true;
+  }
+  return false;
+}
+
+function upsertVsCodeInstructions(pathname, instructions, legacyPath) {
   const { value } = readJson(pathname);
   if (typeof value !== "object" || value == null || Array.isArray(value)) return false;
-  const key = "copilot.chat.codeGeneration.instructions";
-  if (value[key] === instructionsPath) return false;
-  value[key] = instructionsPath;
+  const normalized = normalizeInstructionText(instructions);
+  if (!normalized) return false;
+  let updated = false;
+  if (upsertVsCodeInstructionKey(value, "chat.instructions", instructions)) {
+    updated = true;
+  }
+  if (removeVsCodeInstructionKey(value, "github.copilot.chat.codeGeneration.instructions", instructions)) {
+    updated = true;
+  }
+  if (
+    removeVsCodeInstructionKey(value, "copilot.chat.codeGeneration.instructions", instructions, {
+      legacyPath
+    })
+  ) {
+    updated = true;
+  }
+  if (!updated) return false;
   writeJson(pathname, value);
   return true;
 }
@@ -921,21 +1169,38 @@ function clientInstructionPaths() {
   const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
   const userProfile = process.env.USERPROFILE || home;
   const vscodeGlobalInstructions = path.join(home, ".vscode", "global_instructions.md");
+  const vscodeInstructionsDir = path.join(home, ".vscode", "instructions");
+  const vscodeInstructionsFile = path.join(vscodeInstructionsDir, "docdex.md");
+  const continueRoot = path.join(userProfile, ".continue");
+  const continueJson = path.join(continueRoot, "config.json");
+  const continueYaml = path.join(continueRoot, "config.yaml");
+  const continueYml = path.join(continueRoot, "config.yml");
   const windsurfGlobalRules = path.join(userProfile, ".codeium", "windsurf", "memories", "global_rules.md");
   const rooRules = path.join(home, ".roo", "rules", "docdex.md");
   const pearaiAgent = path.join(home, ".config", "pearai", "agent.md");
   const aiderConfig = path.join(home, ".aider.conf.yml");
   const gooseConfig = path.join(home, ".config", "goose", "config.yaml");
   const openInterpreterConfig = path.join(home, ".openinterpreter", "profiles", "default.yaml");
+  const geminiInstructions = path.join(userProfile, ".gemini", "GEMINI.md");
+  const claudeInstructions = path.join(userProfile, ".claude", "CLAUDE.md");
+  const cursorAgents = path.join(userProfile, ".cursor", "agents.md");
+  const cursorAgentsUpper = path.join(userProfile, ".cursor", "AGENTS.md");
   const codexAgents = path.join(userProfile, ".codex", "AGENTS.md");
   switch (process.platform) {
     case "win32":
       return {
-        claude: path.join(appData, "Claude", "claude_desktop_config.json"),
-        continue: path.join(userProfile, ".continue", "config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
+        continue: continueJson,
+        continueYaml,
+        continueYml,
         zed: path.join(appData, "Zed", "settings.json"),
         vscodeSettings: path.join(appData, "Code", "User", "settings.json"),
         vscodeGlobalInstructions,
+        vscodeInstructionsDir,
+        vscodeInstructionsFile,
         windsurfGlobalRules,
         rooRules,
         pearaiAgent,
@@ -946,11 +1211,18 @@ function clientInstructionPaths() {
       };
     case "darwin":
       return {
-        claude: path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json"),
-        continue: path.join(home, ".continue", "config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
+        continue: continueJson,
+        continueYaml,
+        continueYml,
         zed: path.join(home, ".config", "zed", "settings.json"),
         vscodeSettings: path.join(home, "Library", "Application Support", "Code", "User", "settings.json"),
         vscodeGlobalInstructions,
+        vscodeInstructionsDir,
+        vscodeInstructionsFile,
         windsurfGlobalRules,
         rooRules,
         pearaiAgent,
@@ -961,11 +1233,18 @@ function clientInstructionPaths() {
       };
     default:
       return {
-        claude: path.join(home, ".config", "Claude", "claude_desktop_config.json"),
-        continue: path.join(home, ".continue", "config.json"),
+        gemini: geminiInstructions,
+        claude: claudeInstructions,
+        cursorAgents,
+        cursorAgentsUpper,
+        continue: continueJson,
+        continueYaml,
+        continueYml,
         zed: path.join(home, ".config", "zed", "settings.json"),
         vscodeSettings: path.join(home, ".config", "Code", "User", "settings.json"),
         vscodeGlobalInstructions,
+        vscodeInstructionsDir,
+        vscodeInstructionsFile,
         windsurfGlobalRules,
         rooRules,
         pearaiAgent,
@@ -1041,12 +1320,23 @@ function applyAgentInstructions({ logger } = {}) {
   };
 
   if (paths.vscodeGlobalInstructions) {
-    safeApply("vscode-global", () =>
-      upsertPromptFile(paths.vscodeGlobalInstructions, instructions, { prepend: true })
+    safeApply("vscode-global-cleanup", () => removePromptFile(paths.vscodeGlobalInstructions));
+  }
+  if (paths.vscodeInstructionsFile) {
+    safeApply("vscode-instructions-file-cleanup", () =>
+      removePromptFile(paths.vscodeInstructionsFile)
     );
   }
-  if (paths.vscodeSettings && paths.vscodeGlobalInstructions) {
-    safeApply("vscode-settings", () => upsertVsCodeInstructions(paths.vscodeSettings, paths.vscodeGlobalInstructions));
+  if (paths.cursorAgents) {
+    safeApply("cursor-legacy-cleanup", () => removePromptFile(paths.cursorAgents));
+  }
+  if (paths.cursorAgentsUpper) {
+    safeApply("cursor-legacy-upper-cleanup", () => removePromptFile(paths.cursorAgentsUpper));
+  }
+  if (paths.vscodeSettings) {
+    safeApply("vscode-settings", () =>
+      upsertVsCodeInstructions(paths.vscodeSettings, instructions, paths.vscodeGlobalInstructions)
+    );
   }
   if (paths.windsurfGlobalRules) {
     safeApply("windsurf", () => upsertPromptFile(paths.windsurfGlobalRules, instructions, { prepend: true }));
@@ -1060,18 +1350,28 @@ function applyAgentInstructions({ logger } = {}) {
   if (paths.claude) {
     safeApply("claude", () => upsertClaudeInstructions(paths.claude, instructions));
   }
-  if (paths.continue) {
-    safeApply("continue", () => upsertContinueInstructions(paths.continue, instructions));
+  if (paths.gemini) {
+    safeApply("gemini", () => upsertPromptFile(paths.gemini, instructions));
+  }
+  const continueYamlExists =
+    (paths.continueYaml && fs.existsSync(paths.continueYaml)) ||
+    (paths.continueYml && fs.existsSync(paths.continueYml));
+  if (continueYamlExists) {
+    if (paths.continueYaml && fs.existsSync(paths.continueYaml)) {
+      safeApply("continue-yaml", () => upsertContinueYamlRules(paths.continueYaml, instructions));
+    }
+    if (paths.continueYml && fs.existsSync(paths.continueYml)) {
+      safeApply("continue-yml", () => upsertContinueYamlRules(paths.continueYml, instructions));
+    }
+    if (paths.continue && fs.existsSync(paths.continue)) {
+      safeApply("continue-json", () => upsertContinueJsonInstructions(paths.continue, instructions));
+    }
+  } else if (paths.continue) {
+    safeApply("continue-json", () => upsertContinueJsonInstructions(paths.continue, instructions));
   }
   if (paths.zed) {
     safeApply("zed", () => upsertZedInstructions(paths.zed, instructions));
   }
-  if (paths.aiderConfig) {
-    safeApply("aider", () => upsertYamlInstruction(paths.aiderConfig, "system-prompt", instructions));
-  }
-  if (paths.gooseConfig) {
-    safeApply("goose", () => upsertYamlInstruction(paths.gooseConfig, "instructions", instructions));
-  }
   if (paths.openInterpreterConfig) {
     safeApply("open-interpreter", () =>
       upsertYamlInstruction(paths.openInterpreterConfig, "system_message", instructions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docdex",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "mcpName": "io.github.bekirdag/docdex",
   "description": "Local-first documentation and code indexer with HTTP/MCP search, AST, and agent memory.",
   "bin": {