@arabold/docs-mcp-server 1.21.0 → 1.22.0

package/dist/index.js

@@ -1,4 +1,10 @@
+#!/usr/bin/env node
 import "dotenv/config";
+import { BedrockEmbeddings } from "@langchain/aws";
+import { GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
+import { VertexAIEmbeddings } from "@langchain/google-vertexai";
+import { AzureOpenAIEmbeddings, OpenAIEmbeddings } from "@langchain/openai";
+import { Embeddings } from "@langchain/core/embeddings";
 import { PostHog } from "posthog-node";
 import crypto, { randomUUID } from "node:crypto";
 import fs, { readFileSync, existsSync } from "node:fs";
@@ -39,14 +45,277 @@ import DOMPurify from "dompurify";
 import { fileURLToPath, URL as URL$1 } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
-import "fuse.js";
-import "langchain/text_splitter";
-import "better-sqlite3";
-import "sqlite-vec";
+import Fuse from "fuse.js";
+import { RecursiveCharacterTextSplitter } from "langchain/text_splitter";
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
 import { execSync } from "node:child_process";
 import { v4 } from "uuid";
 import psl from "psl";
 import { minimatch } from "minimatch";
+const VECTOR_DIMENSION = 1536;
+function mapDbDocumentToDocument(doc) {
+  return {
+    id: doc.id,
+    pageContent: doc.content,
+    metadata: JSON.parse(doc.metadata)
+  };
+}
+var VersionStatus = /* @__PURE__ */ ((VersionStatus2) => {
+  VersionStatus2["NOT_INDEXED"] = "not_indexed";
+  VersionStatus2["QUEUED"] = "queued";
+  VersionStatus2["RUNNING"] = "running";
+  VersionStatus2["COMPLETED"] = "completed";
+  VersionStatus2["FAILED"] = "failed";
+  VersionStatus2["CANCELLED"] = "cancelled";
+  VersionStatus2["UPDATING"] = "updating";
+  return VersionStatus2;
+})(VersionStatus || {});
+function normalizeVersionName(name) {
+  return name ?? "";
+}
+function denormalizeVersionName(name) {
+  return name === "" ? "" : name;
+}
+function getStatusDescription(status) {
+  const descriptions = {
+    [
+      "not_indexed"
+      /* NOT_INDEXED */
+    ]: "Version created but not yet indexed",
+    [
+      "queued"
+      /* QUEUED */
+    ]: "Waiting in queue for indexing",
+    [
+      "running"
+      /* RUNNING */
+    ]: "Currently being indexed",
+    [
+      "completed"
+      /* COMPLETED */
+    ]: "Successfully indexed",
+    [
+      "failed"
+      /* FAILED */
+    ]: "Indexing failed",
+    [
+      "cancelled"
+      /* CANCELLED */
+    ]: "Indexing was cancelled",
+    [
+      "updating"
+      /* UPDATING */
+    ]: "Re-indexing in progress"
+  };
+  return descriptions[status] || "Unknown status";
+}
+function isActiveStatus(status) {
+  return [
+    "queued",
+    "running",
+    "updating"
+    /* UPDATING */
+  ].includes(
+    status
+  );
+}
+class StoreError extends Error {
+  constructor(message, cause) {
+    super(cause ? `${message} caused by ${cause}` : message);
+    this.cause = cause;
+    this.name = this.constructor.name;
+    const causeError = cause instanceof Error ? cause : cause ? new Error(String(cause)) : void 0;
+    if (causeError?.stack) {
+      this.stack = causeError.stack;
+    }
+  }
+}
+class DimensionError extends StoreError {
+  constructor(modelName, modelDimension, dbDimension) {
+    super(
+      `Model "${modelName}" produces ${modelDimension}-dimensional vectors, which exceeds the database's fixed dimension of ${dbDimension}. Please use a model with dimension ≤ ${dbDimension}.`
+    );
+    this.modelName = modelName;
+    this.modelDimension = modelDimension;
+    this.dbDimension = dbDimension;
+  }
+}
+class ConnectionError extends StoreError {
+}
+class FixedDimensionEmbeddings extends Embeddings {
+  constructor(embeddings, targetDimension, providerAndModel, allowTruncate = false) {
+    super({});
+    this.embeddings = embeddings;
+    this.targetDimension = targetDimension;
+    this.allowTruncate = allowTruncate;
+    const [providerOrModel, modelName] = providerAndModel.split(":");
+    this.provider = modelName ? providerOrModel : "openai";
+    this.model = modelName || providerOrModel;
+  }
+  provider;
+  model;
+  /**
+   * Normalize a vector to the target dimension by truncating (for MRL models) or padding.
+   * @throws {DimensionError} If vector is too large and provider doesn't support MRL
+   */
+  normalizeVector(vector) {
+    const dimension = vector.length;
+    if (dimension > this.targetDimension) {
+      if (this.allowTruncate) {
+        return vector.slice(0, this.targetDimension);
+      }
+      throw new DimensionError(
+        `${this.provider}:${this.model}`,
+        dimension,
+        this.targetDimension
+      );
+    }
+    if (dimension < this.targetDimension) {
+      return [...vector, ...new Array(this.targetDimension - dimension).fill(0)];
+    }
+    return vector;
+  }
+  async embedQuery(text) {
+    const vector = await this.embeddings.embedQuery(text);
+    return this.normalizeVector(vector);
+  }
+  async embedDocuments(documents) {
+    const vectors = await this.embeddings.embedDocuments(documents);
+    return vectors.map((vector) => this.normalizeVector(vector));
+  }
+}
+class UnsupportedProviderError extends Error {
+  constructor(provider) {
+    super(
+      `❌ Unsupported embedding provider: ${provider}
+   Supported providers: openai, vertex, gemini, aws, microsoft
+   See README.md for configuration options or run with --help for more details.`
+    );
+    this.name = "UnsupportedProviderError";
+  }
+}
+class ModelConfigurationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ModelConfigurationError";
+  }
+}
+function createEmbeddingModel(providerAndModel) {
+  const [providerOrModel, ...modelNameParts] = providerAndModel.split(":");
+  const modelName = modelNameParts.join(":");
+  const provider = modelName ? providerOrModel : "openai";
+  const model = modelName || providerOrModel;
+  const baseConfig = { stripNewLines: true };
+  switch (provider) {
+    case "openai": {
+      if (!process.env.OPENAI_API_KEY) {
+        throw new ModelConfigurationError(
+          "❌ Missing API key for embedding provider\n   Please set OPENAI_API_KEY or configure an alternative embedding model.\n   See README.md for configuration options or run with --help for more details."
+        );
+      }
+      const config = {
+        ...baseConfig,
+        modelName: model,
+        batchSize: 512
+        // OpenAI supports large batches
+      };
+      const baseURL = process.env.OPENAI_API_BASE;
+      if (baseURL) {
+        config.configuration = { baseURL };
+      }
+      return new OpenAIEmbeddings(config);
+    }
+    case "vertex": {
+      if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+        throw new ModelConfigurationError(
+          "❌ Missing credentials for Google Cloud Vertex AI\n   Please set GOOGLE_APPLICATION_CREDENTIALS or configure an alternative embedding model.\n   See README.md for configuration options or run with --help for more details."
+        );
+      }
+      return new VertexAIEmbeddings({
+        ...baseConfig,
+        model
+        // e.g., "text-embedding-004"
+      });
+    }
+    case "gemini": {
+      if (!process.env.GOOGLE_API_KEY) {
+        throw new ModelConfigurationError(
+          "❌ Missing API key for Google AI (Gemini)\n   Please set GOOGLE_API_KEY or configure an alternative embedding model.\n   See README.md for configuration options or run with --help for more details."
+        );
+      }
+      const baseEmbeddings = new GoogleGenerativeAIEmbeddings({
+        ...baseConfig,
+        apiKey: process.env.GOOGLE_API_KEY,
+        model
+        // e.g., "gemini-embedding-exp-03-07"
+      });
+      return new FixedDimensionEmbeddings(
+        baseEmbeddings,
+        VECTOR_DIMENSION,
+        providerAndModel,
+        true
+      );
+    }
+    case "aws": {
+      const region = process.env.BEDROCK_AWS_REGION || process.env.AWS_REGION;
+      if (!region) {
+        throw new ModelConfigurationError(
+          "BEDROCK_AWS_REGION or AWS_REGION environment variable is required for AWS Bedrock"
+        );
+      }
+      if (!process.env.AWS_PROFILE && !process.env.AWS_ACCESS_KEY_ID && !process.env.AWS_SECRET_ACCESS_KEY) {
+        throw new ModelConfigurationError(
+          "Either AWS_PROFILE or both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are required for AWS Bedrock"
+        );
+      }
+      const credentials = process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY ? {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        sessionToken: process.env.AWS_SESSION_TOKEN
+      } : void 0;
+      return new BedrockEmbeddings({
+        ...baseConfig,
+        model,
+        // e.g., "amazon.titan-embed-text-v1"
+        region,
+        ...credentials ? { credentials } : {}
+      });
+    }
+    case "microsoft": {
+      if (!process.env.AZURE_OPENAI_API_KEY) {
+        throw new ModelConfigurationError(
+          "AZURE_OPENAI_API_KEY environment variable is required for Azure OpenAI"
+        );
+      }
+      if (!process.env.AZURE_OPENAI_API_INSTANCE_NAME) {
+        throw new ModelConfigurationError(
+          "AZURE_OPENAI_API_INSTANCE_NAME environment variable is required for Azure OpenAI"
+        );
+      }
+      if (!process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME) {
+        throw new ModelConfigurationError(
+          "AZURE_OPENAI_API_DEPLOYMENT_NAME environment variable is required for Azure OpenAI"
+        );
+      }
+      if (!process.env.AZURE_OPENAI_API_VERSION) {
+        throw new ModelConfigurationError(
+          "AZURE_OPENAI_API_VERSION environment variable is required for Azure OpenAI"
+        );
+      }
+      return new AzureOpenAIEmbeddings({
+        ...baseConfig,
+        azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,
+        azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_API_INSTANCE_NAME,
+        azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME,
+        azureOpenAIApiVersion: process.env.AZURE_OPENAI_API_VERSION,
+        deploymentName: model
+      });
+    }
+    default:
+      throw new UnsupportedProviderError(provider);
+  }
+}
 const LogLevel = {
   ERROR: 0,
   WARN: 1,
@@ -105,6 +374,41 @@ const logger = {
     }
   }
 };
+function camelToSnakeCase(str) {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function convertPropertiesToSnakeCase(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = camelToSnakeCase(key);
+    if (value && typeof value === "object" && !Array.isArray(value) && !(value instanceof Date)) {
+      result[snakeKey] = convertPropertiesToSnakeCase(value);
+    } else if (Array.isArray(value)) {
+      result[snakeKey] = value.map(
+        (item) => item && typeof item === "object" && !(item instanceof Date) ? convertPropertiesToSnakeCase(item) : item
+      );
+    } else {
+      result[snakeKey] = value;
+    }
+  }
+  return result;
+}
+function addPostHogStandardProperties(properties) {
+  const result = { ...properties };
+  if (properties.sessionId) {
+    result.$session_id = properties.sessionId;
+    delete result.sessionId;
+  }
+  if (properties.startTime) {
+    result.$start_timestamp = properties.startTime.toISOString();
+    delete result.startTime;
+  }
+  if (properties.appVersion) {
+    result.$app_version = properties.appVersion;
+    delete result.appVersion;
+  }
+  return result;
+}
 class PostHogClient {
   client;
   enabled;
@@ -155,10 +459,12 @@ class PostHogClient {
   capture(distinctId, event, properties) {
     if (!this.enabled || !this.client) return;
     try {
+      const enhancedProperties = addPostHogStandardProperties(properties);
+      const snakeCaseProperties = convertPropertiesToSnakeCase(enhancedProperties);
       this.client.capture({
         distinctId,
         event,
-        properties
+        properties: snakeCaseProperties
       });
       logger.debug(`PostHog event captured: ${event}`);
     } catch (error) {
@@ -167,6 +473,26 @@ class PostHogClient {
       );
     }
   }
+  /**
+   * Capture exception using PostHog's native error tracking
+   */
+  captureException(distinctId, error, properties) {
+    if (!this.enabled || !this.client) return;
+    try {
+      const enhancedProperties = addPostHogStandardProperties(properties || {});
+      const snakeCaseProperties = convertPropertiesToSnakeCase(enhancedProperties);
+      this.client.captureException({
+        error,
+        distinctId,
+        properties: snakeCaseProperties
+      });
+      logger.debug(`PostHog exception captured: ${error.constructor.name}`);
+    } catch (captureError) {
+      logger.debug(
+        `PostHog captureException error: ${captureError instanceof Error ? captureError.message : "Unknown error"}`
+      );
+    }
+  }
   /**
    * Graceful shutdown with event flushing
    */
@@ -203,7 +529,7 @@ class SessionTracker {
   endSession() {
     if (!this.sessionContext) return null;
     const duration = Date.now() - this.sessionContext.startTime.getTime();
-    const sessionInterface = this.sessionContext.interface;
+    const sessionInterface = this.sessionContext.appInterface;
     this.sessionContext = void 0;
     return { duration, interface: sessionInterface };
   }
@@ -213,6 +539,14 @@ class SessionTracker {
   getSessionContext() {
     return this.sessionContext;
   }
+  /**
+   * Update session context with additional fields
+   */
+  updateSessionContext(updates) {
+    if (this.sessionContext) {
+      this.sessionContext = { ...this.sessionContext, ...updates };
+    }
+  }
   /**
    * Get enriched properties with session context
    */
@@ -293,8 +627,6 @@ var TelemetryEvent = /* @__PURE__ */ ((TelemetryEvent2) => {
   TelemetryEvent2["PIPELINE_JOB_PROGRESS"] = "pipeline_job_progress";
   TelemetryEvent2["PIPELINE_JOB_COMPLETED"] = "pipeline_job_completed";
   TelemetryEvent2["DOCUMENT_PROCESSED"] = "document_processed";
-  TelemetryEvent2["DOCUMENT_PROCESSING_FAILED"] = "document_processing_failed";
-  TelemetryEvent2["ERROR_OCCURRED"] = "error_occurred";
   return TelemetryEvent2;
 })(TelemetryEvent || {});
 class Analytics {
@@ -320,23 +652,34 @@ class Analytics {
     if (!this.enabled) return;
     this.sessionTracker.startSession(context);
     this.track("session_started", {
-      interface: context.interface,
-      version: context.version,
-      platform: context.platform,
-      sessionDurationTarget: context.interface === "cli" ? "short" : "long",
-      authEnabled: context.authEnabled,
-      readOnly: context.readOnly,
-      servicesCount: context.servicesEnabled.length
+      interface: context.appInterface,
+      version: context.appVersion,
+      platform: context.appPlatform,
+      authEnabled: context.appAuthEnabled,
+      readOnly: context.appReadOnly,
+      servicesCount: context.appServicesEnabled.length
     });
   }
   /**
-   * Track an event with automatic session context inclusion
+   * Update session context with additional fields (e.g., embedding model info)
    */
+  updateSessionContext(updates) {
+    if (!this.enabled) return;
+    this.sessionTracker.updateSessionContext(updates);
+  }
   track(event, properties = {}) {
     if (!this.enabled) return;
     const eventProperties = this.sessionTracker.getEnrichedProperties(properties);
     this.postHogClient.capture(this.distinctId, event, eventProperties);
   }
+  /**
+   * Capture exception using PostHog's native error tracking with session context
+   */
+  captureException(error, properties = {}) {
+    if (!this.enabled) return;
+    const eventProperties = this.sessionTracker.getEnrichedProperties(properties);
+    this.postHogClient.captureException(this.distinctId, error, eventProperties);
+  }
   /**
    * Track session end with duration
    */
@@ -368,29 +711,38 @@ class Analytics {
   getSessionContext() {
     return this.sessionTracker.getSessionContext();
   }
-}
-const analytics = new Analytics();
-async function trackTool(toolName, operation, getProperties) {
-  const startTime = Date.now();
-  try {
-    const result = await operation();
-    analytics.track("tool_used", {
-      tool: toolName,
-      success: true,
-      durationMs: Date.now() - startTime,
-      ...getProperties ? getProperties(result) : {}
-    });
-    return result;
-  } catch (error) {
-    analytics.track("tool_used", {
-      tool: toolName,
-      success: false,
-      durationMs: Date.now() - startTime,
-      errorType: error instanceof Error ? error.constructor.name : "UnknownError"
-    });
-    throw error;
+  /**
+   * Track tool usage with error handling and automatic timing
+   */
+  async trackTool(toolName, operation, getProperties) {
+    const startTime = Date.now();
+    try {
+      const result = await operation();
+      this.track("tool_used", {
+        tool: toolName,
+        success: true,
+        durationMs: Date.now() - startTime,
+        ...getProperties ? getProperties(result) : {}
+      });
+      return result;
+    } catch (error) {
+      this.track("tool_used", {
+        tool: toolName,
+        success: false,
+        durationMs: Date.now() - startTime
+      });
+      if (error instanceof Error) {
+        this.captureException(error, {
+          tool: toolName,
+          context: "tool_execution",
+          durationMs: Date.now() - startTime
+        });
+      }
+      throw error;
+    }
   }
 }
+const analytics = new Analytics();
 function extractHostname(url) {
   try {
     const parsed = new URL(url);
@@ -410,28 +762,7 @@ function extractProtocol(urlOrPath) {
     return "unknown";
   }
 }
-function analyzeSearchQuery(query) {
-  return {
-    length: query.length,
-    wordCount: query.trim().split(/\s+/).length,
-    hasCodeTerms: /\b(function|class|import|export|const|let|var|def|async|await)\b/i.test(query),
-    hasSpecialChars: /[^\w\s]/.test(query)
-  };
-}
-function sanitizeErrorMessage(message) {
-  return message.replace(/https?:\/\/[^\s]+/gi, "[url]").replace(/file:\/\/[^\s]+/gi, "[file-url]").replace(/\/[^\s]*\.[a-z]{2,4}/gi, "[path]").replace(/[A-Za-z]:\\[^\s]+/g, "[path]").replace(/Bearer\s+[^\s]+/gi, "Bearer [token]").replace(/api[_-]?key[=:]\s*[^\s]+/gi, "api_key=[redacted]").replace(/token[=:]\s*[^\s]+/gi, "token=[redacted]").substring(0, 200);
-}
-function sanitizeError(error) {
-  return {
-    type: error.constructor.name,
-    message: sanitizeErrorMessage(error.message),
-    hasStack: Boolean(error.stack)
-  };
-}
-function extractCliFlags(argv) {
-  return argv.filter((arg) => arg.startsWith("--") || arg.startsWith("-"));
-}
-const version = "1.20.0";
+const version = "1.21.1";
 const packageJson = {
   version
 };
@@ -439,34 +770,48 @@ function getPackageVersion() {
   return packageJson.version;
 }
 function createCliSession(command, options) {
-  return {
+  const baseSession = {
     sessionId: randomUUID(),
-    interface: "cli",
+    appInterface: "cli",
     startTime: /* @__PURE__ */ new Date(),
-    version: getPackageVersion(),
-    platform: process.platform,
-    nodeVersion: process.version,
-    command: command || "unknown",
-    authEnabled: options?.authEnabled,
-    readOnly: options?.readOnly,
-    servicesEnabled: ["worker"]
+    appVersion: getPackageVersion(),
+    appPlatform: process.platform,
+    appNodeVersion: process.version,
+    cliCommand: command || "unknown",
+    appAuthEnabled: options?.authEnabled,
+    appReadOnly: options?.readOnly,
+    appServicesEnabled: ["worker"]
     // CLI typically runs embedded worker
   };
+  if (options?.embeddingContext) {
+    return {
+      ...baseSession,
+      ...options.embeddingContext
+    };
+  }
+  return baseSession;
 }
 function createMcpSession(options) {
-  return {
+  const baseSession = {
     sessionId: randomUUID(),
-    interface: "mcp",
+    appInterface: "mcp",
     startTime: /* @__PURE__ */ new Date(),
-    version: getPackageVersion(),
-    platform: process.platform,
-    nodeVersion: process.version,
-    protocol: options.protocol || "stdio",
-    transport: options.transport,
-    authEnabled: options.authEnabled ?? false,
-    readOnly: options.readOnly ?? false,
-    servicesEnabled: options.servicesEnabled ?? ["mcp"]
+    appVersion: getPackageVersion(),
+    appPlatform: process.platform,
+    appNodeVersion: process.version,
+    mcpProtocol: options.protocol || "stdio",
+    mcpTransport: options.transport,
+    appAuthEnabled: options.authEnabled ?? false,
+    appReadOnly: options.readOnly ?? false,
+    appServicesEnabled: options.servicesEnabled ?? ["mcp"]
   };
+  if (options.embeddingContext) {
+    return {
+      ...baseSession,
+      ...options.embeddingContext
+    };
+  }
+  return baseSession;
 }
 function createTelemetryService() {
   return {
@@ -929,42 +1274,55 @@ class CancelJobTool {
    * @returns A promise that resolves with the outcome message.
    */
   async execute(input) {
-    try {
-      const job = await this.pipeline.getJob(input.jobId);
-      if (!job) {
-        logger.warn(`❓ [CancelJobTool] Job not found: ${input.jobId}`);
-        return {
-          message: `Job with ID ${input.jobId} not found.`,
-          success: false
-        };
-      }
-      if (job.status === PipelineJobStatus.COMPLETED || // Use enum member
-      job.status === PipelineJobStatus.FAILED || // Use enum member
-      job.status === PipelineJobStatus.CANCELLED) {
-        logger.debug(`Job ${input.jobId} is already in a final state: ${job.status}.`);
+    return analytics.trackTool(
+      "cancel_job",
+      async () => {
+        try {
+          const job = await this.pipeline.getJob(input.jobId);
+          if (!job) {
+            logger.warn(`❓ [CancelJobTool] Job not found: ${input.jobId}`);
+            return {
+              message: `Job with ID ${input.jobId} not found.`,
+              success: false
+            };
+          }
+          if (job.status === PipelineJobStatus.COMPLETED || // Use enum member
+          job.status === PipelineJobStatus.FAILED || // Use enum member
+          job.status === PipelineJobStatus.CANCELLED) {
+            logger.debug(
+              `Job ${input.jobId} is already in a final state: ${job.status}.`
+            );
+            return {
+              message: `Job ${input.jobId} is already ${job.status}. No action taken.`,
+              success: true
+              // Considered success as no cancellation needed
+            };
+          }
+          await this.pipeline.cancelJob(input.jobId);
+          const updatedJob = await this.pipeline.getJob(input.jobId);
+          const finalStatus = updatedJob?.status ?? "UNKNOWN (job disappeared?)";
+          logger.debug(
+            `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}`
+          );
+          return {
+            message: `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}.`,
+            success: true
+          };
+        } catch (error) {
+          logger.error(`❌ Error cancelling job ${input.jobId}: ${error}`);
+          return {
+            message: `Failed to cancel job ${input.jobId}: ${error instanceof Error ? error.message : String(error)}`,
+            success: false
+          };
+        }
+      },
+      (result) => {
         return {
-          message: `Job ${input.jobId} is already ${job.status}. No action taken.`,
-          success: true
-          // Considered success as no cancellation needed
+          success: result.success
+          // Note: success flag already indicates if cancellation was successful
         };
       }
-      await this.pipeline.cancelJob(input.jobId);
-      const updatedJob = await this.pipeline.getJob(input.jobId);
-      const finalStatus = updatedJob?.status ?? "UNKNOWN (job disappeared?)";
-      logger.debug(
-        `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}`
-      );
-      return {
-        message: `Cancellation requested for job ${input.jobId}. Current status: ${finalStatus}.`,
-        success: true
-      };
-    } catch (error) {
-      logger.error(`❌ Error cancelling job ${input.jobId}: ${error}`);
-      return {
-        message: `Failed to cancel job ${input.jobId}: ${error instanceof Error ? error.message : String(error)}`,
-        success: false
-      };
-    }
+    );
   }
 }
 class ClearCompletedJobsTool {
@@ -982,24 +1340,33 @@ class ClearCompletedJobsTool {
    * @returns A promise that resolves with the outcome of the clear operation.
    */
   async execute(_input) {
-    try {
-      const clearedCount = await this.pipeline.clearCompletedJobs();
-      const message = clearedCount > 0 ? `Successfully cleared ${clearedCount} completed job${clearedCount === 1 ? "" : "s"} from the queue.` : "No completed jobs to clear.";
-      logger.debug(message);
-      return {
-        message,
-        success: true,
-        clearedCount
-      };
-    } catch (error) {
-      const errorMessage = `Failed to clear completed jobs: ${error instanceof Error ? error.message : String(error)}`;
-      logger.error(`❌ ${errorMessage}`);
-      return {
-        message: errorMessage,
-        success: false,
-        clearedCount: 0
-      };
-    }
+    return analytics.trackTool(
+      "clear_completed_jobs",
+      async () => {
+        try {
+          const clearedCount = await this.pipeline.clearCompletedJobs();
+          const message = clearedCount > 0 ? `Successfully cleared ${clearedCount} completed job${clearedCount === 1 ? "" : "s"} from the queue.` : "No completed jobs to clear.";
+          logger.debug(message);
+          return {
+            message,
+            success: true,
+            clearedCount
+          };
+        } catch (error) {
+          const errorMessage = `Failed to clear completed jobs: ${error instanceof Error ? error.message : String(error)}`;
+          logger.error(`❌ ${errorMessage}`);
+          return {
+            message: errorMessage,
+            success: false,
+            clearedCount: 0
+          };
+        }
+      },
+      (result) => ({
+        success: result.success,
+        clearedCount: result.clearedCount
+      })
+    );
   }
 }
 class ToolError extends Error {
@@ -1937,91 +2304,106 @@ class FetchUrlTool {
    * @throws {ToolError} If fetching or processing fails
    */
   async execute(options) {
-    const { url, scrapeMode = ScrapeMode.Auto, headers } = options;
-    const canFetchResults = this.fetchers.map((f) => f.canFetch(url));
-    const fetcherIndex = canFetchResults.indexOf(true);
-    if (fetcherIndex === -1) {
-      throw new ToolError(
-        `Invalid URL: ${url}. Must be an HTTP/HTTPS URL or a file:// URL.`,
-        this.constructor.name
-      );
-    }
-    const fetcher = this.fetchers[fetcherIndex];
-    const htmlPipeline = new HtmlPipeline();
-    const markdownPipeline = new MarkdownPipeline();
-    const pipelines = [htmlPipeline, markdownPipeline];
-    try {
-      logger.info(`📡 Fetching ${url}...`);
-      const rawContent = await fetcher.fetch(url, {
-        followRedirects: options.followRedirects ?? true,
-        maxRetries: 3,
-        headers
-        // propagate custom headers
-      });
-      logger.info("🔄 Processing content...");
-      let processed;
-      for (const pipeline of pipelines) {
-        if (pipeline.canProcess(rawContent)) {
-          processed = await pipeline.process(
-            rawContent,
-            {
-              url,
-              library: "",
-              version: "",
-              maxDepth: 0,
-              maxPages: 1,
-              maxConcurrency: 1,
-              scope: "subpages",
-              followRedirects: options.followRedirects ?? true,
-              excludeSelectors: void 0,
-              ignoreErrors: false,
-              scrapeMode,
-              headers
-              // propagate custom headers
-            },
-            fetcher
+    return analytics.trackTool(
+      "fetch_url",
+      async () => {
+        const { url, scrapeMode = ScrapeMode.Auto, headers } = options;
+        const canFetchResults = this.fetchers.map((f) => f.canFetch(url));
+        const fetcherIndex = canFetchResults.indexOf(true);
+        if (fetcherIndex === -1) {
+          throw new ToolError(
+            `Invalid URL: ${url}. Must be an HTTP/HTTPS URL or a file:// URL.`,
+            this.constructor.name
           );
-          break;
         }
+        const fetcher = this.fetchers[fetcherIndex];
+        const htmlPipeline = new HtmlPipeline();
+        const markdownPipeline = new MarkdownPipeline();
+        const pipelines = [htmlPipeline, markdownPipeline];
+        try {
+          logger.info(`📡 Fetching ${url}...`);
+          const rawContent = await fetcher.fetch(url, {
+            followRedirects: options.followRedirects ?? true,
+            maxRetries: 3,
+            headers
+            // propagate custom headers
+          });
+          logger.info("🔄 Processing content...");
+          let processed;
+          for (const pipeline of pipelines) {
+            if (pipeline.canProcess(rawContent)) {
+              processed = await pipeline.process(
+                rawContent,
+                {
+                  url,
+                  library: "",
+                  version: "",
+                  maxDepth: 0,
+                  maxPages: 1,
+                  maxConcurrency: 1,
+                  scope: "subpages",
+                  followRedirects: options.followRedirects ?? true,
+                  excludeSelectors: void 0,
+                  ignoreErrors: false,
+                  scrapeMode,
+                  headers
+                  // propagate custom headers
+                },
+                fetcher
+              );
+              break;
+            }
+          }
+          if (!processed) {
+            logger.warn(
+              `⚠️  Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
+            );
+            const resolvedCharset = resolveCharset(
+              rawContent.charset,
+              rawContent.content,
+              rawContent.mimeType
+            );
+            const contentString = convertToString(rawContent.content, resolvedCharset);
+            return contentString;
+          }
+          for (const err of processed.errors) {
+            logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
+          }
+          if (typeof processed.textContent !== "string" || !processed.textContent.trim()) {
+            throw new ToolError(
+              `Processing resulted in empty content for ${url}`,
+              this.constructor.name
+            );
+          }
+          logger.info(`✅ Successfully processed ${url}`);
+          return processed.textContent;
+        } catch (error) {
+          if (error instanceof ScraperError || error instanceof ToolError) {
+            throw new ToolError(
+              `Failed to fetch or process URL: ${error.message}`,
+              this.constructor.name
+            );
+          }
+          throw new ToolError(
+            `Failed to fetch or process URL: ${error instanceof Error ? error.message : String(error)}`,
+            this.constructor.name
+          );
+        } finally {
+          await htmlPipeline.close();
+          await markdownPipeline.close();
+        }
+      },
+      (result) => {
+        const { url, scrapeMode, followRedirects, headers } = options;
+        return {
+          url,
+          scrapeMode,
+          followRedirects,
+          contentLength: result.length,
+          hasHeaders: !!headers
+        };
       }
-      if (!processed) {
-        logger.warn(
-          `⚠️  Unsupported content type "${rawContent.mimeType}" for ${url}. Returning raw content.`
-        );
-        const resolvedCharset = resolveCharset(
-          rawContent.charset,
-          rawContent.content,
-          rawContent.mimeType
-        );
-        const contentString = convertToString(rawContent.content, resolvedCharset);
-        return contentString;
-      }
-      for (const err of processed.errors) {
-        logger.warn(`⚠️  Processing error for ${url}: ${err.message}`);
-      }
-      if (typeof processed.textContent !== "string" || !processed.textContent.trim()) {
-        throw new ToolError(
-          `Processing resulted in empty content for ${url}`,
-          this.constructor.name
-        );
-      }
-      logger.info(`✅ Successfully processed ${url}`);
-      return processed.textContent;
-    } catch (error) {
-      if (error instanceof ScraperError || error instanceof ToolError) {
-        throw new ToolError(
-          `Failed to fetch or process URL: ${error.message}`,
-          this.constructor.name
-        );
-      }
-      throw new ToolError(
-        `Failed to fetch or process URL: ${error instanceof Error ? error.message : String(error)}`,
-        this.constructor.name
-      );
-    } finally {
-      await htmlPipeline.close();
-      await markdownPipeline.close();
-    }
+    );
   }
 }
 class FindVersionTool {
@@ -2034,35 +2416,50 @@ class FindVersionTool {
    * @returns A descriptive string indicating the best match and unversioned status, or an error message.
    */
   async execute(options) {
-    const { library, targetVersion } = options;
-    const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
-    try {
-      const { bestMatch, hasUnversioned } = await this.docService.findBestVersion(
-        library,
-        targetVersion
-      );
-      let message = "";
-      if (bestMatch) {
-        message = `Best match: ${bestMatch}.`;
-        if (hasUnversioned) {
-          message += " Unversioned docs also available.";
+    return analytics.trackTool(
+      "find_version",
+      async () => {
+        const { library, targetVersion } = options;
+        const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
+        try {
+          const { bestMatch, hasUnversioned } = await this.docService.findBestVersion(
+            library,
+            targetVersion
+          );
+          let message = "";
+          if (bestMatch) {
+            message = `Best match: ${bestMatch}.`;
+            if (hasUnversioned) {
+              message += " Unversioned docs also available.";
+            }
+          } else if (hasUnversioned) {
+            message = `No matching version found for ${libraryAndVersion}, but unversioned docs exist.`;
+          } else {
+            message = `No matching version or unversioned documents found for ${libraryAndVersion}.`;
+          }
+          return { message, bestMatch, hasUnversioned };
+        } catch (error) {
+          if (error instanceof VersionNotFoundError) {
+            logger.info(`ℹ️ Version not found: ${error.message}`);
+            const message = `No matching version or unversioned documents found for ${libraryAndVersion}. Available: ${error.availableVersions.length > 0 ? error.availableVersions.map((v) => v.version).join(", ") : "None"}.`;
+            return { message, bestMatch: null, hasUnversioned: false };
+          }
+          logger.error(
+            `❌ Error finding version for ${libraryAndVersion}: ${error instanceof Error ? error.message : error}`
+          );
+          throw error;
         }
-      } else if (hasUnversioned) {
-        message = `No matching version found for ${libraryAndVersion}, but unversioned docs exist.`;
-      } else {
-        message = `No matching version or unversioned documents found for ${libraryAndVersion}.`;
-      }
-      return message;
-    } catch (error) {
-      if (error instanceof VersionNotFoundError) {
-        logger.info(`ℹ️ Version not found: ${error.message}`);
-        return `No matching version or unversioned documents found for ${libraryAndVersion}. Available: ${error.availableVersions.length > 0 ? error.availableVersions.map((v) => v.version).join(", ") : "None"}.`;
+      },
+      (result) => {
+        const { library, targetVersion } = options;
+        return {
+          library,
+          targetVersion,
+          foundMatch: !!result.bestMatch,
+          hasUnversioned: result.hasUnversioned
+        };
       }
-      logger.error(
-        `❌ Error finding version for ${libraryAndVersion}: ${error instanceof Error ? error.message : error}`
-      );
-      throw error;
-    }
+    ).then((result) => result.message);
   }
 }
 class GetJobInfoTool {
@@ -2080,29 +2477,41 @@ class GetJobInfoTool {
    * @returns A promise that resolves with the simplified job info or null if not found.
    */
   async execute(input) {
-    const job = await this.pipeline.getJob(input.jobId);
-    if (!job) {
-      return { job: null };
-    }
-    const jobInfo = {
-      id: job.id,
-      library: job.library,
-      version: job.version,
-      status: job.status,
-      dbStatus: job.versionStatus,
-      createdAt: job.createdAt.toISOString(),
-      startedAt: job.startedAt?.toISOString() ?? null,
-      finishedAt: job.finishedAt?.toISOString() ?? null,
-      error: job.error?.message ?? null,
-      progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
-        pages: job.progressPages || 0,
-        totalPages: job.progressMaxPages,
-        totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
-      } : void 0,
-      updatedAt: job.updatedAt?.toISOString(),
-      errorMessage: job.errorMessage ?? void 0
-    };
-    return { job: jobInfo };
+    return analytics.trackTool(
+      "get_job_info",
+      async () => {
+        const job = await this.pipeline.getJob(input.jobId);
+        if (!job) {
+          return { job: null };
+        }
+        const jobInfo = {
+          id: job.id,
+          library: job.library,
+          version: job.version,
+          status: job.status,
+          dbStatus: job.versionStatus,
+          createdAt: job.createdAt.toISOString(),
+          startedAt: job.startedAt?.toISOString() ?? null,
+          finishedAt: job.finishedAt?.toISOString() ?? null,
+          error: job.error?.message ?? null,
+          progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
+            pages: job.progressPages || 0,
+            totalPages: job.progressMaxPages,
+            totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
+          } : void 0,
+          updatedAt: job.updatedAt?.toISOString(),
+          errorMessage: job.errorMessage ?? void 0
+        };
+        return { job: jobInfo };
+      },
+      (result) => {
+        return {
+          found: result.job !== null,
+          library: result.job?.library,
+          version: result.job?.version
+        };
+      }
+    );
   }
 }
 class ListJobsTool {
@@ -2120,28 +2529,45 @@ class ListJobsTool {
    * @returns A promise that resolves with the list of simplified job objects.
    */
   async execute(input) {
-    const jobs = await this.pipeline.getJobs(input.status);
-    const simplifiedJobs = jobs.map((job) => {
-      return {
-        id: job.id,
-        library: job.library,
-        version: job.version,
-        status: job.status,
-        dbStatus: job.versionStatus,
-        createdAt: job.createdAt.toISOString(),
-        startedAt: job.startedAt?.toISOString() ?? null,
-        finishedAt: job.finishedAt?.toISOString() ?? null,
-        error: job.error?.message ?? null,
-        progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
-          pages: job.progressPages || 0,
-          totalPages: job.progressMaxPages,
-          totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
-        } : void 0,
-        updatedAt: job.updatedAt?.toISOString(),
-        errorMessage: job.errorMessage ?? void 0
-      };
-    });
-    return { jobs: simplifiedJobs };
+    return analytics.trackTool(
+      "list_jobs",
+      async () => {
+        const jobs = await this.pipeline.getJobs(input.status);
+        const simplifiedJobs = jobs.map((job) => {
+          return {
+            id: job.id,
+            library: job.library,
+            version: job.version,
+            status: job.status,
+            dbStatus: job.versionStatus,
+            createdAt: job.createdAt.toISOString(),
+            startedAt: job.startedAt?.toISOString() ?? null,
+            finishedAt: job.finishedAt?.toISOString() ?? null,
+            error: job.error?.message ?? null,
+            progress: job.progressMaxPages && job.progressMaxPages > 0 ? {
+              pages: job.progressPages || 0,
+              totalPages: job.progressMaxPages,
+              totalDiscovered: job.progress?.totalDiscovered || job.progressMaxPages
+            } : void 0,
+            updatedAt: job.updatedAt?.toISOString(),
+            errorMessage: job.errorMessage ?? void 0
+          };
+        });
+        return { jobs: simplifiedJobs };
+      },
+      (result) => {
+        return {
+          jobCount: result.jobs.length,
+          statusCounts: result.jobs.reduce(
+            (acc, job) => {
+              acc[job.status] = (acc[job.status] || 0) + 1;
+              return acc;
+            },
+            {}
+          )
+        };
+      }
+    );
   }
 }
 class ListLibrariesTool {
@@ -2150,20 +2576,32 @@ class ListLibrariesTool {
     this.docService = docService;
   }
   async execute(_options) {
-    const rawLibraries = await this.docService.listLibraries();
-    const libraries = rawLibraries.map(({ library, versions }) => ({
-      name: library,
-      versions: versions.map((v) => ({
-        version: v.ref.version,
-        documentCount: v.counts.documents,
-        uniqueUrlCount: v.counts.uniqueUrls,
-        indexedAt: v.indexedAt,
-        status: v.status,
-        ...v.progress ? { progress: v.progress } : void 0,
-        sourceUrl: v.sourceUrl
-      }))
-    }));
-    return { libraries };
+    return analytics.trackTool(
+      "list_libraries",
+      async () => {
+        const rawLibraries = await this.docService.listLibraries();
+        const libraries = rawLibraries.map(({ library, versions }) => ({
+          name: library,
+          versions: versions.map((v) => ({
+            version: v.ref.version,
+            documentCount: v.counts.documents,
+            uniqueUrlCount: v.counts.uniqueUrls,
+            indexedAt: v.indexedAt,
+            status: v.status,
+            ...v.progress ? { progress: v.progress } : void 0,
+            sourceUrl: v.sourceUrl
+          }))
+        }));
+        return { libraries };
+      },
+      (result) => ({
+        libraryCount: result.libraries.length,
+        totalVersions: result.libraries.reduce(
+          (sum, lib) => sum + lib.versions.length,
+          0
+        )
+      })
+    );
   }
 }
 class RemoveTool {
@@ -2177,29 +2615,42 @@ class RemoveTool {
    * Removes all documents, the version record, and the library if no other versions exist.
    */
   async execute(args) {
-    const { library, version: version2 } = args;
-    logger.info(`🗑️ Removing library: ${library}${version2 ? `@${version2}` : ""}`);
-    try {
-      const allJobs = await this.pipeline.getJobs();
-      const jobs = allJobs.filter(
-        (job) => job.library === library && job.version === (version2 ?? "") && (job.status === PipelineJobStatus.QUEUED || job.status === PipelineJobStatus.RUNNING)
-      );
-      for (const job of jobs) {
-        logger.info(
-          `🚫 Aborting job for ${library}@${version2 ?? ""} before deletion: ${job.id}`
-        );
-        await this.pipeline.cancelJob(job.id);
-        await this.pipeline.waitForJobCompletion(job.id);
+    return analytics.trackTool(
+      "remove_docs",
+      async () => {
+        const { library, version: version2 } = args;
+        logger.info(`🗑️ Removing library: ${library}${version2 ? `@${version2}` : ""}`);
+        try {
+          const allJobs = await this.pipeline.getJobs();
+          const jobs = allJobs.filter(
+            (job) => job.library === library && job.version === (version2 ?? "") && (job.status === PipelineJobStatus.QUEUED || job.status === PipelineJobStatus.RUNNING)
+          );
+          for (const job of jobs) {
+            logger.info(
+              `🚫 Aborting job for ${library}@${version2 ?? ""} before deletion: ${job.id}`
+            );
+            await this.pipeline.cancelJob(job.id);
+            await this.pipeline.waitForJobCompletion(job.id);
+          }
+          await this.documentManagementService.removeVersion(library, version2);
+          const message = `Successfully removed ${library}${version2 ? `@${version2}` : ""}.`;
+          logger.info(`✅ ${message}`);
+          return { message };
+        } catch (error) {
+          const errorMessage = `Failed to remove ${library}${version2 ? `@${version2}` : ""}: ${error instanceof Error ? error.message : String(error)}`;
+          logger.error(`❌ Error removing library: ${errorMessage}`);
+          throw new ToolError(errorMessage, this.constructor.name);
+        }
+      },
+      () => {
+        const { library, version: version2 } = args;
+        return {
+          library,
+          version: version2
+          // Success is implicit since if this callback runs, no exception was thrown
+        };
       }
-      await this.documentManagementService.removeVersion(library, version2);
-      const message = `Successfully removed ${library}${version2 ? `@${version2}` : ""}.`;
-      logger.info(`✅ ${message}`);
-      return { message };
-    } catch (error) {
-      const errorMessage = `Failed to remove ${library}${version2 ? `@${version2}` : ""}: ${error instanceof Error ? error.message : String(error)}`;
-      logger.error(`❌ Error removing library: ${errorMessage}`);
-      throw new ToolError(errorMessage, this.constructor.name);
-    }
+    );
   }
 }
 class ScrapeTool {
@@ -2215,66 +2666,80 @@ class ScrapeTool {
       options: scraperOptions,
       waitForCompletion = true
     } = options;
-    let internalVersion;
-    const partialVersionRegex = /^\d+(\.\d+)?$/;
-    if (version2 === null || version2 === void 0) {
-      internalVersion = "";
-    } else {
-      const validFullVersion = semver.valid(version2);
-      if (validFullVersion) {
-        internalVersion = validFullVersion;
-      } else if (partialVersionRegex.test(version2)) {
-        const coercedVersion = semver.coerce(version2);
-        if (coercedVersion) {
-          internalVersion = coercedVersion.version;
+    return analytics.trackTool(
+      "scrape_docs",
+      async () => {
+        let internalVersion;
+        const partialVersionRegex = /^\d+(\.\d+)?$/;
+        if (version2 === null || version2 === void 0) {
+          internalVersion = "";
         } else {
-          throw new Error(
-            `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
-          );
+          const validFullVersion = semver.valid(version2);
+          if (validFullVersion) {
+            internalVersion = validFullVersion;
+          } else if (partialVersionRegex.test(version2)) {
+            const coercedVersion = semver.coerce(version2);
+            if (coercedVersion) {
+              internalVersion = coercedVersion.version;
+            } else {
+              throw new Error(
+                `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
+              );
+            }
+          } else {
+            throw new Error(
+              `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
+            );
+          }
         }
-      } else {
-        throw new Error(
-          `Invalid version format for scraping: '${version2}'. Use 'X.Y.Z', 'X.Y.Z-prerelease', 'X.Y', 'X', or omit.`
-        );
-      }
-    }
-    internalVersion = internalVersion.toLowerCase();
-    const pipeline = this.pipeline;
-    const enqueueVersion = internalVersion === "" ? null : internalVersion;
-    const jobId = await pipeline.enqueueJob(library, enqueueVersion, {
-      url,
-      library,
-      version: internalVersion,
-      scope: scraperOptions?.scope ?? "subpages",
-      followRedirects: scraperOptions?.followRedirects ?? true,
-      maxPages: scraperOptions?.maxPages ?? DEFAULT_MAX_PAGES,
-      maxDepth: scraperOptions?.maxDepth ?? DEFAULT_MAX_DEPTH$1,
-      maxConcurrency: scraperOptions?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
-      ignoreErrors: scraperOptions?.ignoreErrors ?? true,
-      scrapeMode: scraperOptions?.scrapeMode ?? ScrapeMode.Auto,
-      // Pass scrapeMode enum
-      includePatterns: scraperOptions?.includePatterns,
-      excludePatterns: scraperOptions?.excludePatterns,
-      headers: scraperOptions?.headers
-      // <-- propagate headers
-    });
-    if (waitForCompletion) {
-      try {
-        await pipeline.waitForJobCompletion(jobId);
-        const finalJob = await pipeline.getJob(jobId);
-        const finalPagesScraped = finalJob?.progress?.pagesScraped ?? 0;
-        logger.debug(
-          `Job ${jobId} finished with status ${finalJob?.status}. Pages scraped: ${finalPagesScraped}`
-        );
-        return {
-          pagesScraped: finalPagesScraped
-        };
-      } catch (error) {
-        logger.error(`❌ Job ${jobId} failed or was cancelled: ${error}`);
-        throw error;
-      }
-    }
-    return { jobId };
+        internalVersion = internalVersion.toLowerCase();
+        const pipeline = this.pipeline;
+        const enqueueVersion = internalVersion === "" ? null : internalVersion;
+        const jobId = await pipeline.enqueueJob(library, enqueueVersion, {
+          url,
+          library,
+          version: internalVersion,
+          scope: scraperOptions?.scope ?? "subpages",
+          followRedirects: scraperOptions?.followRedirects ?? true,
+          maxPages: scraperOptions?.maxPages ?? DEFAULT_MAX_PAGES,
+          maxDepth: scraperOptions?.maxDepth ?? DEFAULT_MAX_DEPTH$1,
+          maxConcurrency: scraperOptions?.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY,
+          ignoreErrors: scraperOptions?.ignoreErrors ?? true,
+          scrapeMode: scraperOptions?.scrapeMode ?? ScrapeMode.Auto,
+          // Pass scrapeMode enum
+          includePatterns: scraperOptions?.includePatterns,
+          excludePatterns: scraperOptions?.excludePatterns,
+          headers: scraperOptions?.headers
+          // <-- propagate headers
+        });
+        if (waitForCompletion) {
+          try {
+            await pipeline.waitForJobCompletion(jobId);
+            const finalJob = await pipeline.getJob(jobId);
+            const finalPagesScraped = finalJob?.progress?.pagesScraped ?? 0;
+            logger.debug(
+              `Job ${jobId} finished with status ${finalJob?.status}. Pages scraped: ${finalPagesScraped}`
+            );
+            return {
+              pagesScraped: finalPagesScraped
+            };
+          } catch (error) {
+            logger.error(`❌ Job ${jobId} failed or was cancelled: ${error}`);
+            throw error;
+          }
+        }
+        return { jobId };
+      },
+      (result) => ({
+        library,
+        version: version2,
+        url,
+        waitForCompletion,
+        ...scraperOptions,
+        isBackgroundJob: "jobId" in result,
+        pagesScraped: "pagesScraped" in result ? result.pagesScraped : void 0
+      })
+    );
   }
 }
 class SearchTool {
@@ -2284,43 +2749,56 @@ class SearchTool {
   }
   async execute(options) {
     const { library, version: version2, query, limit = 5, exactMatch = false } = options;
-    if (exactMatch && (!version2 || version2 === "latest")) {
-      await this.docService.validateLibraryExists(library);
-      const allLibraries = await this.docService.listLibraries();
-      const libraryInfo = allLibraries.find((lib) => lib.library === library);
-      const detailedVersions = libraryInfo ? libraryInfo.versions.map((v) => ({
-        version: v.ref.version,
-        documentCount: v.counts.documents,
-        uniqueUrlCount: v.counts.uniqueUrls,
-        indexedAt: v.indexedAt
-      })) : [];
-      throw new VersionNotFoundError(library, version2 ?? "latest", detailedVersions);
-    }
-    const resolvedVersion = version2 || "latest";
-    logger.info(
-      `🔍 Searching ${library}@${resolvedVersion} for: ${query}${exactMatch ? " (exact match)" : ""}`
-    );
-    try {
-      await this.docService.validateLibraryExists(library);
-      let versionToSearch = resolvedVersion;
-      if (!exactMatch) {
-        const versionResult = await this.docService.findBestVersion(library, version2);
-        versionToSearch = versionResult.bestMatch;
-      }
-      const results = await this.docService.searchStore(
+    return analytics.trackTool(
+      "search_docs",
+      async () => {
+        if (exactMatch && (!version2 || version2 === "latest")) {
+          await this.docService.validateLibraryExists(library);
+          const allLibraries = await this.docService.listLibraries();
+          const libraryInfo = allLibraries.find((lib) => lib.library === library);
+          const detailedVersions = libraryInfo ? libraryInfo.versions.map((v) => ({
+            version: v.ref.version,
+            documentCount: v.counts.documents,
+            uniqueUrlCount: v.counts.uniqueUrls,
+            indexedAt: v.indexedAt
+          })) : [];
+          throw new VersionNotFoundError(library, version2 ?? "latest", detailedVersions);
+        }
+        const resolvedVersion = version2 || "latest";
+        logger.info(
+          `🔍 Searching ${library}@${resolvedVersion} for: ${query}${exactMatch ? " (exact match)" : ""}`
+        );
+        try {
+          await this.docService.validateLibraryExists(library);
+          let versionToSearch = resolvedVersion;
+          if (!exactMatch) {
+            const versionResult = await this.docService.findBestVersion(library, version2);
+            versionToSearch = versionResult.bestMatch;
+          }
+          const results = await this.docService.searchStore(
+            library,
+            versionToSearch,
+            query,
+            limit
+          );
+          logger.info(`✅ Found ${results.length} matching results`);
+          return { results };
+        } catch (error) {
+          logger.error(
+            `❌ Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
+          );
+          throw error;
+        }
+      },
+      (result) => ({
         library,
-        versionToSearch,
+        version: version2,
         query,
-        limit
-      );
-      logger.info(`✅ Found ${results.length} matching results`);
-      return { results };
-    } catch (error) {
-      logger.error(
-        `❌ Search failed: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
-      throw error;
-    }
+        limit,
+        exactMatch,
+        resultCount: result.results.length
+      })
+    );
   }
 }
 function createResponse(text) {
@@ -3050,6 +3528,7 @@ async function registerMcpService(server, docService, pipeline, readOnly = false
             authEnabled: !!authManager,
             readOnly,
             servicesEnabled: ["mcp"]
+            // Embedding context will be resolved by the service that starts MCP
           });
           analytics.startSession(session);
         }
@@ -3100,23 +3579,10 @@ async function registerMcpService(server, docService, pipeline, readOnly = false
         const requestTransport = new StreamableHTTPServerTransport({
           sessionIdGenerator: void 0
         });
-        if (analytics.isEnabled()) {
-          const session = createMcpSession({
-            protocol: "http",
-            transport: "streamable",
-            authEnabled: !!authManager,
-            readOnly,
-            servicesEnabled: ["mcp"]
-          });
-          analytics.startSession(session);
-        }
         reply.raw.on("close", () => {
           logger.debug("Streamable HTTP request closed");
           requestTransport.close();
           requestServer.close();
-          if (analytics.isEnabled()) {
-            analytics.endSession();
-          }
         });
         await requestServer.connect(requestTransport);
         await requestTransport.handleRequest(request.raw, reply.raw, request.body);
@@ -3260,6 +3726,15 @@ function createDataRouter(trpc) {
         return results;
       }
     ),
+    removeVersion: tt.procedure.input(z$1.object({ library: nonEmpty, version: optionalVersion })).mutation(
+      async ({
+        ctx,
+        input
+      }) => {
+        await ctx.docService.removeVersion(input.library, input.version ?? null);
+        return { ok: true };
+      }
+    ),
     removeAllDocuments: tt.procedure.input(z$1.object({ library: nonEmpty, version: optionalVersion })).mutation(
       async ({
         ctx,
@@ -3517,97 +3992,30 @@ function registerClearCompletedJobsRoute(server, clearCompletedJobsTool) {
     }
   });
 }
-const VECTOR_DIMENSION = 1536;
-function mapDbDocumentToDocument(doc) {
-  return {
-    id: doc.id,
-    pageContent: doc.content,
-    metadata: JSON.parse(doc.metadata)
-  };
-}
-var VersionStatus = /* @__PURE__ */ ((VersionStatus2) => {
-  VersionStatus2["NOT_INDEXED"] = "not_indexed";
-  VersionStatus2["QUEUED"] = "queued";
-  VersionStatus2["RUNNING"] = "running";
-  VersionStatus2["COMPLETED"] = "completed";
-  VersionStatus2["FAILED"] = "failed";
-  VersionStatus2["CANCELLED"] = "cancelled";
-  VersionStatus2["UPDATING"] = "updating";
-  return VersionStatus2;
-})(VersionStatus || {});
-function normalizeVersionName(name) {
-  return name ?? "";
-}
-function denormalizeVersionName(name) {
-  return name === "" ? "" : name;
-}
-function getStatusDescription(status) {
-  const descriptions = {
-    [
-      "not_indexed"
-      /* NOT_INDEXED */
-    ]: "Version created but not yet indexed",
-    [
-      "queued"
-      /* QUEUED */
-    ]: "Waiting in queue for indexing",
-    [
-      "running"
-      /* RUNNING */
-    ]: "Currently being indexed",
-    [
-      "completed"
-      /* COMPLETED */
-    ]: "Successfully indexed",
-    [
-      "failed"
-      /* FAILED */
-    ]: "Indexing failed",
-    [
-      "cancelled"
-      /* CANCELLED */
-    ]: "Indexing was cancelled",
-    [
-      "updating"
-      /* UPDATING */
-    ]: "Re-indexing in progress"
-  };
-  return descriptions[status] || "Unknown status";
-}
-function isActiveStatus(status) {
-  return [
-    "queued",
-    "running",
-    "updating"
-    /* UPDATING */
-  ].includes(
-    status
-  );
-}
-const VersionBadge = ({ version: version2 }) => {
-  if (!version2) {
-    return null;
-  }
-  return /* @__PURE__ */ jsx("span", { class: "bg-purple-100 text-purple-800 text-xs font-medium me-2 px-1.5 py-0.5 rounded dark:bg-purple-900 dark:text-purple-300", children: /* @__PURE__ */ jsx("span", { safe: true, children: version2 }) });
-};
-function getStatusClasses(status) {
-  const baseClasses = "px-1.5 py-0.5 text-xs font-medium rounded";
-  switch (status) {
-    case VersionStatus.COMPLETED:
-      return `${baseClasses} bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300`;
-    case VersionStatus.RUNNING:
-    case VersionStatus.UPDATING:
-      return `${baseClasses} bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300`;
-    case VersionStatus.QUEUED:
-      return `${baseClasses} bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-300`;
-    case VersionStatus.FAILED:
-      return `${baseClasses} bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300`;
-    case VersionStatus.CANCELLED:
-      return `${baseClasses} bg-gray-100 text-gray-800 dark:bg-gray-900 dark:text-gray-300`;
-    case VersionStatus.NOT_INDEXED:
-    default:
-      return `${baseClasses} bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400`;
-  }
+const VersionBadge = ({ version: version2 }) => {
+  if (!version2) {
+    return null;
+  }
+  return /* @__PURE__ */ jsx("span", { class: "bg-purple-100 text-purple-800 text-xs font-medium me-2 px-1.5 py-0.5 rounded dark:bg-purple-900 dark:text-purple-300", children: /* @__PURE__ */ jsx("span", { safe: true, children: version2 }) });
+};
+function getStatusClasses(status) {
+  const baseClasses = "px-1.5 py-0.5 text-xs font-medium rounded";
+  switch (status) {
+    case VersionStatus.COMPLETED:
+      return `${baseClasses} bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300`;
+    case VersionStatus.RUNNING:
+    case VersionStatus.UPDATING:
+      return `${baseClasses} bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300`;
+    case VersionStatus.QUEUED:
+      return `${baseClasses} bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-300`;
+    case VersionStatus.FAILED:
+      return `${baseClasses} bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300`;
+    case VersionStatus.CANCELLED:
+      return `${baseClasses} bg-gray-100 text-gray-800 dark:bg-gray-900 dark:text-gray-300`;
+    case VersionStatus.NOT_INDEXED:
+    default:
+      return `${baseClasses} bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-400`;
+  }
 }
 const StatusBadge = ({ status, showDescription = true }) => /* @__PURE__ */ jsx("span", { class: getStatusClasses(status), children: showDescription ? getStatusDescription(status) : status });
 const ProgressBar = ({ progress, showText = true }) => {
@@ -4939,16 +5347,12 @@ async function registerWorkerService(pipeline) {
       logger.warn(
         `⚠️ Job ${job.id} error ${document ? `on document ${document.metadata.url}` : ""}: ${error.message}`
       );
-      const errorInfo = sanitizeError(error);
-      analytics.track(TelemetryEvent.ERROR_OCCURRED, {
+      analytics.captureException(error, {
         jobId: job.id,
         // Job IDs are already anonymous
         library: job.library,
-        errorType: errorInfo.type,
-        errorMessage: errorInfo.message,
         hasDocument: !!document,
         stage: document ? "document_processing" : "job_setup",
-        hasStack: errorInfo.hasStack,
         pages_processed_before_error: job.progressPages || 0
       });
     }
@@ -5027,13 +5431,13 @@ class AppServer {
       try {
         telemetryService.startSession({
           sessionId: crypto.randomUUID(),
-          interface: "web",
+          appInterface: "web",
           startTime: /* @__PURE__ */ new Date(),
-          version: process.env.npm_package_version || "unknown",
-          platform: process.platform,
-          servicesEnabled: this.getActiveServicesList(),
-          authEnabled: Boolean(this.config.auth),
-          readOnly: Boolean(this.config.readOnly)
+          appVersion: process.env.npm_package_version || "unknown",
+          appPlatform: process.platform,
+          appServicesEnabled: this.getActiveServicesList(),
+          appAuthEnabled: Boolean(this.config.auth),
+          appReadOnly: Boolean(this.config.readOnly)
         });
       } catch (error) {
         logger.debug(`Failed to initialize telemetry: ${error}`);
@@ -5110,11 +5514,10 @@ class AppServer {
       process.on("unhandledRejection", (reason) => {
         logger.error(`Unhandled Promise Rejection: ${reason}`);
         if (analytics.isEnabled()) {
-          analytics.track(TelemetryEvent.ERROR_OCCURRED, {
-            error_type: "UnhandledPromiseRejection",
+          const error = reason instanceof Error ? reason : new Error(String(reason));
+          analytics.captureException(error, {
             error_category: "system",
-            component: "AppServer",
-            severity: "critical",
+            component: AppServer.constructor.name,
             context: "process_unhandled_rejection"
           });
         }
@@ -5124,11 +5527,9 @@ class AppServer {
       process.on("uncaughtException", (error) => {
         logger.error(`Uncaught Exception: ${error.message}`);
         if (analytics.isEnabled()) {
-          analytics.track(TelemetryEvent.ERROR_OCCURRED, {
-            error_type: error.constructor.name,
+          analytics.captureException(error, {
             error_category: "system",
-            component: "AppServer",
-            severity: "critical",
+            component: AppServer.constructor.name,
             context: "process_uncaught_exception"
           });
         }
@@ -5137,11 +5538,9 @@ class AppServer {
     if (typeof this.server.setErrorHandler === "function") {
       this.server.setErrorHandler(async (error, request, reply) => {
         if (analytics.isEnabled()) {
-          analytics.track(TelemetryEvent.ERROR_OCCURRED, {
-            error_type: error.constructor.name,
+          analytics.captureException(error, {
             error_category: "http",
             component: "FastifyServer",
-            severity: "high",
             status_code: error.statusCode || 500,
             method: request.method,
             route: request.routeOptions?.url || request.url,
@@ -5273,195 +5672,2564 @@ class AppServer {
     logger.debug("OAuth2 proxy endpoints registered");
   }
   /**
-   * Log startup information showing which services are enabled.
+   * Log startup information showing which services are enabled.
+   */
+  logStartupInfo(address) {
+    logger.info(`🚀 AppServer available at ${address}`);
+    const enabledServices = [];
+    if (this.config.enableWebInterface) {
+      enabledServices.push(`Web interface: ${address}`);
+    }
+    if (this.config.enableMcpServer) {
+      enabledServices.push(`MCP endpoints: ${address}/mcp, ${address}/sse`);
+    }
+    if (this.config.enableApiServer) {
+      enabledServices.push(`API: ${address}/api`);
+    }
+    if (this.config.enableWorker) {
+      enabledServices.push("Embedded worker: enabled");
+    } else if (this.config.externalWorkerUrl) {
+      enabledServices.push(`External worker: ${this.config.externalWorkerUrl}`);
+    }
+    for (const service of enabledServices) {
+      logger.info(`   • ${service}`);
+    }
+  }
+}
+async function startAppServer(docService, pipeline, config) {
+  const appServer = new AppServer(docService, pipeline, config);
+  await appServer.start();
+  return appServer;
+}
+async function startStdioServer(tools, readOnly = false) {
+  setLogLevel(LogLevel.ERROR);
+  const server = createMcpServerInstance(tools, readOnly);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info("🤖 MCP server listening on stdio");
+  return server;
+}
+class DocumentManagementClient {
+  baseUrl;
+  client;
+  constructor(serverUrl) {
+    this.baseUrl = serverUrl.replace(/\/$/, "");
+    this.client = createTRPCProxyClient({
+      links: [httpBatchLink({ url: this.baseUrl })]
+    });
+    logger.debug(`DocumentManagementClient (tRPC) created for: ${this.baseUrl}`);
+  }
+  async initialize() {
+    await this.client.ping.query();
+  }
+  async shutdown() {
+  }
+  async listLibraries() {
+    return this.client.listLibraries.query();
+  }
+  async validateLibraryExists(library) {
+    await this.client.validateLibraryExists.mutate({ library });
+  }
+  async findBestVersion(library, targetVersion) {
+    return this.client.findBestVersion.query({ library, targetVersion });
+  }
+  async searchStore(library, version2, query, limit) {
+    return this.client.search.query({ library, version: version2 ?? null, query, limit });
+  }
+  async removeVersion(library, version2) {
+    await this.client.removeVersion.mutate({ library, version: version2 });
+  }
+  async removeAllDocuments(library, version2) {
+    await this.client.removeAllDocuments.mutate({ library, version: version2 ?? null });
+  }
+  async getVersionsByStatus(statuses) {
+    return this.client.getVersionsByStatus.query({
+      statuses
+    });
+  }
+  async findVersionsBySourceUrl(url) {
+    return this.client.findVersionsBySourceUrl.query({ url });
+  }
+  async getScraperOptions(versionId) {
+    return this.client.getScraperOptions.query({ versionId });
+  }
+  async updateVersionStatus(versionId, status, errorMessage) {
+    await this.client.updateVersionStatus.mutate({ versionId, status, errorMessage });
+  }
+  async updateVersionProgress(versionId, pages, maxPages) {
+    await this.client.updateVersionProgress.mutate({ versionId, pages, maxPages });
+  }
+  async storeScraperOptions(versionId, options) {
+    await this.client.storeScraperOptions.mutate({ versionId, options });
+  }
+}
+class SplitterError extends Error {
+}
+class MinimumChunkSizeError extends SplitterError {
+  constructor(size, maxSize) {
+    super(
+      `Cannot split content any further. Content requires minimum chunk size of ${size} bytes, but maximum allowed is ${maxSize} bytes.`
+    );
+  }
+}
+class ContentSplitterError extends SplitterError {
+}
+class GreedySplitter {
+  baseSplitter;
+  minChunkSize;
+  preferredChunkSize;
+  /**
+   * Combines a base document splitter with size constraints to produce optimally-sized chunks.
+   * The base splitter handles the initial semantic splitting, while this class handles
+   * the concatenation strategy.
+   */
+  constructor(baseSplitter, minChunkSize, preferredChunkSize) {
+    this.baseSplitter = baseSplitter;
+    this.minChunkSize = minChunkSize;
+    this.preferredChunkSize = preferredChunkSize;
+  }
+  /**
+   * Uses a greedy concatenation strategy to build optimally-sized chunks. Small chunks
+   * are combined until they reach the minimum size, but splits are preserved at major
+   * section boundaries to maintain document structure. This balances the need for
+   * context with semantic coherence.
+   */
+  async splitText(markdown) {
+    const initialChunks = await this.baseSplitter.splitText(markdown);
+    const concatenatedChunks = [];
+    let currentChunk = null;
+    for (const nextChunk of initialChunks) {
+      if (currentChunk) {
+        if (this.wouldExceedMaxSize(currentChunk, nextChunk)) {
+          concatenatedChunks.push(currentChunk);
+          currentChunk = this.cloneChunk(nextChunk);
+          continue;
+        }
+        if (currentChunk.content.length >= this.minChunkSize && this.startsNewMajorSection(nextChunk)) {
+          concatenatedChunks.push(currentChunk);
+          currentChunk = this.cloneChunk(nextChunk);
+          continue;
+        }
+        currentChunk.content += `
+${nextChunk.content}`;
+        currentChunk.section = this.mergeSectionInfo(currentChunk, nextChunk);
+        currentChunk.types = this.mergeTypes(currentChunk.types, nextChunk.types);
+      } else {
+        currentChunk = this.cloneChunk(nextChunk);
+      }
+    }
+    if (currentChunk) {
+      concatenatedChunks.push(currentChunk);
+    }
+    return concatenatedChunks;
+  }
+  cloneChunk(chunk) {
+    return {
+      types: [...chunk.types],
+      content: chunk.content,
+      section: {
+        level: chunk.section.level,
+        path: [...chunk.section.path]
+      }
+    };
+  }
+  /**
+   * H1 and H2 headings represent major conceptual breaks in the document.
+   * Preserving these splits helps maintain the document's logical structure.
+   */
+  startsNewMajorSection(chunk) {
+    return chunk.section.level === 1 || chunk.section.level === 2;
+  }
+  /**
+   * Size limit check to ensure chunks remain within embedding model constraints.
+   * Essential for maintaining consistent embedding quality and avoiding truncation.
+   */
+  wouldExceedMaxSize(currentChunk, nextChunk) {
+    if (!currentChunk) {
+      return false;
+    }
+    return currentChunk.content.length + nextChunk.content.length > this.preferredChunkSize;
+  }
+  /**
+   * Checks if one path is a prefix of another path, indicating a parent-child relationship
+   */
+  isPathIncluded(parentPath, childPath) {
+    if (parentPath.length >= childPath.length) return false;
+    return parentPath.every((part, i) => part === childPath[i]);
+  }
+  /**
+   * Merges section metadata when concatenating chunks, following these rules:
+   * 1. Level: Always uses the lowest (most general) level between chunks
+   * 2. Path selection:
+   *    - For parent-child relationships (one path includes the other), uses the child's path
+   *    - For siblings/unrelated sections, uses the common parent path
+   *    - If no common path exists, uses the root path ([])
+   */
+  mergeSectionInfo(currentChunk, nextChunk) {
+    const level = Math.min(currentChunk.section.level, nextChunk.section.level);
+    if (currentChunk.section.level === nextChunk.section.level && currentChunk.section.path.length === nextChunk.section.path.length && currentChunk.section.path.every((p, i) => p === nextChunk.section.path[i])) {
+      return currentChunk.section;
+    }
+    if (this.isPathIncluded(currentChunk.section.path, nextChunk.section.path)) {
+      return {
+        path: nextChunk.section.path,
+        level
+      };
+    }
+    if (this.isPathIncluded(nextChunk.section.path, currentChunk.section.path)) {
+      return {
+        path: currentChunk.section.path,
+        level
+      };
+    }
+    const commonPath = this.findCommonPrefix(
+      currentChunk.section.path,
+      nextChunk.section.path
+    );
+    return {
+      path: commonPath,
+      level
+    };
+  }
+  mergeTypes(currentTypes, nextTypes) {
+    return [.../* @__PURE__ */ new Set([...currentTypes, ...nextTypes])];
+  }
+  /**
+   * Returns longest common prefix between two paths
+   */
+  findCommonPrefix(path1, path2) {
+    const common = [];
+    for (let i = 0; i < Math.min(path1.length, path2.length); i++) {
+      if (path1[i] === path2[i]) {
+        common.push(path1[i]);
+      } else {
+        break;
+      }
+    }
+    return common;
+  }
+}
+const fullTrim = (str) => {
+  return str.replace(/^[\s\r\n\t]+|[\s\r\n\t]+$/g, "");
+};
+class CodeContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  async split(content) {
+    const language = content.match(/^```(\w+)\n/)?.[1];
+    const strippedContent = content.replace(/^```(\w*)\n/, "").replace(/```\s*$/, "");
+    const lines = strippedContent.split("\n");
+    const chunks = [];
+    let currentChunkLines = [];
+    for (const line of lines) {
+      const singleLineSize = this.wrap(line, language).length;
+      if (singleLineSize > this.options.chunkSize) {
+        throw new MinimumChunkSizeError(singleLineSize, this.options.chunkSize);
+      }
+      currentChunkLines.push(line);
+      const newChunkContent = this.wrap(currentChunkLines.join("\n"), language);
+      const newChunkSize = newChunkContent.length;
+      if (newChunkSize > this.options.chunkSize && currentChunkLines.length > 1) {
+        const lastLine = currentChunkLines.pop();
+        chunks.push(this.wrap(currentChunkLines.join("\n"), language));
+        currentChunkLines = [lastLine];
+      }
+    }
+    if (currentChunkLines.length > 0) {
+      chunks.push(this.wrap(currentChunkLines.join("\n"), language));
+    }
+    return chunks;
+  }
+  wrap(content, language) {
+    return `\`\`\`${language || ""}
+${content.replace(/\n+$/, "")}
+\`\`\``;
+  }
+}
+class TableContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Splits table content into chunks while preserving table structure
+   */
+  async split(content) {
+    const parsedTable = this.parseTable(content);
+    if (!parsedTable) {
+      return [content];
+    }
+    const { headers, rows } = parsedTable;
+    const chunks = [];
+    let currentRows = [];
+    for (const row of rows) {
+      const singleRowSize = this.wrap(row, headers).length;
+      if (singleRowSize > this.options.chunkSize) {
+        throw new MinimumChunkSizeError(singleRowSize, this.options.chunkSize);
+      }
+      const newChunkContent = this.wrap([...currentRows, row].join("\n"), headers);
+      const newChunkSize = newChunkContent.length;
+      if (newChunkSize > this.options.chunkSize && currentRows.length > 0) {
+        chunks.push(this.wrap(currentRows.join("\n"), headers));
+        currentRows = [row];
+      } else {
+        currentRows.push(row);
+      }
+    }
+    if (currentRows.length > 0) {
+      chunks.push(this.wrap(currentRows.join("\n"), headers));
+    }
+    return chunks;
+  }
+  wrap(content, headers) {
+    const headerRow = `| ${headers.join(" | ")} |`;
+    const separatorRow = `|${headers.map(() => "---").join("|")}|`;
+    return [headerRow, separatorRow, content].join("\n");
+  }
+  parseTable(content) {
+    const lines = content.trim().split("\n");
+    if (lines.length < 3) return null;
+    const headers = this.parseRow(lines[0]);
+    if (!headers) return null;
+    const separator = lines[1];
+    if (!this.isValidSeparator(separator)) return null;
+    const rows = lines.slice(2).filter((row) => row.trim() !== "");
+    return { headers, separator, rows };
+  }
+  /**
+   * Parses a table row into cells
+   */
+  parseRow(row) {
+    if (!row.includes("|")) return null;
+    return row.split("|").map((cell) => cell.trim()).filter((cell) => cell !== "");
+  }
+  /**
+   * Validates the separator row of the table
+   */
+  isValidSeparator(separator) {
+    return separator.includes("|") && /^\|?[\s-|]+\|?$/.test(separator);
+  }
+}
+class TextContentSplitter {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Splits text content into chunks while trying to preserve semantic boundaries.
+   * Prefers paragraph breaks, then line breaks, finally falling back to word boundaries.
+   */
+  async split(content) {
+    const trimmedContent = fullTrim(content);
+    if (trimmedContent.length <= this.options.chunkSize) {
+      return [trimmedContent];
+    }
+    const words = trimmedContent.split(/\s+/);
+    const longestWord = words.reduce(
+      (max, word) => word.length > max.length ? word : max
+    );
+    if (longestWord.length > this.options.chunkSize) {
+      throw new MinimumChunkSizeError(longestWord.length, this.options.chunkSize);
+    }
+    const paragraphChunks = this.splitByParagraphs(trimmedContent);
+    if (this.areChunksValid(paragraphChunks)) {
+      return paragraphChunks;
+    }
+    const lineChunks = this.splitByLines(trimmedContent);
+    if (this.areChunksValid(lineChunks)) {
+      return this.mergeChunks(lineChunks, "\n");
+    }
+    const wordChunks = await this.splitByWords(trimmedContent);
+    return this.mergeChunks(wordChunks, " ");
+  }
+  /**
+   * Checks if all chunks are within the maximum size limit
+   */
+  areChunksValid(chunks) {
+    return chunks.every((chunk) => chunk.length <= this.options.chunkSize);
+  }
+  /**
+   * Splits text into chunks by paragraph boundaries (double newlines)
+   */
+  splitByParagraphs(text) {
+    const paragraphs = text.split(/\n\s*\n/).map((p) => fullTrim(p)).filter(Boolean);
+    return paragraphs.filter((chunk) => chunk.length > 2);
+  }
+  /**
+   * Splits text into chunks by line boundaries
+   */
+  splitByLines(text) {
+    const lines = text.split(/\n/).map((line) => fullTrim(line)).filter(Boolean);
+    return lines.filter((chunk) => chunk.length > 1);
+  }
+  /**
+   * Uses LangChain's recursive splitter for word-based splitting as a last resort
+   */
+  async splitByWords(text) {
+    const splitter = new RecursiveCharacterTextSplitter({
+      chunkSize: this.options.chunkSize,
+      chunkOverlap: 0
+    });
+    const chunks = await splitter.splitText(text);
+    return chunks;
+  }
+  /**
+   * Attempts to merge small chunks with previous chunks to minimize fragmentation.
+   * Only merges if combined size is within maxChunkSize.
+   */
+  mergeChunks(chunks, separator) {
+    const mergedChunks = [];
+    let currentChunk = null;
+    for (const chunk of chunks) {
+      if (currentChunk === null) {
+        currentChunk = chunk;
+        continue;
+      }
+      const currentChunkSize = this.getChunkSize(currentChunk);
+      const nextChunkSize = this.getChunkSize(chunk);
+      if (currentChunkSize + nextChunkSize + separator.length <= this.options.chunkSize) {
+        currentChunk = `${currentChunk}${separator}${chunk}`;
+      } else {
+        mergedChunks.push(currentChunk);
+        currentChunk = chunk;
+      }
+    }
+    if (currentChunk) {
+      mergedChunks.push(currentChunk);
+    }
+    return mergedChunks;
+  }
+  getChunkSize(chunk) {
+    return chunk.length;
+  }
+  wrap(content) {
+    return content;
+  }
+}
+class SemanticMarkdownSplitter {
+  constructor(preferredChunkSize, maxChunkSize) {
+    this.preferredChunkSize = preferredChunkSize;
+    this.maxChunkSize = maxChunkSize;
+    this.turndownService = new TurndownService({
+      headingStyle: "atx",
+      hr: "---",
+      bulletListMarker: "-",
+      codeBlockStyle: "fenced",
+      emDelimiter: "_",
+      strongDelimiter: "**",
+      linkStyle: "inlined"
+    });
+    this.turndownService.addRule("table", {
+      filter: ["table"],
+      replacement: (_content, node) => {
+        const table = node;
+        const headers = Array.from(table.querySelectorAll("th")).map(
+          (th) => th.textContent?.trim() || ""
+        );
+        const rows = Array.from(table.querySelectorAll("tr")).filter(
+          (tr) => !tr.querySelector("th")
+        );
+        if (headers.length === 0 && rows.length === 0) return "";
+        let markdown = "\n";
+        if (headers.length > 0) {
+          markdown += `| ${headers.join(" | ")} |
+`;
+          markdown += `|${headers.map(() => "---").join("|")}|
+`;
+        }
+        for (const row of rows) {
+          const cells = Array.from(row.querySelectorAll("td")).map(
+            (td) => td.textContent?.trim() || ""
+          );
+          markdown += `| ${cells.join(" | ")} |
+`;
+        }
+        return markdown;
+      }
+    });
+    this.textSplitter = new TextContentSplitter({
+      chunkSize: this.preferredChunkSize
+    });
+    this.codeSplitter = new CodeContentSplitter({
+      chunkSize: this.maxChunkSize
+    });
+    this.tableSplitter = new TableContentSplitter({
+      chunkSize: this.maxChunkSize
+    });
+  }
+  turndownService;
+  textSplitter;
+  codeSplitter;
+  tableSplitter;
+  /**
+   * Main entry point for splitting markdown content
+   */
+  async splitText(markdown) {
+    const html = await this.markdownToHtml(markdown);
+    const dom = await this.parseHtml(html);
+    const sections = await this.splitIntoSections(dom);
+    return this.splitSectionContent(sections);
+  }
+  /**
+   * Step 1: Split document into sections based on H1-H6 headings,
+   * as well as code blocks and tables.
+   */
+  async splitIntoSections(dom) {
+    const body = dom.querySelector("body");
+    if (!body) {
+      throw new Error("Invalid HTML structure: no body element found");
+    }
+    let currentSection = this.createRootSection();
+    const sections = [];
+    const stack = [currentSection];
+    for (const element of Array.from(body.children)) {
+      const headingMatch = element.tagName.match(/H([1-6])/);
+      if (headingMatch) {
+        const level = Number.parseInt(headingMatch[1], 10);
+        const title = fullTrim(element.textContent || "");
+        while (stack.length > 1 && stack[stack.length - 1].level >= level) {
+          stack.pop();
+        }
+        currentSection = {
+          level,
+          path: [
+            ...stack.slice(1).reduce((acc, s) => {
+              const lastPath = s.path[s.path.length - 1];
+              if (lastPath) acc.push(lastPath);
+              return acc;
+            }, []),
+            title
+          ],
+          content: [
+            {
+              type: "heading",
+              text: `${"#".repeat(level)} ${title}`
+            }
+          ]
+        };
+        sections.push(currentSection);
+        stack.push(currentSection);
+      } else if (element.tagName === "PRE") {
+        const code = element.querySelector("code");
+        const language = code?.className.replace("language-", "") || "";
+        const content = code?.textContent || element.textContent || "";
+        const markdown = `${"```"}${language}
+${content}
+${"```"}`;
+        currentSection = {
+          level: currentSection.level,
+          path: currentSection.path,
+          content: [
+            {
+              type: "code",
+              text: markdown
+            }
+          ]
+        };
+        sections.push(currentSection);
+      } else if (element.tagName === "TABLE") {
+        const markdown = fullTrim(this.turndownService.turndown(element.outerHTML));
+        currentSection = {
+          level: currentSection.level,
+          path: currentSection.path,
+          content: [
+            {
+              type: "table",
+              text: markdown
+            }
+          ]
+        };
+        sections.push(currentSection);
+      } else {
+        const markdown = fullTrim(this.turndownService.turndown(element.innerHTML));
+        if (markdown) {
+          currentSection = {
+            level: currentSection.level,
+            path: currentSection.path,
+            content: [
+              {
+                type: "text",
+                text: markdown
+              }
+            ]
+          };
+          sections.push(currentSection);
+        }
+      }
+    }
+    return sections;
+  }
+  /**
+   * Step 2: Split section content into smaller chunks
+   */
+  async splitSectionContent(sections) {
+    const chunks = [];
+    for (const section of sections) {
+      for (const content of section.content) {
+        let splitContent = [];
+        try {
+          switch (content.type) {
+            case "heading":
+            case "text": {
+              splitContent = await this.textSplitter.split(content.text);
+              break;
+            }
+            case "code": {
+              splitContent = await this.codeSplitter.split(content.text);
+              break;
+            }
+            case "table": {
+              splitContent = await this.tableSplitter.split(content.text);
+              break;
+            }
+          }
+        } catch (err) {
+          if (err instanceof MinimumChunkSizeError) {
+            logger.warn(
+              `⚠ Cannot split ${content.type} chunk normally, using RecursiveCharacterTextSplitter: ${err.message}`
+            );
+            const splitter = new RecursiveCharacterTextSplitter({
+              chunkSize: this.maxChunkSize,
+              chunkOverlap: Math.min(20, Math.floor(this.maxChunkSize * 0.1)),
+              // Use more aggressive separators including empty string as last resort
+              separators: [
+                "\n\n",
+                "\n",
+                " ",
+                "	",
+                ".",
+                ",",
+                ";",
+                ":",
+                "-",
+                "(",
+                ")",
+                "[",
+                "]",
+                "{",
+                "}",
+                ""
+              ]
+            });
+            const chunks2 = await splitter.splitText(content.text);
+            if (chunks2.length === 0) {
+              splitContent = [content.text.substring(0, this.maxChunkSize)];
+            } else {
+              splitContent = chunks2;
+            }
+          } else {
+            const errMessage = err instanceof Error ? err.message : String(err);
+            throw new ContentSplitterError(
+              `Failed to split ${content.type} content: ${errMessage}`
+            );
+          }
+        }
+        chunks.push(
+          ...splitContent.map(
+            (text) => ({
+              types: [content.type],
+              content: text,
+              section: {
+                level: section.level,
+                path: section.path
+              }
+            })
+          )
+        );
+      }
+    }
+    return chunks;
+  }
+  /**
+   * Helper to create the root section
+   */
+  createRootSection() {
+    return {
+      level: 0,
+      path: [],
+      content: []
+    };
+  }
+  /**
+   * Convert markdown to HTML using remark
+   */
+  async markdownToHtml(markdown) {
+    const html = await unified().use(remarkParse).use(remarkGfm).use(remarkHtml).process(markdown);
+    return `<!DOCTYPE html>
+      <html>
+        <body>
+          ${String(html)}
+        </body>
+      </html>`;
+  }
+  /**
+   * Parse HTML
+   */
+  async parseHtml(html) {
+    const { window } = createJSDOM(html);
+    return window.document;
+  }
+}
+const CHILD_LIMIT = 5;
+const SIBLING_LIMIT = 2;
+class DocumentRetrieverService {
+  documentStore;
+  constructor(documentStore) {
+    this.documentStore = documentStore;
+  }
+  /**
+   * Collects all related chunk IDs for a given initial hit.
+   * Returns an object with url, hitId, relatedIds (Set), and score.
+   */
+  async getRelatedChunkIds(library, version2, doc, siblingLimit = SIBLING_LIMIT, childLimit = CHILD_LIMIT) {
+    const id = doc.id;
+    const url = doc.metadata.url;
+    const score = doc.metadata.score;
+    const relatedIds = /* @__PURE__ */ new Set();
+    relatedIds.add(id);
+    const parent = await this.documentStore.findParentChunk(library, version2, id);
+    if (parent) {
+      relatedIds.add(parent.id);
+    }
+    const precedingSiblings = await this.documentStore.findPrecedingSiblingChunks(
+      library,
+      version2,
+      id,
+      siblingLimit
+    );
+    for (const sib of precedingSiblings) {
+      relatedIds.add(sib.id);
+    }
+    const childChunks = await this.documentStore.findChildChunks(
+      library,
+      version2,
+      id,
+      childLimit
+    );
+    for (const child of childChunks) {
+      relatedIds.add(child.id);
+    }
+    const subsequentSiblings = await this.documentStore.findSubsequentSiblingChunks(
+      library,
+      version2,
+      id,
+      siblingLimit
+    );
+    for (const sib of subsequentSiblings) {
+      relatedIds.add(sib.id);
+    }
+    return { url, hitId: id, relatedIds, score };
+  }
+  /**
+   * Groups related chunk info by URL, deduplicates IDs, and finds max score per URL.
+   */
+  groupAndPrepareFetch(relatedInfos) {
+    const urlMap = /* @__PURE__ */ new Map();
+    for (const info of relatedInfos) {
+      let entry = urlMap.get(info.url);
+      if (!entry) {
+        entry = { uniqueChunkIds: /* @__PURE__ */ new Set(), maxScore: info.score };
+        urlMap.set(info.url, entry);
+      }
+      for (const id of info.relatedIds) {
+        entry.uniqueChunkIds.add(id);
+      }
+      if (info.score > entry.maxScore) {
+        entry.maxScore = info.score;
+      }
+    }
+    return urlMap;
+  }
+  /**
+   * Finalizes the merged result for a URL group by fetching, sorting, and joining content.
+   */
+  async finalizeResult(library, version2, url, uniqueChunkIds, maxScore) {
+    const ids = Array.from(uniqueChunkIds);
+    const docs = await this.documentStore.findChunksByIds(library, version2, ids);
+    const content = docs.map((d) => d.pageContent).join("\n\n");
+    return {
+      url,
+      content,
+      score: maxScore
+    };
+  }
+  /**
+   * Searches for documents and expands the context around the matches.
+   * @param library The library name.
+   * @param version The library version.
+   * @param query The search query.
+   * @param version The library version (optional, defaults to searching documents without a version).
+   * @param query The search query.
+   * @param limit The optional limit for the initial search results.
+   * @returns An array of strings representing the aggregated content of the retrieved chunks.
+   */
+  async search(library, version2, query, limit) {
+    const normalizedVersion = (version2 ?? "").toLowerCase();
+    const initialResults = await this.documentStore.findByContent(
+      library,
+      normalizedVersion,
+      query,
+      limit ?? 10
+    );
+    const relatedInfos = await Promise.all(
+      initialResults.map(
+        (doc) => this.getRelatedChunkIds(library, normalizedVersion, doc)
+      )
+    );
+    const urlMap = this.groupAndPrepareFetch(relatedInfos);
+    const results = [];
+    for (const [url, { uniqueChunkIds, maxScore }] of urlMap.entries()) {
+      const result = await this.finalizeResult(
+        library,
+        normalizedVersion,
+        url,
+        uniqueChunkIds,
+        maxScore
+      );
+      results.push(result);
+    }
+    return results;
+  }
+}
+const MIGRATIONS_DIR = path.join(getProjectRoot(), "db", "migrations");
+const MIGRATIONS_TABLE = "_schema_migrations";
+function ensureMigrationsTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+      id TEXT PRIMARY KEY,
+      applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+}
+function getAppliedMigrations(db) {
+  const stmt = db.prepare(`SELECT id FROM ${MIGRATIONS_TABLE}`);
+  const rows = stmt.all();
+  return new Set(rows.map((row) => row.id));
+}
+async function applyMigrations(db) {
+  try {
+    db.pragma("journal_mode = OFF");
+    db.pragma("synchronous = OFF");
+    db.pragma("mmap_size = 268435456");
+    db.pragma("cache_size = -64000");
+    db.pragma("temp_store = MEMORY");
+    logger.debug("Applied performance optimizations for migration");
+  } catch (_error) {
+    logger.warn("⚠️ Could not apply all performance optimizations for migration");
+  }
+  const overallTransaction = db.transaction(() => {
+    logger.debug("Checking database migrations...");
+    ensureMigrationsTable(db);
+    const appliedMigrations = getAppliedMigrations(db);
+    if (!fs.existsSync(MIGRATIONS_DIR)) {
+      throw new StoreError("Migrations directory not found");
+    }
+    const migrationFiles = fs.readdirSync(MIGRATIONS_DIR).filter((file) => file.endsWith(".sql")).sort();
+    const pendingMigrations = migrationFiles.filter(
+      (filename) => !appliedMigrations.has(filename)
+    );
+    if (pendingMigrations.length > 0) {
+      logger.info(`🔄 Applying ${pendingMigrations.length} database migration(s)...`);
+    }
+    let appliedCount = 0;
+    for (const filename of pendingMigrations) {
+      logger.debug(`Applying migration: ${filename}`);
+      const filePath = path.join(MIGRATIONS_DIR, filename);
+      const sql = fs.readFileSync(filePath, "utf8");
+      try {
+        db.exec(sql);
+        const insertStmt = db.prepare(`INSERT INTO ${MIGRATIONS_TABLE} (id) VALUES (?)`);
+        insertStmt.run(filename);
+        logger.debug(`Applied migration: ${filename}`);
+        appliedCount++;
+      } catch (error) {
+        logger.error(`❌ Failed to apply migration: ${filename} - ${error}`);
+        throw new StoreError(`Migration failed: ${filename}`, error);
+      }
+    }
+    if (appliedCount > 0) {
+      logger.info(`✅ Successfully applied ${appliedCount} migration(s)`);
+    } else {
+      logger.debug("Database schema is up to date");
+    }
+    return appliedCount;
+  });
+  let retries = 0;
+  let appliedMigrationsCount = 0;
+  while (true) {
+    try {
+      appliedMigrationsCount = overallTransaction.immediate();
+      logger.debug("Database migrations completed successfully");
+      if (appliedMigrationsCount > 0) {
+        try {
+          logger.debug(
+            `Running VACUUM after applying ${appliedMigrationsCount} migration(s)...`
+          );
+          db.exec("VACUUM");
+          logger.debug("Database vacuum completed successfully");
+        } catch (error) {
+          logger.warn(`⚠️ Could not vacuum database after migrations: ${error}`);
+        }
+      } else {
+        logger.debug("Skipping VACUUM - no migrations were applied");
+      }
+      break;
+    } catch (error) {
+      if (error?.code === "SQLITE_BUSY" && retries < MIGRATION_MAX_RETRIES) {
+        retries++;
+        logger.warn(
+          `⚠️  Migrations busy (SQLITE_BUSY), retrying attempt ${retries}/${MIGRATION_MAX_RETRIES} in ${MIGRATION_RETRY_DELAY_MS}ms...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, MIGRATION_RETRY_DELAY_MS));
+      } else {
+        if (error?.code === "SQLITE_BUSY") {
+          logger.error(
+            `❌ Migrations still busy after ${MIGRATION_MAX_RETRIES} retries. Giving up: ${error}`
+          );
+        }
+        if (error instanceof StoreError) {
+          throw error;
+        }
+        throw new StoreError("Failed during migration process", error);
+      }
+    }
+  }
+  try {
+    db.pragma("journal_mode = WAL");
+    db.pragma("wal_autocheckpoint = 1000");
+    db.pragma("busy_timeout = 30000");
+    db.pragma("foreign_keys = ON");
+    db.pragma("synchronous = NORMAL");
+    logger.debug(
+      "Applied production database configuration (WAL mode, autocheckpoint, foreign keys, busy timeout)"
+    );
+  } catch (_error) {
+    logger.warn("⚠️ Could not apply all production database settings");
+  }
+}
+class EmbeddingConfig {
+  static instance = null;
+  /**
+   * Get the singleton instance of EmbeddingConfig.
+   * Creates the instance if it doesn't exist.
+   */
+  static getInstance() {
+    if (EmbeddingConfig.instance === null) {
+      EmbeddingConfig.instance = new EmbeddingConfig();
+    }
+    return EmbeddingConfig.instance;
+  }
+  /**
+   * Reset the singleton instance (useful for testing).
+   */
+  static resetInstance() {
+    EmbeddingConfig.instance = null;
+  }
+  /**
+   * Known dimensions for common embedding models.
+   * This avoids expensive API calls for dimension detection in telemetry.
+   *
+   * Note: The "openai" provider also supports OpenAI-compatible APIs like:
+   * - Ollama (local models)
+   * - LMStudio (local models)
+   * - Any service implementing OpenAI's embedding API
+   */
+  knownModelDimensions = {
+    // OpenAI models (also works with Ollama, LMStudio, and other OpenAI-compatible APIs)
+    "text-embedding-3-small": 1536,
+    "text-embedding-3-large": 3072,
+    "text-embedding-ada-002": 1536,
+    // Google Vertex AI models
+    "text-embedding-004": 768,
+    "textembedding-gecko@003": 768,
+    "textembedding-gecko@002": 768,
+    "textembedding-gecko@001": 768,
+    // Google Gemini models (with MRL support)
+    "text-embedding-preview-0409": 768,
+    "embedding-001": 768,
+    // AWS Bedrock models
+    // Amazon Titan models
+    "amazon.titan-embed-text-v1": 1536,
+    "amazon.titan-embed-text-v2:0": 1024,
+    "amazon.titan-embed-image-v1": 1024,
+    // Image embedding model
+    // Cohere models
+    "cohere.embed-english-v3": 1024,
+    "cohere.embed-multilingual-v3": 1024,
+    // SageMaker models (hosted on AWS SageMaker)
+    "intfloat/multilingual-e5-large": 1024,
+    // Additional AWS models that might be supported
+    // Note: Some of these might be placeholders - verify dimensions before use
+    // "amazon.nova-embed-multilingual-v1:0": 4096, // Commented out as noted in source
+    // MTEB Leaderboard models (source: https://huggingface.co/spaces/mteb/leaderboard)
+    // Top performing models from Massive Text Embedding Benchmark
+    "sentence-transformers/all-MiniLM-L6-v2": 384,
+    "gemini-embedding-001": 3072,
+    "Qwen/Qwen3-Embedding-8B": 4096,
+    "Qwen/Qwen3-Embedding-4B": 2560,
+    "Qwen/Qwen3-Embedding-0.6B": 1024,
+    "Linq-AI-Research/Linq-Embed-Mistral": 4096,
+    "Alibaba-NLP/gte-Qwen2-7B-instruct": 3584,
+    "intfloat/multilingual-e5-large-instruct": 1024,
+    "Salesforce/SFR-Embedding-Mistral": 4096,
+    "text-multilingual-embedding-002": 768,
+    "GritLM/GritLM-7B": 4096,
+    "GritLM/GritLM-8x7B": 4096,
+    "intfloat/e5-mistral-7b-instruct": 4096,
+    "Cohere/Cohere-embed-multilingual-v3.0": 1024,
+    "Alibaba-NLP/gte-Qwen2-1.5B-instruct": 8960,
+    "Lajavaness/bilingual-embedding-large": 1024,
+    "Salesforce/SFR-Embedding-2_R": 4096,
+    "NovaSearch/stella_en_1.5B_v5": 8960,
+    "NovaSearch/jasper_en_vision_language_v1": 8960,
+    "nvidia/NV-Embed-v2": 4096,
+    "OrdalieTech/Solon-embeddings-large-0.1": 1024,
+    "BAAI/bge-m3": 1024,
+    "HIT-TMG/KaLM-embedding-multilingual-mini-v1": 896,
+    "jinaai/jina-embeddings-v3": 1024,
+    "Alibaba-NLP/gte-multilingual-base": 768,
+    "Lajavaness/bilingual-embedding-base": 768,
+    "HIT-TMG/KaLM-embedding-multilingual-mini-instruct-v1": 896,
+    "nvidia/NV-Embed-v1": 4096,
+    "Cohere/Cohere-embed-multilingual-light-v3.0": 384,
+    "manu/bge-m3-custom-fr": 1024,
+    "Lajavaness/bilingual-embedding-small": 384,
+    "Snowflake/snowflake-arctic-embed-l-v2.0": 1024,
+    "intfloat/multilingual-e5-base": 768,
+    "voyage-3-lite": 512,
+    "voyage-3": 1024,
+    "intfloat/multilingual-e5-small": 384,
+    "Alibaba-NLP/gte-Qwen1.5-7B-instruct": 4096,
+    "Snowflake/snowflake-arctic-embed-m-v2.0": 768,
+    "deepvk/USER-bge-m3": 1024,
+    "Cohere/Cohere-embed-english-v3.0": 1024,
+    "Omartificial-Intelligence-Space/Arabic-labse-Matryoshka": 768,
+    "ibm-granite/granite-embedding-278m-multilingual": 768,
+    "NovaSearch/stella_en_400M_v5": 4096,
+    "omarelshehy/arabic-english-sts-matryoshka": 1024,
+    "sentence-transformers/paraphrase-multilingual-mpnet-base-v2": 768,
+    "Omartificial-Intelligence-Space/Arabic-all-nli-triplet-Matryoshka": 768,
+    "Haon-Chen/speed-embedding-7b-instruct": 4096,
+    "sentence-transformers/LaBSE": 768,
+    "WhereIsAI/UAE-Large-V1": 1024,
+    "ibm-granite/granite-embedding-107m-multilingual": 384,
+    "mixedbread-ai/mxbai-embed-large-v1": 1024,
+    "intfloat/e5-large-v2": 1024,
+    "avsolatorio/GIST-large-Embedding-v0": 1024,
+    "sdadas/mmlw-e5-large": 1024,
+    "nomic-ai/nomic-embed-text-v1": 768,
+    "nomic-ai/nomic-embed-text-v1-ablated": 768,
+    "intfloat/e5-base-v2": 768,
+    "BAAI/bge-large-en-v1.5": 1024,
+    "intfloat/e5-large": 1024,
+    "Omartificial-Intelligence-Space/Arabic-MiniLM-L12-v2-all-nli-triplet": 384,
+    "Cohere/Cohere-embed-english-light-v3.0": 384,
+    "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2": 768,
+    "Gameselo/STS-multilingual-mpnet-base-v2": 768,
+    "thenlper/gte-large": 1024,
+    "avsolatorio/GIST-Embedding-v0": 768,
+    "nomic-ai/nomic-embed-text-v1-unsupervised": 768,
+    "infgrad/stella-base-en-v2": 768,
+    "avsolatorio/NoInstruct-small-Embedding-v0": 384,
+    "dwzhu/e5-base-4k": 768,
+    "sdadas/mmlw-e5-base": 768,
+    "voyage-multilingual-2": 1024,
+    "McGill-NLP/LLM2Vec-Mistral-7B-Instruct-v2-mntp-supervised": 4096,
+    "BAAI/bge-base-en-v1.5": 768,
+    "avsolatorio/GIST-small-Embedding-v0": 384,
+    "sdadas/mmlw-roberta-large": 1024,
+    "nomic-ai/nomic-embed-text-v1.5": 768,
+    "minishlab/potion-multilingual-128M": 256,
+    "shibing624/text2vec-base-multilingual": 384,
+    "thenlper/gte-base": 768,
+    "intfloat/e5-small-v2": 384,
+    "intfloat/e5-base": 768,
+    "sentence-transformers/static-similarity-mrl-multilingual-v1": 1024,
+    "manu/sentence_croissant_alpha_v0.3": 2048,
+    "BAAI/bge-small-en-v1.5": 512,
+    "thenlper/gte-small": 384,
+    "sdadas/mmlw-e5-small": 384,
+    "manu/sentence_croissant_alpha_v0.4": 2048,
+    "manu/sentence_croissant_alpha_v0.2": 2048,
+    "abhinand/MedEmbed-small-v0.1": 384,
+    "ibm-granite/granite-embedding-125m-english": 768,
+    "intfloat/e5-small": 384,
+    "voyage-large-2-instruct": 1024,
+    "sdadas/mmlw-roberta-base": 768,
+    "Snowflake/snowflake-arctic-embed-l": 1024,
+    "Mihaiii/Ivysaur": 384,
+    "Snowflake/snowflake-arctic-embed-m-long": 768,
+    "bigscience/sgpt-bloom-7b1-msmarco": 4096,
+    "avsolatorio/GIST-all-MiniLM-L6-v2": 384,
+    "sergeyzh/LaBSE-ru-turbo": 768,
+    "sentence-transformers/all-mpnet-base-v2": 768,
+    "Snowflake/snowflake-arctic-embed-m": 768,
+    "Snowflake/snowflake-arctic-embed-s": 384,
+    "sentence-transformers/all-MiniLM-L12-v2": 384,
+    "Mihaiii/gte-micro-v4": 384,
+    "Snowflake/snowflake-arctic-embed-m-v1.5": 768,
+    "cointegrated/LaBSE-en-ru": 768,
+    "Mihaiii/Bulbasaur": 384,
+    "ibm-granite/granite-embedding-30m-english": 384,
+    "deepfile/embedder-100p": 768,
+    "Jaume/gemma-2b-embeddings": 2048,
+    "OrlikB/KartonBERT-USE-base-v1": 768,
+    "izhx/udever-bloom-7b1": 4096,
+    "izhx/udever-bloom-1b1": 1024,
+    "brahmairesearch/slx-v0.1": 384,
+    "Mihaiii/Wartortle": 384,
+    "izhx/udever-bloom-3b": 2048,
+    "deepvk/USER-base": 768,
+    "ai-forever/ru-en-RoSBERTa": 1024,
+    "McGill-NLP/LLM2Vec-Mistral-7B-Instruct-v2-mntp-unsup-simcse": 4096,
+    "Mihaiii/Venusaur": 384,
+    "Snowflake/snowflake-arctic-embed-xs": 384,
+    "jinaai/jina-embedding-b-en-v1": 768,
+    "Mihaiii/gte-micro": 384,
+    "aari1995/German_Semantic_STS_V2": 1024,
+    "Mihaiii/Squirtle": 384,
+    "OrlikB/st-polish-kartonberta-base-alpha-v1": 768,
+    "sergeyzh/rubert-tiny-turbo": 312,
+    "minishlab/potion-base-8M": 256,
+    "minishlab/M2V_base_glove_subword": 256,
+    "jinaai/jina-embedding-s-en-v1": 512,
+    "minishlab/potion-base-4M": 128,
+    "minishlab/M2V_base_output": 256,
+    "DeepPavlov/rubert-base-cased-sentence": 768,
+    "jinaai/jina-embeddings-v2-small-en": 512,
+    "cointegrated/rubert-tiny2": 312,
+    "minishlab/M2V_base_glove": 256,
+    "cointegrated/rubert-tiny": 312,
+    "silma-ai/silma-embeddding-matryoshka-v0.1": 768,
+    "DeepPavlov/rubert-base-cased": 768,
+    "Omartificial-Intelligence-Space/Arabic-mpnet-base-all-nli-triplet": 768,
+    "izhx/udever-bloom-560m": 1024,
+    "minishlab/potion-base-2M": 64,
+    "DeepPavlov/distilrubert-small-cased-conversational": 768,
+    "consciousAI/cai-lunaris-text-embeddings": 1024,
+    "deepvk/deberta-v1-base": 768,
+    "Omartificial-Intelligence-Space/Arabert-all-nli-triplet-Matryoshka": 768,
+    "Omartificial-Intelligence-Space/Marbert-all-nli-triplet-Matryoshka": 768,
+    "ai-forever/sbert_large_mt_nlu_ru": 1024,
+    "ai-forever/sbert_large_nlu_ru": 1024,
+    "malenia1/ternary-weight-embedding": 1024,
+    "jinaai/jina-embeddings-v2-base-en": 768,
+    "VPLabs/SearchMap_Preview": 4096,
+    "Hum-Works/lodestone-base-4096-v1": 768,
+    "jinaai/jina-embeddings-v4": 2048
+  };
+  /**
+   * Lowercase lookup map for case-insensitive model dimension queries.
+   * Built lazily from knownModelDimensions to ensure consistency.
+   */
+  modelLookup;
+  constructor() {
+    this.modelLookup = /* @__PURE__ */ new Map();
+    for (const [model, dimensions] of Object.entries(this.knownModelDimensions)) {
+      this.modelLookup.set(model.toLowerCase(), dimensions);
+    }
+  }
+  /**
+   * Parse embedding model configuration from environment variables.
+   * This is a synchronous operation that extracts provider, model, and known dimensions.
+   *
+   * Supports various providers:
+   * - openai: OpenAI models and OpenAI-compatible APIs (Ollama, LMStudio, etc.)
+   * - vertex: Google Cloud Vertex AI
+   * - gemini: Google Generative AI
+   * - aws: AWS Bedrock models
+   * - microsoft: Azure OpenAI
+   * - sagemaker: AWS SageMaker hosted models
+   *
+   * @param modelSpec Optional model specification, defaults to DOCS_MCP_EMBEDDING_MODEL env var
+   * @returns Parsed embedding model configuration
+   */
+  parse(modelSpec) {
+    const spec = modelSpec || process.env.DOCS_MCP_EMBEDDING_MODEL || "text-embedding-3-small";
+    const colonIndex = spec.indexOf(":");
+    let provider;
+    let model;
+    if (colonIndex === -1) {
+      provider = "openai";
+      model = spec;
+    } else {
+      provider = spec.substring(0, colonIndex);
+      model = spec.substring(colonIndex + 1);
+    }
+    const dimensions = this.modelLookup?.get(model.toLowerCase()) || null;
+    return {
+      provider,
+      model,
+      dimensions,
+      modelSpec: spec
+    };
+  }
+  /**
+   * Get the known dimensions for a specific model.
+   * Returns null if the model dimensions are not known.
+   * Uses case-insensitive lookup.
+   *
+   * @param model The model name (e.g., "text-embedding-3-small")
+   * @returns Known dimensions or null
+   */
+  getKnownDimensions(model) {
+    return this.modelLookup?.get(model.toLowerCase()) || null;
+  }
+  /**
+   * Add or update known dimensions for a model.
+   * This can be used to cache discovered dimensions.
+   * Stores both original case and lowercase for consistent lookup.
+   *
+   * @param model The model name
+   * @param dimensions The dimensions to cache
+   */
+  setKnownDimensions(model, dimensions) {
+    this.knownModelDimensions[model] = dimensions;
+    if (this.modelLookup) {
+      this.modelLookup.set(model.toLowerCase(), dimensions);
+    }
+  }
+  /**
+   * Static method to parse embedding model configuration using the singleton instance.
+   * This maintains backward compatibility while using the class-based approach.
+   */
+  static parseEmbeddingConfig(modelSpec) {
+    return EmbeddingConfig.getInstance().parse(modelSpec);
+  }
+  /**
+   * Static method to get known model dimensions using the singleton instance.
+   * This maintains backward compatibility while using the class-based approach.
+   */
+  static getKnownModelDimensions(model) {
+    return EmbeddingConfig.getInstance().getKnownDimensions(model);
+  }
+  /**
+   * Static method to set known model dimensions using the singleton instance.
+   * This maintains backward compatibility while using the class-based approach.
+   */
+  static setKnownModelDimensions(model, dimensions) {
+    EmbeddingConfig.getInstance().setKnownDimensions(model, dimensions);
+  }
+}
+class DocumentStore {
+  db;
+  embeddings;
+  dbDimension = VECTOR_DIMENSION;
+  modelDimension;
+  embeddingConfig;
+  statements;
+  /**
+   * Calculates Reciprocal Rank Fusion score for a result
+   */
+  calculateRRF(vecRank, ftsRank, k = 60) {
+    let rrf = 0;
+    if (vecRank !== void 0) {
+      rrf += 1 / (k + vecRank);
+    }
+    if (ftsRank !== void 0) {
+      rrf += 1 / (k + ftsRank);
+    }
+    return rrf;
+  }
+  /**
+   * Assigns ranks to search results based on their scores
+   */
+  assignRanks(results) {
+    const vecRanks = /* @__PURE__ */ new Map();
+    const ftsRanks = /* @__PURE__ */ new Map();
+    results.filter((r) => r.vec_score !== void 0).sort((a, b) => (b.vec_score ?? 0) - (a.vec_score ?? 0)).forEach((result, index) => {
+      vecRanks.set(Number(result.id), index + 1);
+    });
+    results.filter((r) => r.fts_score !== void 0).sort((a, b) => (b.fts_score ?? 0) - (a.fts_score ?? 0)).forEach((result, index) => {
+      ftsRanks.set(Number(result.id), index + 1);
+    });
+    return results.map((result) => ({
+      ...result,
+      vec_rank: vecRanks.get(Number(result.id)),
+      fts_rank: ftsRanks.get(Number(result.id)),
+      rrf_score: this.calculateRRF(
+        vecRanks.get(Number(result.id)),
+        ftsRanks.get(Number(result.id))
+      )
+    }));
+  }
+  constructor(dbPath, embeddingConfig) {
+    if (!dbPath) {
+      throw new StoreError("Missing required database path");
+    }
+    this.db = new Database(dbPath);
+    this.embeddingConfig = embeddingConfig;
+  }
+  /**
+   * Sets up prepared statements for database queries
+   */
+  prepareStatements() {
+    const statements = {
+      getById: this.db.prepare("SELECT * FROM documents WHERE id = ?"),
+      insertDocument: this.db.prepare(
+        "INSERT INTO documents (library_id, version_id, url, content, metadata, sort_order, indexed_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
+      ),
+      insertEmbedding: this.db.prepare(
+        "INSERT INTO documents_vec (rowid, library_id, version_id, embedding) VALUES (?, ?, ?, ?)"
+      ),
+      insertLibrary: this.db.prepare(
+        "INSERT INTO libraries (name) VALUES (?) ON CONFLICT(name) DO NOTHING"
+      ),
+      getLibraryIdByName: this.db.prepare(
+        "SELECT id FROM libraries WHERE name = ?"
+      ),
+      // New version-related statements
+      insertVersion: this.db.prepare(
+        "INSERT INTO versions (library_id, name, status) VALUES (?, ?, 'not_indexed') ON CONFLICT(library_id, name) DO NOTHING"
+      ),
+      resolveVersionId: this.db.prepare(
+        "SELECT id FROM versions WHERE library_id = ? AND name IS ?"
+      ),
+      getVersionById: this.db.prepare("SELECT * FROM versions WHERE id = ?"),
+      queryVersionsByLibraryId: this.db.prepare(
+        "SELECT * FROM versions WHERE library_id = ? ORDER BY name"
+      ),
+      deleteLibraryDocuments: this.db.prepare(
+        `DELETE FROM documents
+         WHERE library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      deleteDocuments: this.db.prepare(
+        `DELETE FROM documents
+         WHERE library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      deleteDocumentsByUrl: this.db.prepare(
+        `DELETE FROM documents
+         WHERE url = ?
+         AND library_id = (SELECT id FROM libraries WHERE name = ?)
+         AND version_id = (
+           SELECT v.id FROM versions v 
+           WHERE v.library_id = (SELECT id FROM libraries WHERE name = ?)
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+         )`
+      ),
+      getDocumentBySort: this.db.prepare(
+        `SELECT d.id
+         FROM documents d
+         JOIN versions v ON d.version_id = v.id
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         AND COALESCE(v.name, '') = COALESCE(?, '')
+         LIMIT 1`
+      ),
+      queryVersions: this.db.prepare(
+        `SELECT DISTINCT v.name
+         FROM versions v
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         ORDER BY v.name`
+      ),
+      checkExists: this.db.prepare(
+        `SELECT d.id FROM documents d
+         JOIN versions v ON d.version_id = v.id
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ?
+         AND COALESCE(v.name, '') = COALESCE(?, '')
+         LIMIT 1`
+      ),
+      // Library/version aggregation including versions without documents and status/progress fields
+      queryLibraryVersions: this.db.prepare(
+        `SELECT
+          l.name as library,
+          COALESCE(v.name, '') as version,
+          v.id as versionId,
+          v.status as status,
+          v.progress_pages as progressPages,
+          v.progress_max_pages as progressMaxPages,
+          v.source_url as sourceUrl,
+          MIN(d.indexed_at) as indexedAt,
+          COUNT(d.id) as documentCount,
+          COUNT(DISTINCT d.url) as uniqueUrlCount
+        FROM versions v
+        JOIN libraries l ON v.library_id = l.id
+        LEFT JOIN documents d ON d.version_id = v.id
+        GROUP BY v.id
+        ORDER BY l.name, version`
+      ),
+      getChildChunks: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND json_array_length(json_extract(d.metadata, '$.path')) = ?
+        AND json_extract(d.metadata, '$.path') LIKE ? || '%'
+        AND d.sort_order > (SELECT sort_order FROM documents WHERE id = ?)
+        ORDER BY d.sort_order
+        LIMIT ?
+      `),
+      getPrecedingSiblings: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND d.sort_order < (SELECT sort_order FROM documents WHERE id = ?)
+        AND json_extract(d.metadata, '$.path') = ?
+        ORDER BY d.sort_order DESC
+        LIMIT ?
+      `),
+      getSubsequentSiblings: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND d.sort_order > (SELECT sort_order FROM documents WHERE id = ?)
+        AND json_extract(d.metadata, '$.path') = ?
+        ORDER BY d.sort_order
+        LIMIT ?
+      `),
+      getParentChunk: this.db.prepare(`
+        SELECT d.* FROM documents d
+        JOIN versions v ON d.version_id = v.id
+        JOIN libraries l ON v.library_id = l.id
+        WHERE l.name = ?
+        AND COALESCE(v.name, '') = COALESCE(?, '')
+        AND d.url = ?
+        AND json_extract(d.metadata, '$.path') = ?
+        AND d.sort_order < (SELECT sort_order FROM documents WHERE id = ?)
+        ORDER BY d.sort_order DESC
+        LIMIT 1
+      `),
+      // Status tracking statements
+      updateVersionStatus: this.db.prepare(
+        "UPDATE versions SET status = ?, error_message = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      updateVersionProgress: this.db.prepare(
+        "UPDATE versions SET progress_pages = ?, progress_max_pages = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      getVersionsByStatus: this.db.prepare(
+        "SELECT v.*, l.name as library_name FROM versions v JOIN libraries l ON v.library_id = l.id WHERE v.status IN (SELECT value FROM json_each(?))"
+      ),
+      // Scraper options statements
+      updateVersionScraperOptions: this.db.prepare(
+        "UPDATE versions SET source_url = ?, scraper_options = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+      ),
+      getVersionWithOptions: this.db.prepare(
+        "SELECT * FROM versions WHERE id = ?"
+      ),
+      getVersionsBySourceUrl: this.db.prepare(
+        "SELECT v.*, l.name as library_name FROM versions v JOIN libraries l ON v.library_id = l.id WHERE v.source_url = ? ORDER BY v.created_at DESC"
+      ),
+      // Version and library deletion statements
+      deleteVersionById: this.db.prepare("DELETE FROM versions WHERE id = ?"),
+      deleteLibraryById: this.db.prepare("DELETE FROM libraries WHERE id = ?"),
+      countVersionsByLibraryId: this.db.prepare(
+        "SELECT COUNT(*) as count FROM versions WHERE library_id = ?"
+      ),
+      getVersionId: this.db.prepare(
+        `SELECT v.id, v.library_id FROM versions v
+         JOIN libraries l ON v.library_id = l.id
+         WHERE l.name = ? AND COALESCE(v.name, '') = COALESCE(?, '')`
+      )
+    };
+    this.statements = statements;
+  }
+  /**
+   * Pads a vector to the fixed database dimension by appending zeros.
+   * Throws an error if the input vector is longer than the database dimension.
+   */
+  padVector(vector) {
+    if (vector.length > this.dbDimension) {
+      throw new Error(
+        `Vector dimension ${vector.length} exceeds database dimension ${this.dbDimension}`
+      );
+    }
+    if (vector.length === this.dbDimension) {
+      return vector;
+    }
+    return [...vector, ...new Array(this.dbDimension - vector.length).fill(0)];
+  }
+  /**
+   * Initialize the embeddings client using either provided config or environment variables.
+   * If no embedding config is provided (null), embeddings will not be initialized.
+   * This allows DocumentStore to be used without embeddings for operations that don't need them.
+   *
+   * Environment variables per provider:
+   * - openai: OPENAI_API_KEY (and optionally OPENAI_API_BASE, OPENAI_ORG_ID)
+   * - vertex: GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)
+   * - gemini: GOOGLE_API_KEY
+   * - aws: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
+   * - microsoft: Azure OpenAI credentials (AZURE_OPENAI_API_*)
+   */
+  async initializeEmbeddings() {
+    if (this.embeddingConfig === null) {
+      logger.debug("Embedding initialization skipped (explicitly disabled)");
+      return;
+    }
+    const config = this.embeddingConfig || EmbeddingConfig.parseEmbeddingConfig();
+    try {
+      this.embeddings = createEmbeddingModel(config.modelSpec);
+      if (config.dimensions !== null) {
+        this.modelDimension = config.dimensions;
+      } else {
+        const testVector = await this.embeddings.embedQuery("test");
+        this.modelDimension = testVector.length;
+        EmbeddingConfig.setKnownModelDimensions(config.model, this.modelDimension);
+      }
+      if (this.modelDimension > this.dbDimension) {
+        throw new DimensionError(config.modelSpec, this.modelDimension, this.dbDimension);
+      }
+      logger.debug(
+        `Embeddings initialized: ${config.provider}:${config.model} (${this.modelDimension}d)`
+      );
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes("does not exist") || error.message.includes("MODEL_NOT_FOUND")) {
+          throw new ModelConfigurationError(
+            `❌ Invalid embedding model: ${config.model}
+   The model "${config.model}" is not available or you don't have access to it.
+   See README.md for supported models or run with --help for more details.`
+          );
+        }
+        if (error.message.includes("API key") || error.message.includes("401") || error.message.includes("authentication")) {
+          throw new ModelConfigurationError(
+            `❌ Authentication failed for ${config.provider} embedding provider
+   Please check your API key configuration.
+   See README.md for configuration options or run with --help for more details.`
+          );
+        }
+      }
+      throw error;
+    }
+  }
+  /**
+   * Escapes a query string for use with SQLite FTS5 MATCH operator.
+   * Wraps the query in double quotes and escapes internal double quotes.
+   */
+  escapeFtsQuery(query) {
+    const escapedQuotes = query.replace(/"/g, '""');
+    return `"${escapedQuotes}"`;
+  }
+  /**
+   * Initializes database connection and ensures readiness
+   */
+  async initialize() {
+    try {
+      sqliteVec.load(this.db);
+      applyMigrations(this.db);
+      this.prepareStatements();
+      await this.initializeEmbeddings();
+    } catch (error) {
+      if (error instanceof StoreError || error instanceof ModelConfigurationError || error instanceof UnsupportedProviderError) {
+        throw error;
+      }
+      throw new ConnectionError("Failed to initialize database connection", error);
+    }
+  }
+  /**
+   * Gracefully closes database connections
+   */
+  async shutdown() {
+    this.db.close();
+  }
+  /**
+   * Resolves a library name and version string to library_id and version_id.
+   * Creates library and version records if they don't exist.
+   */
+  async resolveLibraryAndVersionIds(library, version2) {
+    const normalizedLibrary = library.toLowerCase();
+    const normalizedVersion = denormalizeVersionName(version2.toLowerCase());
+    this.statements.insertLibrary.run(normalizedLibrary);
+    const libraryIdRow = this.statements.getLibraryIdByName.get(normalizedLibrary);
+    if (!libraryIdRow || typeof libraryIdRow.id !== "number") {
+      throw new StoreError(`Failed to resolve library_id for library: ${library}`);
+    }
+    const libraryId = libraryIdRow.id;
+    this.statements.insertVersion.run(libraryId, normalizedVersion);
+    const versionIdRow = this.statements.resolveVersionId.get(
+      libraryId,
+      normalizedVersion === null ? "" : normalizedVersion
+    );
+    if (!versionIdRow || typeof versionIdRow.id !== "number") {
+      throw new StoreError(
+        `Failed to resolve version_id for library: ${library}, version: ${version2}`
+      );
+    }
+    return { libraryId, versionId: versionIdRow.id };
+  }
+  /**
+   * Retrieves all unique versions for a specific library
+   */
+  async queryUniqueVersions(library) {
+    try {
+      const rows = this.statements.queryVersions.all(library.toLowerCase());
+      return rows.map((row) => normalizeVersionName(row.name));
+    } catch (error) {
+      throw new ConnectionError("Failed to query versions", error);
+    }
+  }
+  /**
+   * Updates the status of a version record in the database.
+   * @param versionId The version ID to update
+   * @param status The new status to set
+   * @param errorMessage Optional error message for failed statuses
+   */
+  async updateVersionStatus(versionId, status, errorMessage) {
+    try {
+      this.statements.updateVersionStatus.run(status, errorMessage ?? null, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to update version status: ${error}`);
+    }
+  }
+  /**
+   * Updates the progress counters for a version being indexed.
+   * @param versionId The version ID to update
+   * @param pages Current number of pages processed
+   * @param maxPages Total number of pages to process
+   */
+  async updateVersionProgress(versionId, pages, maxPages) {
+    try {
+      this.statements.updateVersionProgress.run(pages, maxPages, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to update version progress: ${error}`);
+    }
+  }
+  /**
+   * Retrieves versions by their status.
+   * @param statuses Array of statuses to filter by
+   * @returns Array of version records matching the statuses
+   */
+  async getVersionsByStatus(statuses) {
+    try {
+      const statusJson = JSON.stringify(statuses);
+      const rows = this.statements.getVersionsByStatus.all(
+        statusJson
+      );
+      return rows;
+    } catch (error) {
+      throw new StoreError(`Failed to get versions by status: ${error}`);
+    }
+  }
+  /**
+   * Stores scraper options for a version to enable reproducible indexing.
+   * @param versionId The version ID to update
+   * @param options Complete scraper options used for indexing
+   */
+  async storeScraperOptions(versionId, options) {
+    try {
+      const { url: source_url, library, version: version2, signal, ...scraper_options } = options;
+      const optionsJson = JSON.stringify(scraper_options);
+      this.statements.updateVersionScraperOptions.run(source_url, optionsJson, versionId);
+    } catch (error) {
+      throw new StoreError(`Failed to store scraper options: ${error}`);
+    }
+  }
+  /**
+   * Retrieves stored scraping configuration (source URL and options) for a version.
+   * Returns null when no source URL is recorded (not re-indexable).
+   */
+  async getScraperOptions(versionId) {
+    try {
+      const row = this.statements.getVersionWithOptions.get(versionId);
+      if (!row?.source_url) {
+        return null;
+      }
+      let parsed = {};
+      if (row.scraper_options) {
+        try {
+          parsed = JSON.parse(row.scraper_options);
+        } catch (e) {
+          logger.warn(`⚠️ Invalid scraper_options JSON for version ${versionId}: ${e}`);
+          parsed = {};
+        }
+      }
+      return { sourceUrl: row.source_url, options: parsed };
+    } catch (error) {
+      throw new StoreError(`Failed to get scraper options: ${error}`);
+    }
+  }
+  /**
+   * Finds versions that were indexed from the same source URL.
+   * Useful for finding similar configurations or detecting duplicates.
+   * @param url Source URL to search for
+   * @returns Array of versions with the same source URL
+   */
+  async findVersionsBySourceUrl(url) {
+    try {
+      const rows = this.statements.getVersionsBySourceUrl.all(
+        url
+      );
+      return rows;
+    } catch (error) {
+      throw new StoreError(`Failed to find versions by source URL: ${error}`);
+    }
+  }
+  /**
+   * Verifies existence of documents for a specific library version
+   */
+  async checkDocumentExists(library, version2) {
+    try {
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.checkExists.get(
+        library.toLowerCase(),
+        normalizedVersion
+      );
+      return result !== void 0;
+    } catch (error) {
+      throw new ConnectionError("Failed to check document existence", error);
+    }
+  }
+  /**
+   * Retrieves a mapping of all libraries to their available versions with details.
+   */
+  async queryLibraryVersions() {
+    try {
+      const rows = this.statements.queryLibraryVersions.all();
+      const libraryMap = /* @__PURE__ */ new Map();
+      for (const row of rows) {
+        const library = row.library;
+        if (!libraryMap.has(library)) {
+          libraryMap.set(library, []);
+        }
+        const indexedAtISO = row.indexedAt ? new Date(row.indexedAt).toISOString() : null;
+        libraryMap.get(library)?.push({
+          version: row.version,
+          versionId: row.versionId,
+          // Preserve raw string status here; DocumentManagementService will cast to VersionStatus
+          status: row.status,
+          progressPages: row.progressPages,
+          progressMaxPages: row.progressMaxPages,
+          sourceUrl: row.sourceUrl,
+          documentCount: row.documentCount,
+          uniqueUrlCount: row.uniqueUrlCount,
+          indexedAt: indexedAtISO
+        });
+      }
+      for (const versions of libraryMap.values()) {
+        versions.sort((a, b) => {
+          if (a.version === "" && b.version !== "") {
+            return -1;
+          }
+          if (a.version !== "" && b.version === "") {
+            return 1;
+          }
+          if (a.version === "" && b.version === "") {
+            return 0;
+          }
+          try {
+            return semver__default.compare(a.version, b.version);
+          } catch (_error) {
+            return a.version.localeCompare(b.version);
+          }
+        });
+      }
+      return libraryMap;
+    } catch (error) {
+      throw new ConnectionError("Failed to query library versions", error);
+    }
+  }
+  /**
+   * Stores documents with library and version metadata, generating embeddings
+   * for vector similarity search. Automatically removes any existing documents
+   * for the same URLs before adding new ones to prevent UNIQUE constraint violations.
+   */
+  async addDocuments(library, version2, documents) {
+    try {
+      if (documents.length === 0) {
+        return;
+      }
+      const urls = /* @__PURE__ */ new Set();
+      for (const doc of documents) {
+        const url = doc.metadata.url;
+        if (!url || typeof url !== "string" || !url.trim()) {
+          throw new StoreError("Document metadata must include a valid URL");
+        }
+        urls.add(url);
+      }
+      const texts = documents.map((doc) => {
+        const header = `<title>${doc.metadata.title}</title>
+<url>${doc.metadata.url}</url>
+<path>${doc.metadata.path.join(" / ")}</path>
+`;
+        return `${header}${doc.pageContent}`;
+      });
+      const maxBatchChars = Number(process.env.DOCS_MCP_EMBEDDING_BATCH_CHARS) || EMBEDDING_BATCH_CHARS;
+      const rawEmbeddings = [];
+      let currentBatch = [];
+      let currentBatchSize = 0;
+      let batchCount = 0;
+      for (const text of texts) {
+        const textSize = text.length;
+        if (currentBatchSize + textSize > maxBatchChars && currentBatch.length > 0) {
+          batchCount++;
+          logger.debug(
+            `🔄 Processing embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+          );
+          const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+          rawEmbeddings.push(...batchEmbeddings);
+          currentBatch = [];
+          currentBatchSize = 0;
+        }
+        currentBatch.push(text);
+        currentBatchSize += textSize;
+        if (currentBatch.length >= EMBEDDING_BATCH_SIZE) {
+          batchCount++;
+          logger.debug(
+            `🔄 Processing embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+          );
+          const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+          rawEmbeddings.push(...batchEmbeddings);
+          currentBatch = [];
+          currentBatchSize = 0;
+        }
+      }
+      if (currentBatch.length > 0) {
+        batchCount++;
+        logger.debug(
+          `🔄 Processing final embedding batch ${batchCount}: ${currentBatch.length} texts, ${currentBatchSize} chars`
+        );
+        const batchEmbeddings = await this.embeddings.embedDocuments(currentBatch);
+        rawEmbeddings.push(...batchEmbeddings);
+      }
+      const paddedEmbeddings = rawEmbeddings.map((vector) => this.padVector(vector));
+      const { libraryId, versionId } = await this.resolveLibraryAndVersionIds(
+        library,
+        version2
+      );
+      for (const url of urls) {
+        const deletedCount = await this.deleteDocumentsByUrl(library, version2, url);
+        if (deletedCount > 0) {
+          logger.debug(`Deleted ${deletedCount} existing documents for URL: ${url}`);
+        }
+      }
+      const transaction = this.db.transaction((docs) => {
+        for (let i = 0; i < docs.length; i++) {
+          const doc = docs[i];
+          const url = doc.metadata.url;
+          const result = this.statements.insertDocument.run(
+            BigInt(libraryId),
+            BigInt(versionId),
+            url,
+            doc.pageContent,
+            JSON.stringify(doc.metadata),
+            i,
+            (/* @__PURE__ */ new Date()).toISOString()
+            // Pass current timestamp for indexed_at
+          );
+          const rowId = result.lastInsertRowid;
+          this.statements.insertEmbedding.run(
+            BigInt(rowId),
+            BigInt(libraryId),
+            BigInt(versionId),
+            JSON.stringify(paddedEmbeddings[i])
+          );
+        }
+      });
+      transaction(documents);
+    } catch (error) {
+      throw new ConnectionError("Failed to add documents to store", error);
+    }
+  }
+  /**
+   * Removes documents matching specified library and version
+   * @returns Number of documents deleted
+   */
+  async deleteDocuments(library, version2) {
+    try {
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.deleteDocuments.run(
+        library.toLowerCase(),
+        library.toLowerCase(),
+        // library name appears twice in the query
+        normalizedVersion
+      );
+      return result.changes;
+    } catch (error) {
+      throw new ConnectionError("Failed to delete documents", error);
+    }
+  }
+  /**
+   * Removes documents for a specific URL within a library and version
+   * @returns Number of documents deleted
+   */
+  async deleteDocumentsByUrl(library, version2, url) {
+    try {
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.deleteDocumentsByUrl.run(
+        url,
+        library.toLowerCase(),
+        library.toLowerCase(),
+        // library name appears twice in the query
+        normalizedVersion
+      );
+      return result.changes;
+    } catch (error) {
+      throw new ConnectionError("Failed to delete documents by URL", error);
+    }
+  }
+  /**
+   * Completely removes a library version and all associated documents.
+   * Optionally removes the library if no other versions remain.
+   * @param library Library name
+   * @param version Version string (empty string for unversioned)
+   * @param removeLibraryIfEmpty Whether to remove the library if no versions remain
+   * @returns Object with counts of deleted documents, version deletion status, and library deletion status
+   */
+  async removeVersion(library, version2, removeLibraryIfEmpty = true) {
+    try {
+      const normalizedLibrary = library.toLowerCase();
+      const normalizedVersion = version2.toLowerCase();
+      const versionResult = this.statements.getVersionId.get(
+        normalizedLibrary,
+        normalizedVersion
+      );
+      if (!versionResult) {
+        return { documentsDeleted: 0, versionDeleted: false, libraryDeleted: false };
+      }
+      const { id: versionId, library_id: libraryId } = versionResult;
+      const documentsDeleted = await this.deleteDocuments(library, version2);
+      const versionDeleteResult = this.statements.deleteVersionById.run(versionId);
+      const versionDeleted = versionDeleteResult.changes > 0;
+      let libraryDeleted = false;
+      if (removeLibraryIfEmpty && versionDeleted) {
+        const countResult = this.statements.countVersionsByLibraryId.get(libraryId);
+        const remainingVersions = countResult?.count ?? 0;
+        if (remainingVersions === 0) {
+          const libraryDeleteResult = this.statements.deleteLibraryById.run(libraryId);
+          libraryDeleted = libraryDeleteResult.changes > 0;
+        }
+      }
+      return { documentsDeleted, versionDeleted, libraryDeleted };
+    } catch (error) {
+      throw new ConnectionError("Failed to remove version", error);
+    }
+  }
+  /**
+   * Retrieves a document by its ID.
+   * @param id The ID of the document.
+   * @returns The document, or null if not found.
+   */
+  async getById(id) {
+    try {
+      const row = this.statements.getById.get(BigInt(id));
+      if (!row) {
+        return null;
+      }
+      return mapDbDocumentToDocument(row);
+    } catch (error) {
+      throw new ConnectionError(`Failed to get document by ID ${id}`, error);
+    }
+  }
+  /**
+   * Finds documents matching a text query using hybrid search.
+   * Combines vector similarity search with full-text search using Reciprocal Rank Fusion.
+   */
+  async findByContent(library, version2, query, limit) {
+    try {
+      const rawEmbedding = await this.embeddings.embedQuery(query);
+      const embedding = this.padVector(rawEmbedding);
+      const ftsQuery = this.escapeFtsQuery(query);
+      const normalizedVersion = version2.toLowerCase();
+      const stmt = this.db.prepare(`
+        WITH vec_distances AS (
+          SELECT
+            dv.rowid as id,
+            dv.distance as vec_distance
+          FROM documents_vec dv
+          JOIN versions v ON dv.version_id = v.id
+          JOIN libraries l ON v.library_id = l.id
+          WHERE l.name = ?
+            AND COALESCE(v.name, '') = COALESCE(?, '')
+            AND dv.embedding MATCH ?
+            AND dv.k = ?
+          ORDER BY dv.distance
+        ),
+        fts_scores AS (
+          SELECT
+            f.rowid as id,
+            bm25(documents_fts, 10.0, 1.0, 5.0, 1.0) as fts_score
+          FROM documents_fts f
+          JOIN documents d ON f.rowid = d.id
+          JOIN versions v ON d.version_id = v.id
+          JOIN libraries l ON v.library_id = l.id
+          WHERE l.name = ?
+            AND COALESCE(v.name, '') = COALESCE(?, '')
+            AND documents_fts MATCH ?
+          ORDER BY fts_score
+          LIMIT ?
+        )
+        SELECT
+          d.id,
+          d.content,
+          d.metadata,
+          COALESCE(1 / (1 + v.vec_distance), 0) as vec_score,
+          COALESCE(-MIN(f.fts_score, 0), 0) as fts_score
+        FROM documents d
+        LEFT JOIN vec_distances v ON d.id = v.id
+        LEFT JOIN fts_scores f ON d.id = f.id
+        WHERE v.id IS NOT NULL OR f.id IS NOT NULL
+      `);
+      const rawResults = stmt.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        JSON.stringify(embedding),
+        limit,
+        library.toLowerCase(),
+        normalizedVersion,
+        ftsQuery,
+        // Use the escaped query
+        limit
+      );
+      const rankedResults = this.assignRanks(rawResults);
+      const topResults = rankedResults.sort((a, b) => b.rrf_score - a.rrf_score).slice(0, limit);
+      return topResults.map((row) => ({
+        ...mapDbDocumentToDocument(row),
+        metadata: {
+          ...JSON.parse(row.metadata),
+          id: row.id,
+          score: row.rrf_score,
+          vec_rank: row.vec_rank,
+          fts_rank: row.fts_rank
+        }
+      }));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find documents by content with query "${query}"`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds child chunks of a given document based on path hierarchy.
+   */
+  async findChildChunks(library, version2, id, limit) {
+    try {
+      const parent = await this.getById(id);
+      if (!parent) {
+        return [];
+      }
+      const parentPath = parent.metadata.path ?? [];
+      const parentUrl = parent.metadata.url;
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.getChildChunks.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        parentUrl,
+        parentPath.length + 1,
+        JSON.stringify(parentPath),
+        BigInt(id),
+        limit
+      );
+      return result.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(`Failed to find child chunks for ID ${id}`, error);
+    }
+  }
+  /**
+   * Finds preceding sibling chunks of a given document.
+   */
+  async findPrecedingSiblingChunks(library, version2, id, limit) {
+    try {
+      const reference = await this.getById(id);
+      if (!reference) {
+        return [];
+      }
+      const refMetadata = reference.metadata;
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.getPrecedingSiblings.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        refMetadata.url,
+        BigInt(id),
+        JSON.stringify(refMetadata.path),
+        limit
+      );
+      return result.reverse().map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find preceding sibling chunks for ID ${id}`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds subsequent sibling chunks of a given document.
+   */
+  async findSubsequentSiblingChunks(library, version2, id, limit) {
+    try {
+      const reference = await this.getById(id);
+      if (!reference) {
+        return [];
+      }
+      const refMetadata = reference.metadata;
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.getSubsequentSiblings.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        refMetadata.url,
+        BigInt(id),
+        JSON.stringify(refMetadata.path),
+        limit
+      );
+      return result.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError(
+        `Failed to find subsequent sibling chunks for ID ${id}`,
+        error
+      );
+    }
+  }
+  /**
+   * Finds the parent chunk of a given document.
+   */
+  async findParentChunk(library, version2, id) {
+    try {
+      const child = await this.getById(id);
+      if (!child) {
+        return null;
+      }
+      const childMetadata = child.metadata;
+      const path2 = childMetadata.path ?? [];
+      const parentPath = path2.slice(0, -1);
+      if (parentPath.length === 0) {
+        return null;
+      }
+      const normalizedVersion = version2.toLowerCase();
+      const result = this.statements.getParentChunk.get(
+        library.toLowerCase(),
+        normalizedVersion,
+        childMetadata.url,
+        JSON.stringify(parentPath),
+        BigInt(id)
+      );
+      if (!result) {
+        return null;
+      }
+      return mapDbDocumentToDocument(result);
+    } catch (error) {
+      throw new ConnectionError(`Failed to find parent chunk for ID ${id}`, error);
+    }
+  }
+  /**
+   * Fetches multiple documents by their IDs in a single call.
+   * Returns an array of Document objects, sorted by their sort_order.
+   */
+  async findChunksByIds(library, version2, ids) {
+    if (!ids.length) return [];
+    try {
+      const normalizedVersion = version2.toLowerCase();
+      const placeholders = ids.map(() => "?").join(",");
+      const stmt = this.db.prepare(
+        `SELECT d.* FROM documents d
+         JOIN libraries l ON d.library_id = l.id
+         JOIN versions v ON d.version_id = v.id
+         WHERE l.name = ? 
+           AND COALESCE(v.name, '') = COALESCE(?, '')
+           AND d.id IN (${placeholders}) 
+         ORDER BY d.sort_order`
+      );
+      const rows = stmt.all(
+        library.toLowerCase(),
+        normalizedVersion,
+        ...ids
+      );
+      return rows.map((row) => mapDbDocumentToDocument(row));
+    } catch (error) {
+      throw new ConnectionError("Failed to fetch documents by IDs", error);
+    }
+  }
+}
+class DocumentManagementService {
+  store;
+  documentRetriever;
+  splitter;
+  /**
+   * Normalizes a version string, converting null or undefined to an empty string
+   * and converting to lowercase.
+   */
+  normalizeVersion(version2) {
+    return (version2 ?? "").toLowerCase();
+  }
+  constructor(embeddingConfig) {
+    let dbPath;
+    let dbDir;
+    const envStorePath = process.env.DOCS_MCP_STORE_PATH;
+    if (envStorePath) {
+      dbDir = envStorePath;
+      dbPath = path.join(dbDir, "documents.db");
+      logger.debug(`Using database directory from DOCS_MCP_STORE_PATH: ${dbDir}`);
+    } else {
+      const projectRoot2 = getProjectRoot();
+      const oldDbDir = path.join(projectRoot2, ".store");
+      const oldDbPath = path.join(oldDbDir, "documents.db");
+      const oldDbExists = fs.existsSync(oldDbPath);
+      if (oldDbExists) {
+        dbPath = oldDbPath;
+        dbDir = oldDbDir;
+        logger.debug(`Using legacy database path: ${dbPath}`);
+      } else {
+        const standardPaths = envPaths("docs-mcp-server", { suffix: "" });
+        dbDir = standardPaths.data;
+        dbPath = path.join(dbDir, "documents.db");
+        logger.debug(`Using standard database directory: ${dbDir}`);
+      }
+    }
+    try {
+      fs.mkdirSync(dbDir, { recursive: true });
+    } catch (error) {
+      logger.error(`⚠️  Failed to create database directory ${dbDir}: ${error}`);
+    }
+    this.store = new DocumentStore(dbPath, embeddingConfig);
+    this.documentRetriever = new DocumentRetrieverService(this.store);
+    const semanticSplitter = new SemanticMarkdownSplitter(
+      SPLITTER_PREFERRED_CHUNK_SIZE,
+      SPLITTER_MAX_CHUNK_SIZE
+    );
+    const greedySplitter = new GreedySplitter(
+      semanticSplitter,
+      SPLITTER_MIN_CHUNK_SIZE,
+      SPLITTER_PREFERRED_CHUNK_SIZE
+    );
+    this.splitter = greedySplitter;
+  }
+  /**
+   * Initializes the underlying document store.
+   */
+  async initialize() {
+    await this.store.initialize();
+  }
+  /**
+   * Shuts down the underlying document store.
+   */
+  async shutdown() {
+    logger.debug("Shutting down store manager");
+    await this.store.shutdown();
+  }
+  // Status tracking methods for pipeline integration
+  /**
+   * Gets versions by their current status.
+   */
+  async getVersionsByStatus(statuses) {
+    return this.store.getVersionsByStatus(statuses);
+  }
+  /**
+   * Updates the status of a version.
+   */
+  async updateVersionStatus(versionId, status, errorMessage) {
+    return this.store.updateVersionStatus(versionId, status, errorMessage);
+  }
+  /**
+   * Updates the progress of a version being indexed.
+   */
+  async updateVersionProgress(versionId, pages, maxPages) {
+    return this.store.updateVersionProgress(versionId, pages, maxPages);
+  }
+  /**
+   * Stores scraper options for a version to enable reproducible indexing.
+   */
+  async storeScraperOptions(versionId, options) {
+    return this.store.storeScraperOptions(versionId, options);
+  }
+  /**
+   * Retrieves stored scraper options for a version.
+   */
+  /**
+   * Retrieves stored scraping configuration for a version.
+   */
+  async getScraperOptions(versionId) {
+    return this.store.getScraperOptions(versionId);
+  }
+  /**
+   * Ensures a library/version exists using a VersionRef and returns version ID.
+   * Delegates to existing ensureLibraryAndVersion for storage.
+   */
+  async ensureVersion(ref) {
+    const normalized = {
+      library: ref.library.trim().toLowerCase(),
+      version: (ref.version ?? "").trim().toLowerCase()
+    };
+    return this.ensureLibraryAndVersion(normalized.library, normalized.version);
+  }
+  /**
+   * Returns enriched library summaries including version status/progress and counts.
+   * Uses existing store APIs; keeps DB details encapsulated.
+   */
+  async listLibraries() {
+    const libMap = await this.store.queryLibraryVersions();
+    const summaries = [];
+    for (const [library, versions] of libMap) {
+      const vs = versions.map(
+        (v) => ({
+          id: v.versionId,
+          ref: { library, version: v.version },
+          status: v.status,
+          // Include progress only while indexing is active; set undefined for COMPLETED
+          progress: v.status === "completed" ? void 0 : { pages: v.progressPages, maxPages: v.progressMaxPages },
+          counts: { documents: v.documentCount, uniqueUrls: v.uniqueUrlCount },
+          indexedAt: v.indexedAt,
+          sourceUrl: v.sourceUrl ?? void 0
+        })
+      );
+      summaries.push({ library, versions: vs });
+    }
+    return summaries;
+  }
+  /**
+   * Finds versions that were indexed from the same source URL.
+   */
+  async findVersionsBySourceUrl(url) {
+    return this.store.findVersionsBySourceUrl(url);
+  }
+  /**
+   * Validates if a library exists in the store (either versioned or unversioned).
+   * Throws LibraryNotFoundError with suggestions if the library is not found.
+   * @param library The name of the library to validate.
+   * @throws {LibraryNotFoundError} If the library does not exist.
+   */
+  async validateLibraryExists(library) {
+    logger.info(`🔎 Validating existence of library: ${library}`);
+    const normalizedLibrary = library.toLowerCase();
+    const versions = await this.listVersions(normalizedLibrary);
+    const hasUnversioned = await this.exists(normalizedLibrary, "");
+    if (versions.length === 0 && !hasUnversioned) {
+      logger.warn(`⚠️  Library '${library}' not found.`);
+      const allLibraries = await this.listLibraries();
+      const libraryNames = allLibraries.map((lib) => lib.library);
+      let suggestions = [];
+      if (libraryNames.length > 0) {
+        const fuse = new Fuse(libraryNames, {
+          // Configure fuse.js options if needed (e.g., threshold)
+          // isCaseSensitive: false, // Handled by normalizing library names
+          // includeScore: true,
+          threshold: 0.4
+          // Adjust threshold for desired fuzziness (0=exact, 1=match anything)
+        });
+        const results = fuse.search(normalizedLibrary);
+        suggestions = results.slice(0, 3).map((result) => result.item);
+        logger.info(`🔍 Found suggestions: ${suggestions.join(", ")}`);
+      }
+      throw new LibraryNotFoundError(library, suggestions);
+    }
+    logger.info(`✅ Library '${library}' confirmed to exist.`);
+  }
+  /**
+   * Returns a list of all available semantic versions for a library.
+   */
+  async listVersions(library) {
+    const versions = await this.store.queryUniqueVersions(library);
+    return versions.filter((v) => semver__default.valid(v));
+  }
+  /**
+   * Checks if documents exist for a given library and optional version.
+   * If version is omitted, checks for documents without a specific version.
    */
-  logStartupInfo(address) {
-    logger.info(`🚀 AppServer available at ${address}`);
-    const enabledServices = [];
-    if (this.config.enableWebInterface) {
-      enabledServices.push(`Web interface: ${address}`);
-    }
-    if (this.config.enableMcpServer) {
-      enabledServices.push(`MCP endpoints: ${address}/mcp, ${address}/sse`);
-    }
-    if (this.config.enableApiServer) {
-      enabledServices.push(`API: ${address}/api`);
-    }
-    if (this.config.enableWorker) {
-      enabledServices.push("Embedded worker: enabled");
-    } else if (this.config.externalWorkerUrl) {
-      enabledServices.push(`External worker: ${this.config.externalWorkerUrl}`);
+  async exists(library, version2) {
+    const normalizedVersion = this.normalizeVersion(version2);
+    return this.store.checkDocumentExists(library, normalizedVersion);
+  }
+  /**
+   * Finds the most appropriate version of documentation based on the requested version.
+   * When no target version is specified, returns the latest version.
+   *
+   * Version matching behavior:
+   * - Exact versions (e.g., "18.0.0"): Matches that version or any earlier version
+   * - X-Range patterns (e.g., "5.x", "5.2.x"): Matches within the specified range
+   * - "latest" or no version: Returns the latest available version
+   *
+   * For documentation, we prefer matching older versions over no match at all,
+   * since older docs are often still relevant and useful.
+   * Also checks if unversioned documents exist for the library.
+   */
+  async findBestVersion(library, targetVersion) {
+    const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
+    logger.info(`🔍 Finding best version for ${libraryAndVersion}`);
+    const hasUnversioned = await this.store.checkDocumentExists(library, "");
+    const versionStrings = await this.listVersions(library);
+    if (versionStrings.length === 0) {
+      if (hasUnversioned) {
+        logger.info(`ℹ️ Unversioned documents exist for ${library}`);
+        return { bestMatch: null, hasUnversioned: true };
+      }
+      logger.warn(`⚠️  No valid versions found for ${library}`);
+      const allLibraryDetails = await this.store.queryLibraryVersions();
+      const libraryDetails = allLibraryDetails.get(library) ?? [];
+      throw new VersionNotFoundError(library, targetVersion ?? "", libraryDetails);
+    }
+    let bestMatch = null;
+    if (!targetVersion || targetVersion === "latest") {
+      bestMatch = semver__default.maxSatisfying(versionStrings, "*");
+    } else {
+      const versionRegex = /^(\d+)(?:\.(?:x(?:\.x)?|\d+(?:\.(?:x|\d+))?))?$|^$/;
+      if (!versionRegex.test(targetVersion)) {
+        logger.warn(`⚠️  Invalid target version format: ${targetVersion}`);
+      } else {
+        let range = targetVersion;
+        if (!semver__default.validRange(targetVersion)) {
+          range = `~${targetVersion}`;
+        } else if (semver__default.valid(targetVersion)) {
+          range = `${range} || <=${targetVersion}`;
+        }
+        bestMatch = semver__default.maxSatisfying(versionStrings, range);
+      }
     }
-    for (const service of enabledServices) {
-      logger.info(`   • ${service}`);
+    if (bestMatch) {
+      logger.info(`✅ Found best match version ${bestMatch} for ${libraryAndVersion}`);
+    } else {
+      logger.warn(`⚠️  No matching semver version found for ${libraryAndVersion}`);
     }
-  }
-}
-async function startAppServer(docService, pipeline, config) {
-  const appServer = new AppServer(docService, pipeline, config);
-  await appServer.start();
-  return appServer;
-}
-async function startStdioServer(tools, readOnly = false) {
-  setLogLevel(LogLevel.ERROR);
-  const server = createMcpServerInstance(tools, readOnly);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  logger.info("🤖 MCP server listening on stdio");
-  return server;
-}
-class StoreError extends Error {
-  constructor(message, cause) {
-    super(cause ? `${message} caused by ${cause}` : message);
-    this.cause = cause;
-    this.name = this.constructor.name;
-    const causeError = cause instanceof Error ? cause : cause ? new Error(String(cause)) : void 0;
-    if (causeError?.stack) {
-      this.stack = causeError.stack;
+    if (!bestMatch && !hasUnversioned) {
+      const allLibraryDetails = await this.store.queryLibraryVersions();
+      const libraryDetails = allLibraryDetails.get(library) ?? [];
+      throw new VersionNotFoundError(library, targetVersion ?? "", libraryDetails);
     }
+    return { bestMatch, hasUnversioned };
   }
-}
-class DimensionError extends StoreError {
-  constructor(modelName, modelDimension, dbDimension) {
-    super(
-      `Model "${modelName}" produces ${modelDimension}-dimensional vectors, which exceeds the database's fixed dimension of ${dbDimension}. Please use a model with dimension ≤ ${dbDimension}.`
-    );
-    this.modelName = modelName;
-    this.modelDimension = modelDimension;
-    this.dbDimension = dbDimension;
-  }
-}
-class ConnectionError extends StoreError {
-}
-const MIGRATIONS_DIR = path.join(getProjectRoot(), "db", "migrations");
-const MIGRATIONS_TABLE = "_schema_migrations";
-function ensureMigrationsTable(db) {
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
-      id TEXT PRIMARY KEY,
-      applied_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  /**
+   * Removes all documents for a specific library and optional version.
+   * If version is omitted, removes documents without a specific version.
+   */
+  async removeAllDocuments(library, version2) {
+    const normalizedVersion = this.normalizeVersion(version2);
+    logger.info(
+      `🗑️ Removing all documents from ${library}@${normalizedVersion || "[no version]"} store`
     );
-  `);
-}
-function getAppliedMigrations(db) {
-  const stmt = db.prepare(`SELECT id FROM ${MIGRATIONS_TABLE}`);
-  const rows = stmt.all();
-  return new Set(rows.map((row) => row.id));
-}
-async function applyMigrations(db) {
-  try {
-    db.pragma("journal_mode = OFF");
-    db.pragma("synchronous = OFF");
-    db.pragma("mmap_size = 268435456");
-    db.pragma("cache_size = -64000");
-    db.pragma("temp_store = MEMORY");
-    logger.debug("Applied performance optimizations for migration");
-  } catch (_error) {
-    logger.warn("⚠️ Could not apply all performance optimizations for migration");
+    const count = await this.store.deleteDocuments(library, normalizedVersion);
+    logger.info(`🗑️ Deleted ${count} documents`);
   }
-  const overallTransaction = db.transaction(() => {
-    logger.debug("Checking database migrations...");
-    ensureMigrationsTable(db);
-    const appliedMigrations = getAppliedMigrations(db);
-    if (!fs.existsSync(MIGRATIONS_DIR)) {
-      throw new StoreError("Migrations directory not found");
-    }
-    const migrationFiles = fs.readdirSync(MIGRATIONS_DIR).filter((file) => file.endsWith(".sql")).sort();
-    const pendingMigrations = migrationFiles.filter(
-      (filename) => !appliedMigrations.has(filename)
+  /**
+   * Completely removes a library version and all associated documents.
+   * Also removes the library if no other versions remain.
+   * @param library Library name
+   * @param version Version string (null/undefined for unversioned)
+   */
+  async removeVersion(library, version2) {
+    const normalizedVersion = this.normalizeVersion(version2);
+    logger.info(`🗑️ Removing version: ${library}@${normalizedVersion || "[no version]"}`);
+    const result = await this.store.removeVersion(library, normalizedVersion, true);
+    logger.info(
+      `🗑️ Removed ${result.documentsDeleted} documents, version: ${result.versionDeleted}, library: ${result.libraryDeleted}`
     );
-    if (pendingMigrations.length > 0) {
-      logger.info(`🔄 Applying ${pendingMigrations.length} database migration(s)...`);
+    if (result.versionDeleted && result.libraryDeleted) {
+      logger.info(`✅ Completely removed library ${library} (was last version)`);
+    } else if (result.versionDeleted) {
+      logger.info(`✅ Removed version ${library}@${normalizedVersion || "[no version]"}`);
+    } else {
+      logger.warn(
+        `⚠️ Version ${library}@${normalizedVersion || "[no version]"} not found`
+      );
     }
-    let appliedCount = 0;
-    for (const filename of pendingMigrations) {
-      logger.debug(`Applying migration: ${filename}`);
-      const filePath = path.join(MIGRATIONS_DIR, filename);
-      const sql = fs.readFileSync(filePath, "utf8");
-      try {
-        db.exec(sql);
-        const insertStmt = db.prepare(`INSERT INTO ${MIGRATIONS_TABLE} (id) VALUES (?)`);
-        insertStmt.run(filename);
-        logger.debug(`Applied migration: ${filename}`);
-        appliedCount++;
-      } catch (error) {
-        logger.error(`❌ Failed to apply migration: ${filename} - ${error}`);
-        throw new StoreError(`Migration failed: ${filename}`, error);
-      }
+  }
+  /**
+   * Adds a document to the store, splitting it into smaller chunks for better search results.
+   * Uses SemanticMarkdownSplitter to maintain markdown structure and content types during splitting.
+   * Preserves hierarchical structure of documents and distinguishes between text and code segments.
+   * If version is omitted, the document is added without a specific version.
+   */
+  async addDocument(library, version2, document) {
+    const processingStart = performance.now();
+    const normalizedVersion = this.normalizeVersion(version2);
+    const url = document.metadata.url;
+    if (!url || typeof url !== "string" || !url.trim()) {
+      throw new StoreError("Document metadata must include a valid URL");
     }
-    if (appliedCount > 0) {
-      logger.info(`✅ Successfully applied ${appliedCount} migration(s)`);
-    } else {
-      logger.debug("Database schema is up to date");
+    logger.info(`📚 Adding document: ${document.metadata.title}`);
+    if (!document.pageContent.trim()) {
+      throw new Error("Document content cannot be empty");
     }
-    return appliedCount;
-  });
-  let retries = 0;
-  let appliedMigrationsCount = 0;
-  while (true) {
     try {
-      appliedMigrationsCount = overallTransaction.immediate();
-      logger.debug("Database migrations completed successfully");
-      if (appliedMigrationsCount > 0) {
-        try {
-          logger.debug(
-            `Running VACUUM after applying ${appliedMigrationsCount} migration(s)...`
-          );
-          db.exec("VACUUM");
-          logger.debug("Database vacuum completed successfully");
-        } catch (error) {
-          logger.warn(`⚠️ Could not vacuum database after migrations: ${error}`);
+      const chunks = await this.splitter.splitText(document.pageContent);
+      const splitDocs = chunks.map((chunk) => ({
+        pageContent: chunk.content,
+        metadata: {
+          ...document.metadata,
+          level: chunk.section.level,
+          path: chunk.section.path
         }
-      } else {
-        logger.debug("Skipping VACUUM - no migrations were applied");
-      }
-      break;
+      }));
+      logger.info(`✂️  Split document into ${splitDocs.length} chunks`);
+      await this.store.addDocuments(library, normalizedVersion, splitDocs);
+      const processingTime = performance.now() - processingStart;
+      analytics.track(TelemetryEvent.DOCUMENT_PROCESSED, {
+        // Content characteristics (privacy-safe)
+        mimeType: document.metadata.mimeType,
+        contentSizeBytes: document.pageContent.length,
+        // Processing metrics
+        processingTimeMs: Math.round(processingTime),
+        chunksCreated: splitDocs.length,
+        // Document characteristics
+        hasTitle: !!document.metadata.title,
+        hasDescription: !!document.metadata.description,
+        urlDomain: extractHostname(url),
+        depth: document.metadata.depth,
+        // Library context
+        library,
+        libraryVersion: normalizedVersion || null,
+        // Processing efficiency
+        avgChunkSizeBytes: Math.round(document.pageContent.length / splitDocs.length),
+        processingSpeedKbPerSec: Math.round(
+          document.pageContent.length / 1024 / (processingTime / 1e3)
+        )
+      });
     } catch (error) {
-      if (error?.code === "SQLITE_BUSY" && retries < MIGRATION_MAX_RETRIES) {
-        retries++;
-        logger.warn(
-          `⚠️  Migrations busy (SQLITE_BUSY), retrying attempt ${retries}/${MIGRATION_MAX_RETRIES} in ${MIGRATION_RETRY_DELAY_MS}ms...`
-        );
-        await new Promise((resolve) => setTimeout(resolve, MIGRATION_RETRY_DELAY_MS));
-      } else {
-        if (error?.code === "SQLITE_BUSY") {
-          logger.error(
-            `❌ Migrations still busy after ${MIGRATION_MAX_RETRIES} retries. Giving up: ${error}`
-          );
-        }
-        if (error instanceof StoreError) {
-          throw error;
-        }
-        throw new StoreError("Failed during migration process", error);
+      const processingTime = performance.now() - processingStart;
+      if (error instanceof Error) {
+        analytics.captureException(error, {
+          mimeType: document.metadata.mimeType,
+          contentSizeBytes: document.pageContent.length,
+          processingTimeMs: Math.round(processingTime),
+          library,
+          libraryVersion: normalizedVersion || null,
+          context: "document_processing",
+          component: DocumentManagementService.constructor.name
+        });
       }
+      throw error;
     }
   }
-  try {
-    db.pragma("journal_mode = WAL");
-    db.pragma("wal_autocheckpoint = 1000");
-    db.pragma("busy_timeout = 30000");
-    db.pragma("foreign_keys = ON");
-    db.pragma("synchronous = NORMAL");
-    logger.debug(
-      "Applied production database configuration (WAL mode, autocheckpoint, foreign keys, busy timeout)"
+  /**
+   * Searches for documentation content across versions.
+   * Uses hybrid search (vector + FTS).
+   * If version is omitted, searches documents without a specific version.
+   */
+  async searchStore(library, version2, query, limit = 5) {
+    const normalizedVersion = this.normalizeVersion(version2);
+    return this.documentRetriever.search(library, normalizedVersion, query, limit);
+  }
+  // Deprecated simple listing removed: enriched listLibraries() is canonical
+  /**
+   * Ensures a library and version exist in the database and returns the version ID.
+   * Creates the library and version records if they don't exist.
+   */
+  async ensureLibraryAndVersion(library, version2) {
+    const normalizedLibrary = library.toLowerCase();
+    const normalizedVersion = this.normalizeVersion(version2);
+    const { versionId } = await this.store.resolveLibraryAndVersionIds(
+      normalizedLibrary,
+      normalizedVersion
     );
-  } catch (_error) {
-    logger.warn("⚠️ Could not apply all production database settings");
+    return versionId;
   }
 }
 async function createDocumentManagement(options = {}) {
   if (options.serverUrl) {
-    const { DocumentManagementClient } = await import("./DocumentManagementClient-CAFdDwTu.js");
     const client = new DocumentManagementClient(options.serverUrl);
     await client.initialize();
     return client;
   }
-  const service = new (await import("./DocumentManagementService-C1xAzouZ.js")).DocumentManagementService();
+  const service = new DocumentManagementService(options.embeddingConfig);
   await service.initialize();
   return service;
 }
-async function createLocalDocumentManagement() {
-  const service = new (await import("./DocumentManagementService-C1xAzouZ.js")).DocumentManagementService();
+async function createLocalDocumentManagement(embeddingConfig) {
+  const service = new DocumentManagementService(embeddingConfig);
   await service.initialize();
   return service;
 }
@@ -6991,6 +9759,17 @@ function warnHttpUsage(authConfig, port) {
     );
   }
 }
+function resolveEmbeddingContext(cliArgs) {
+  try {
+    const modelSpec = cliArgs?.embeddingModel || process.env.DOCS_MCP_EMBEDDING_MODEL;
+    logger.debug("Resolving embedding configuration");
+    const config = EmbeddingConfig.parseEmbeddingConfig(modelSpec);
+    return config;
+  } catch (error) {
+    logger.debug(`Failed to resolve embedding configuration: ${error}`);
+    return null;
+  }
+}
 function createDefaultAction(program) {
   return program.addOption(
     new Option("--protocol <protocol>", "Protocol for MCP server").choices(["auto", "stdio", "http"]).default("auto")
@@ -7030,7 +9809,8 @@ function createDefaultAction(program) {
         warnHttpUsage(authConfig, port);
       }
       ensurePlaywrightBrowsersInstalled();
-      const docService = await createLocalDocumentManagement();
+      const embeddingConfig = resolveEmbeddingContext();
+      const docService = await createLocalDocumentManagement(embeddingConfig);
       const pipelineOptions = {
         recoverJobs: options.resume || false,
         // Use --resume flag for job recovery
@@ -7071,24 +9851,12 @@ async function fetchUrlAction(url, options, command) {
   setupLogging(globalOptions);
   const headers = parseHeaders(options.header);
   const fetchUrlTool = new FetchUrlTool(new HttpFetcher(), new FileFetcher());
-  const content = await trackTool(
-    "fetch_url",
-    () => fetchUrlTool.execute({
-      url,
-      followRedirects: options.followRedirects,
-      scrapeMode: options.scrapeMode,
-      headers: Object.keys(headers).length > 0 ? headers : void 0
-    }),
-    (content2) => ({
-      url_protocol: extractProtocol(url),
-      // Safe: only protocol, not full URL
-      follow_redirects: options.followRedirects,
-      scrape_mode: options.scrapeMode,
-      has_custom_headers: Object.keys(headers).length > 0,
-      content_length: content2.length,
-      cli_flags: extractCliFlags(process.argv)
-    })
-  );
+  const content = await fetchUrlTool.execute({
+    url,
+    followRedirects: options.followRedirects,
+    scrapeMode: options.scrapeMode,
+    headers: Object.keys(headers).length > 0 ? headers : void 0
+  });
   console.log(content);
 }
 function createFetchUrlCommand(program) {
@@ -7120,25 +9888,16 @@ async function findVersionAction(library, options, command) {
   const globalOptions = command.parent?.opts() || {};
   setupLogging(globalOptions);
   const serverUrl = options.serverUrl;
-  const docService = await createDocumentManagement({ serverUrl });
+  const docService = await createDocumentManagement({
+    serverUrl,
+    embeddingConfig: serverUrl ? void 0 : null
+  });
   try {
     const findVersionTool = new FindVersionTool(docService);
-    const versionInfo = await trackTool(
-      "find_version",
-      () => findVersionTool.execute({
-        library,
-        targetVersion: options.version
-      }),
-      (versionInfo2) => ({
-        library,
-        // Safe: library names are public
-        has_target_version: !!options.version,
-        result_type: typeof versionInfo2,
-        // 'string'
-        using_remote_server: !!serverUrl,
-        cli_flags: extractCliFlags(process.argv)
-      })
-    );
+    const versionInfo = await findVersionTool.execute({
+      library,
+      targetVersion: options.version
+    });
     if (!versionInfo) throw new Error("Failed to get version information");
     console.log(versionInfo);
   } finally {
@@ -7155,18 +9914,13 @@ async function listAction(options, command) {
   const globalOptions = command.parent?.opts() || {};
   setupLogging(globalOptions);
   const { serverUrl } = options;
-  const docService = await createDocumentManagement({ serverUrl });
+  const docService = await createDocumentManagement({
+    serverUrl,
+    embeddingConfig: serverUrl ? void 0 : null
+  });
   try {
     const listLibrariesTool = new ListLibrariesTool(docService);
-    const result = await trackTool(
-      "list_libraries",
-      () => listLibrariesTool.execute(),
-      (result2) => ({
-        library_count: result2.libraries.length,
-        using_remote_server: !!serverUrl,
-        cli_flags: extractCliFlags(process.argv)
-      })
-    );
+    const result = await listLibrariesTool.execute();
     console.log(formatOutput(result.libraries));
   } finally {
     await docService.shutdown();
@@ -7219,8 +9973,16 @@ function createMcpCommand(program) {
         validateAuthConfig(authConfig);
       }
       try {
+        const embeddingConfig = resolveEmbeddingContext();
+        if (!serverUrl && !embeddingConfig) {
+          logger.error(
+            "❌ Embedding configuration is required for local mode. Configure an embedding provider with CLI options or environment variables."
+          );
+          process.exit(1);
+        }
         const docService = await createDocumentManagement({
-          serverUrl
+          serverUrl,
+          embeddingConfig
         });
         const pipelineOptions = {
           recoverJobs: false,
@@ -7270,20 +10032,13 @@ async function removeAction(library, options, command) {
   const globalOptions = command.parent?.opts() || {};
   setupLogging(globalOptions);
   const serverUrl = options.serverUrl;
-  const docService = await createDocumentManagement({ serverUrl });
+  const docService = await createDocumentManagement({
+    serverUrl,
+    embeddingConfig: serverUrl ? void 0 : null
+  });
   const { version: version2 } = options;
   try {
-    await trackTool(
-      "remove_documents",
-      () => docService.removeAllDocuments(library, version2),
-      () => ({
-        library,
-        // Safe: library names are public
-        has_version: !!version2,
-        using_remote_server: !!serverUrl,
-        cli_flags: extractCliFlags(process.argv)
-      })
-    );
+    await docService.removeAllDocuments(library, version2);
     console.log(`✅ Successfully removed ${library}${version2 ? `@${version2}` : ""}.`);
   } catch (error) {
     console.error(
@@ -7308,7 +10063,16 @@ async function scrapeAction(library, url, options, command) {
   const globalOptions = command.parent?.opts() || {};
   setupLogging(globalOptions);
   const serverUrl = options.serverUrl;
-  const docService = await createDocumentManagement({ serverUrl });
+  const embeddingConfig = resolveEmbeddingContext();
+  if (!serverUrl && !embeddingConfig) {
+    throw new Error(
+      "Embedding configuration is required for local scraping. Please set DOCS_MCP_EMBEDDING_MODEL environment variable or use --server-url for remote execution."
+    );
+  }
+  const docService = await createDocumentManagement({
+    serverUrl,
+    embeddingConfig
+  });
   let pipeline = null;
   try {
     const pipelineOptions = {
@@ -7323,48 +10087,23 @@ async function scrapeAction(library, url, options, command) {
     await pipeline.start();
     const scrapeTool = new ScrapeTool(pipeline);
     const headers = parseHeaders(options.header);
-    const result = await trackTool(
-      "scrape_docs",
-      () => scrapeTool.execute({
-        url,
-        library,
-        version: options.version,
-        options: {
-          maxPages: Number.parseInt(options.maxPages, 10),
-          maxDepth: Number.parseInt(options.maxDepth, 10),
-          maxConcurrency: Number.parseInt(options.maxConcurrency, 10),
-          ignoreErrors: options.ignoreErrors,
-          scope: options.scope,
-          followRedirects: options.followRedirects,
-          scrapeMode: options.scrapeMode,
-          includePatterns: Array.isArray(options.includePattern) && options.includePattern.length > 0 ? options.includePattern : void 0,
-          excludePatterns: Array.isArray(options.excludePattern) && options.excludePattern.length > 0 ? options.excludePattern : void 0,
-          headers: Object.keys(headers).length > 0 ? headers : void 0
-        }
-      }),
-      (result2) => ({
-        library,
-        // Safe: library names are public
-        url_protocol: extractProtocol(url),
-        // Safe: only protocol, not full URL
-        max_pages: Number.parseInt(options.maxPages, 10),
-        max_depth: Number.parseInt(options.maxDepth, 10),
-        max_concurrency: Number.parseInt(options.maxConcurrency, 10),
-        has_version: !!options.version,
+    const result = await scrapeTool.execute({
+      url,
+      library,
+      version: options.version,
+      options: {
+        maxPages: Number.parseInt(options.maxPages, 10),
+        maxDepth: Number.parseInt(options.maxDepth, 10),
+        maxConcurrency: Number.parseInt(options.maxConcurrency, 10),
+        ignoreErrors: options.ignoreErrors,
         scope: options.scope,
-        scrape_mode: options.scrapeMode,
-        ignore_errors: options.ignoreErrors,
-        follow_redirects: options.followRedirects,
-        has_include_patterns: Array.isArray(options.includePattern) && options.includePattern.length > 0,
-        has_exclude_patterns: Array.isArray(options.excludePattern) && options.excludePattern.length > 0,
-        has_custom_headers: Object.keys(headers).length > 0,
-        using_remote_server: !!serverUrl,
-        cli_flags: extractCliFlags(process.argv),
-        is_async_job: !("pagesScraped" in result2),
-        // Pipeline mode vs direct mode
-        pages_scraped: "pagesScraped" in result2 ? result2.pagesScraped : void 0
-      })
-    );
+        followRedirects: options.followRedirects,
+        scrapeMode: options.scrapeMode,
+        includePatterns: Array.isArray(options.includePattern) && options.includePattern.length > 0 ? options.includePattern : void 0,
+        excludePatterns: Array.isArray(options.excludePattern) && options.excludePattern.length > 0 ? options.excludePattern : void 0,
+        headers: Object.keys(headers).length > 0 ? headers : void 0
+      }
+    });
     if ("pagesScraped" in result) {
       console.log(`✅ Successfully scraped ${result.pagesScraped} pages`);
     } else {
@@ -7443,31 +10182,25 @@ async function searchAction(library, query, options, command) {
   const globalOptions = command.parent?.opts() || {};
   setupLogging(globalOptions);
   const serverUrl = options.serverUrl;
-  const docService = await createDocumentManagement({ serverUrl });
+  const embeddingConfig = resolveEmbeddingContext();
+  if (!serverUrl && !embeddingConfig) {
+    throw new Error(
+      "Embedding configuration is required for local search. Please set DOCS_MCP_EMBEDDING_MODEL environment variable or use --server-url for remote execution."
+    );
+  }
+  const docService = await createDocumentManagement({
+    serverUrl,
+    embeddingConfig
+  });
   try {
     const searchTool = new SearchTool(docService);
-    const result = await trackTool(
-      "search_docs",
-      () => searchTool.execute({
-        library,
-        version: options.version,
-        query,
-        limit: Number.parseInt(options.limit, 10),
-        exactMatch: options.exactMatch
-      }),
-      (result2) => ({
-        library,
-        // Safe: library names are public
-        query_analysis: analyzeSearchQuery(query),
-        // Analyzed, not raw query
-        result_count: result2.results.length,
-        limit_used: Number.parseInt(options.limit, 10),
-        has_version_filter: !!options.version,
-        exact_match: options.exactMatch,
-        using_remote_server: !!serverUrl,
-        cli_flags: extractCliFlags(process.argv)
-      })
-    );
+    const result = await searchTool.execute({
+      library,
+      version: options.version,
+      query,
+      limit: Number.parseInt(options.limit, 10),
+      exactMatch: options.exactMatch
+    });
     console.log(formatOutput(result.results));
   } finally {
     await docService.shutdown();
@@ -7503,8 +10236,16 @@ function createWebCommand(program) {
       const serverUrl = cmdOptions.serverUrl;
       setupLogging(globalOptions);
       try {
+        const embeddingConfig = resolveEmbeddingContext();
+        if (!serverUrl && !embeddingConfig) {
+          logger.error(
+            "❌ Embedding configuration is required for local mode. Configure an embedding provider with CLI options or environment variables."
+          );
+          process.exit(1);
+        }
         const docService = await createDocumentManagement({
-          serverUrl
+          serverUrl,
+          embeddingConfig
         });
         const pipelineOptions = {
           recoverJobs: false,
@@ -7553,7 +10294,8 @@ function createWorkerCommand(program) {
     try {
       logger.info(`🚀 Starting external pipeline worker on port ${port}`);
       ensurePlaywrightBrowsersInstalled();
-      const docService = await createLocalDocumentManagement();
+      const embeddingConfig = resolveEmbeddingContext();
+      const docService = await createLocalDocumentManagement(embeddingConfig);
       const pipelineOptions = {
         recoverJobs: cmdOptions.resume,
         // Use the resume option
@@ -7581,7 +10323,7 @@ function createCliProgram() {
   program.name("docs-mcp-server").description("Unified CLI, MCP Server, and Web Interface for Docs MCP Server.").version(packageJson.version).addOption(
     new Option("--verbose", "Enable verbose (debug) logging").conflicts("silent")
   ).addOption(new Option("--silent", "Disable all logging except errors")).addOption(new Option("--no-telemetry", "Disable telemetry collection")).enablePositionalOptions().allowExcessArguments(false).showHelpAfterError(true);
-  program.hook("preAction", (thisCommand, actionCommand) => {
+  program.hook("preAction", async (thisCommand, actionCommand) => {
     const globalOptions = thisCommand.opts();
     if (globalOptions.silent) setLogLevel(LogLevel.ERROR);
     else if (globalOptions.verbose) setLogLevel(LogLevel.DEBUG);
@@ -7672,7 +10414,11 @@ async function runCli() {
     });
     await program.parseAsync(process.argv);
   } catch (error) {
-    logger.error(`❌ Error in CLI: ${error}`);
+    if (error instanceof ModelConfigurationError || error instanceof UnsupportedProviderError) {
+      logger.error(error.message);
+    } else {
+      logger.error(`❌ Error in CLI: ${error}`);
+    }
     if (!isShuttingDown) {
       isShuttingDown = true;
       const shutdownPromises = [];
@@ -7722,27 +10468,4 @@ runCli().catch((error) => {
   console.error(`🔥 Fatal error in main execution: ${error}`);
   process.exit(1);
 });
-export {
-  ConnectionError as C,
-  DimensionError as D,
-  EMBEDDING_BATCH_CHARS as E,
-  LibraryNotFoundError as L,
-  StoreError as S,
-  TelemetryEvent as T,
-  VECTOR_DIMENSION as V,
-  applyMigrations as a,
-  EMBEDDING_BATCH_SIZE as b,
-  createJSDOM as c,
-  denormalizeVersionName as d,
-  SPLITTER_PREFERRED_CHUNK_SIZE as e,
-  SPLITTER_MAX_CHUNK_SIZE as f,
-  getProjectRoot as g,
-  VersionNotFoundError as h,
-  analytics as i,
-  extractHostname as j,
-  SPLITTER_MIN_CHUNK_SIZE as k,
-  logger as l,
-  mapDbDocumentToDocument as m,
-  normalizeVersionName as n
-};
 //# sourceMappingURL=index.js.map