searchsocket 0.5.0 → 0.6.0

package/dist/cli.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import fs8 from "fs";
-import fsp from "fs/promises";
-import path12 from "path";
+import fs11 from "fs";
+import fsp2 from "fs/promises";
+import path15 from "path";
 import { execSync as execSync2 } from "child_process";
 import { config as dotenvConfig } from "dotenv";
 import chokidar from "chokidar";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 
 // package.json
 var package_default = {
   name: "searchsocket",
-  version: "0.5.0",
+  version: "0.6.0",
   description: "Semantic site search and MCP retrieval for SvelteKit static sites",
   license: "MIT",
   author: "Greg Priday <greg@siteorigin.com>",
@@ -38,6 +38,7 @@ var package_default = {
   files: [
     "dist",
     "!dist/**/*.map",
+    "src/svelte",
     "README.md"
   ],
   bin: {
@@ -63,6 +64,19 @@ var package_default = {
       types: "./dist/scroll.d.ts",
       import: "./dist/scroll.js",
       require: "./dist/scroll.cjs"
+    },
+    "./svelte": {
+      types: "./src/svelte/index.svelte.ts",
+      svelte: "./src/svelte/index.svelte.ts",
+      default: "./src/svelte/index.svelte.ts"
+    }
+  },
+  peerDependencies: {
+    svelte: "^5.0.0"
+  },
+  peerDependenciesMeta: {
+    svelte: {
+      optional: true
     }
   },
   scripts: {
@@ -78,8 +92,9 @@ var package_default = {
   },
   packageManager: "pnpm@10.29.2",
   dependencies: {
+    "@clack/prompts": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@upstash/search": "^0.1.7",
+    "@upstash/vector": "^1.2.3",
     cheerio: "^1.2.0",
     chokidar: "^5.0.0",
     commander: "^14.0.3",
@@ -88,16 +103,19 @@ var package_default = {
     "fast-glob": "^3.3.3",
     "gray-matter": "^4.0.3",
     jiti: "^2.6.1",
+    magicast: "^0.5.2",
     "p-limit": "^7.3.0",
     turndown: "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     zod: "^4.3.6"
   },
   devDependencies: {
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/express": "^5.0.6",
     "@types/node": "^25.2.2",
     "@types/turndown": "^5.0.6",
     jsdom: "^28.1.0",
+    svelte: "^5.55.1",
     tsup: "^8.5.1",
     typescript: "^5.9.3",
     vitest: "^4.0.18"
@@ -154,6 +172,7 @@ var searchSocketConfigSchema = z.object({
     dropSelectors: z.array(z.string()).optional(),
     ignoreAttr: z.string().optional(),
     noindexAttr: z.string().optional(),
+    imageDescAttr: z.string().optional(),
     respectRobotsNoindex: z.boolean().optional()
   }).optional(),
   transform: z.object({
@@ -169,35 +188,48 @@ var searchSocketConfigSchema = z.object({
     headingPathDepth: z.number().int().positive().optional(),
     dontSplitInside: z.array(z.enum(["code", "table", "blockquote"])).optional(),
     prependTitle: z.boolean().optional(),
-    pageSummaryChunk: z.boolean().optional()
+    pageSummaryChunk: z.boolean().optional(),
+    weightHeadings: z.boolean().optional()
   }).optional(),
   upstash: z.object({
     url: z.string().url().optional(),
     token: z.string().min(1).optional(),
     urlEnv: z.string().min(1).optional(),
-    tokenEnv: z.string().min(1).optional()
+    tokenEnv: z.string().min(1).optional(),
+    namespaces: z.object({
+      pages: z.string().min(1).optional(),
+      chunks: z.string().min(1).optional()
+    }).optional()
+  }).optional(),
+  embedding: z.object({
+    model: z.string().optional(),
+    dimensions: z.number().int().positive().optional(),
+    taskType: z.string().optional(),
+    batchSize: z.number().int().positive().optional()
   }).optional(),
   search: z.object({
-    semanticWeight: z.number().min(0).max(1).optional(),
-    inputEnrichment: z.boolean().optional(),
-    reranking: z.boolean().optional(),
     dualSearch: z.boolean().optional(),
     pageSearchWeight: z.number().min(0).max(1).optional()
   }).optional(),
   ranking: z.object({
     enableIncomingLinkBoost: z.boolean().optional(),
     enableDepthBoost: z.boolean().optional(),
+    enableFreshnessBoost: z.boolean().optional(),
+    freshnessDecayRate: z.number().positive().optional(),
+    enableAnchorTextBoost: z.boolean().optional(),
     pageWeights: z.record(z.string(), z.number().min(0)).optional(),
     aggregationCap: z.number().int().positive().optional(),
     aggregationDecay: z.number().min(0).max(1).optional(),
     minChunkScoreRatio: z.number().min(0).max(1).optional(),
-    minScore: z.number().min(0).max(1).optional(),
+    minScoreRatio: z.number().min(0).max(1).optional(),
     scoreGapThreshold: z.number().min(0).max(1).optional(),
     weights: z.object({
       incomingLinks: z.number().optional(),
       depth: z.number().optional(),
       aggregation: z.number().optional(),
-      titleMatch: z.number().optional()
+      titleMatch: z.number().optional(),
+      freshness: z.number().optional(),
+      anchorText: z.number().optional()
     }).optional()
   }).optional(),
   api: z.object({
@@ -212,12 +244,28 @@ var searchSocketConfigSchema = z.object({
   }).optional(),
   mcp: z.object({
     enable: z.boolean().optional(),
+    access: z.enum(["public", "private"]).optional(),
     transport: z.enum(["stdio", "http"]).optional(),
     http: z.object({
       port: z.number().int().positive().optional(),
-      path: z.string().optional()
+      path: z.string().optional(),
+      apiKey: z.string().min(1).optional(),
+      apiKeyEnv: z.string().min(1).optional()
+    }).optional(),
+    handle: z.object({
+      path: z.string().optional(),
+      apiKey: z.string().min(1).optional(),
+      enableJsonResponse: z.boolean().optional()
     }).optional()
   }).optional(),
+  llmsTxt: z.object({
+    enable: z.boolean().optional(),
+    outputPath: z.string().optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    generateFull: z.boolean().optional(),
+    serveMarkdownVariants: z.boolean().optional()
+  }).optional(),
   state: z.object({
     dir: z.string().optional()
   }).optional()
@@ -256,6 +304,7 @@ function createDefaultConfig(projectId) {
       dropSelectors: DEFAULT_DROP_SELECTORS,
       ignoreAttr: "data-search-ignore",
       noindexAttr: "data-search-noindex",
+      imageDescAttr: "data-search-description",
       respectRobotsNoindex: true
     },
     transform: {
@@ -265,39 +314,52 @@ function createDefaultConfig(projectId) {
     },
     chunking: {
       strategy: "hybrid",
-      maxChars: 2200,
+      maxChars: 1500,
       overlapChars: 200,
       minChars: 250,
       headingPathDepth: 3,
       dontSplitInside: ["code", "table", "blockquote"],
       prependTitle: true,
-      pageSummaryChunk: true
+      pageSummaryChunk: true,
+      weightHeadings: true
     },
     upstash: {
-      urlEnv: "UPSTASH_SEARCH_REST_URL",
-      tokenEnv: "UPSTASH_SEARCH_REST_TOKEN"
+      urlEnv: "UPSTASH_VECTOR_REST_URL",
+      tokenEnv: "UPSTASH_VECTOR_REST_TOKEN",
+      namespaces: {
+        pages: "pages",
+        chunks: "chunks"
+      }
+    },
+    embedding: {
+      model: "bge-large-en-v1.5",
+      dimensions: 1024,
+      taskType: "RETRIEVAL_DOCUMENT",
+      batchSize: 100
     },
     search: {
-      semanticWeight: 0.75,
-      inputEnrichment: true,
-      reranking: true,
       dualSearch: true,
       pageSearchWeight: 0.3
     },
     ranking: {
       enableIncomingLinkBoost: true,
       enableDepthBoost: true,
+      enableFreshnessBoost: false,
+      freshnessDecayRate: 1e-3,
+      enableAnchorTextBoost: false,
       pageWeights: {},
       aggregationCap: 5,
       aggregationDecay: 0.5,
       minChunkScoreRatio: 0.5,
-      minScore: 0.3,
+      minScoreRatio: 0.7,
       scoreGapThreshold: 0.4,
       weights: {
         incomingLinks: 0.05,
         depth: 0.03,
         aggregation: 0.1,
-        titleMatch: 0.15
+        titleMatch: 0.15,
+        freshness: 0.1,
+        anchorText: 0.1
       }
     },
     api: {
@@ -308,12 +370,23 @@ function createDefaultConfig(projectId) {
     },
     mcp: {
       enable: process.env.NODE_ENV !== "production",
+      access: "private",
       transport: "stdio",
       http: {
         port: 3338,
         path: "/mcp"
+      },
+      handle: {
+        path: "/api/mcp",
+        enableJsonResponse: true
       }
     },
+    llmsTxt: {
+      enable: false,
+      outputPath: "static/llms.txt",
+      generateFull: true,
+      serveMarkdownVariants: false
+    },
     state: {
       dir: ".searchsocket"
     }
@@ -425,7 +498,15 @@ ${issues}`
     },
     upstash: {
       ...defaults.upstash,
-      ...parsed.upstash
+      ...parsed.upstash,
+      namespaces: {
+        ...defaults.upstash.namespaces,
+        ...parsed.upstash?.namespaces
+      }
+    },
+    embedding: {
+      ...defaults.embedding,
+      ...parsed.embedding
     },
     search: {
       ...defaults.search,
@@ -462,8 +543,16 @@ ${issues}`
       http: {
         ...defaults.mcp.http,
         ...parsed.mcp?.http
+      },
+      handle: {
+        ...defaults.mcp.handle,
+        ...parsed.mcp?.handle
       }
     },
+    llmsTxt: {
+      ...defaults.llmsTxt,
+      ...parsed.llmsTxt
+    },
     state: {
       ...defaults.state,
       ...parsed.state
@@ -483,6 +572,15 @@ ${issues}`
       maxDepth: 10
     };
   }
+  if (merged.mcp.access === "public") {
+    const resolvedKey = merged.mcp.http.apiKey ?? (merged.mcp.http.apiKeyEnv ? process.env[merged.mcp.http.apiKeyEnv] : void 0);
+    if (!resolvedKey) {
+      throw new SearchSocketError(
+        "CONFIG_MISSING",
+        '`mcp.access` is "public" but no API key is configured. Set `mcp.http.apiKey` or `mcp.http.apiKeyEnv`.'
+      );
+    }
+  }
   if (merged.source.mode === "crawl" && !merged.source.crawl?.baseUrl) {
     throw new SearchSocketError("CONFIG_MISSING", "`source.crawl.baseUrl` is required when source.mode is crawl.");
   }
@@ -521,8 +619,8 @@ function writeMinimalConfig(cwd) {
     return target;
   }
   const content = `export default {
-  // Upstash Search credentials (set via env vars or directly here)
-  // upstash: { urlEnv: "UPSTASH_SEARCH_REST_URL", tokenEnv: "UPSTASH_SEARCH_REST_TOKEN" }
+  // Upstash Vector credentials (set via env vars or directly here)
+  // upstash: { urlEnv: "UPSTASH_VECTOR_REST_URL", tokenEnv: "UPSTASH_VECTOR_REST_TOKEN" }
 };
 `;
   fs.writeFileSync(target, content, "utf8");
@@ -586,11 +684,11 @@ var Logger = class {
     this.writeOut(`  [${event}] ${data ? JSON.stringify(data) : ""}
 `);
   }
-  writeOut(text) {
+  writeOut(text2) {
     if (this.stderrOnly) {
-      process.stderr.write(text);
+      process.stderr.write(text2);
     } else {
-      process.stdout.write(text);
+      process.stdout.write(text2);
     }
   }
   logJson(event, data) {
@@ -617,13 +715,84 @@ function normalizeMarkdown(input) {
 function sanitizeScopeName(scopeName) {
   return scopeName.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
+function markdownToPlain(markdown) {
+  return markdown.replace(/```[\s\S]*?```/g, " ").replace(/`([^`]+)`/g, "$1").replace(/[#>*_|\-]/g, " ").replace(/\s+/g, " ").trim();
+}
 function toSnippet(markdown, maxLen = 220) {
-  const plain = markdown.replace(/```[\s\S]*?```/g, " ").replace(/`([^`]+)`/g, "$1").replace(/[#>*_|\-]/g, " ").replace(/\s+/g, " ").trim();
+  const plain = markdownToPlain(markdown);
   if (plain.length <= maxLen) {
     return plain;
   }
   return `${plain.slice(0, Math.max(0, maxLen - 1)).trim()}\u2026`;
 }
+function queryAwareExcerpt(markdown, query, maxLen = 220) {
+  const plain = markdownToPlain(markdown);
+  if (plain.length <= maxLen) return plain;
+  const tokens = query.toLowerCase().split(/\s+/).filter((t) => t.length >= 2);
+  if (tokens.length === 0) return toSnippet(markdown, maxLen);
+  const positions = [];
+  for (let ti = 0; ti < tokens.length; ti++) {
+    const escaped = tokens[ti].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(escaped, "gi");
+    let m;
+    while ((m = re.exec(plain)) !== null) {
+      positions.push({ start: m.index, end: m.index + m[0].length, tokenIdx: ti });
+    }
+  }
+  if (positions.length === 0) return toSnippet(markdown, maxLen);
+  positions.sort((a, b) => a.start - b.start);
+  let bestUniqueCount = 0;
+  let bestTotalCount = 0;
+  let bestLeft = 0;
+  let bestRight = 0;
+  let left = 0;
+  const tokenCounts = /* @__PURE__ */ new Map();
+  for (let right = 0; right < positions.length; right++) {
+    tokenCounts.set(positions[right].tokenIdx, (tokenCounts.get(positions[right].tokenIdx) ?? 0) + 1);
+    while (positions[right].end - positions[left].start > maxLen && left < right) {
+      const leftToken = positions[left].tokenIdx;
+      const cnt = tokenCounts.get(leftToken) - 1;
+      if (cnt === 0) tokenCounts.delete(leftToken);
+      else tokenCounts.set(leftToken, cnt);
+      left++;
+    }
+    const uniqueCount = tokenCounts.size;
+    const totalCount = right - left + 1;
+    if (uniqueCount > bestUniqueCount || uniqueCount === bestUniqueCount && totalCount > bestTotalCount) {
+      bestUniqueCount = uniqueCount;
+      bestTotalCount = totalCount;
+      bestLeft = left;
+      bestRight = right;
+    }
+  }
+  const mid = Math.floor((positions[bestLeft].start + positions[bestRight].end) / 2);
+  let start = Math.max(0, mid - Math.floor(maxLen / 2));
+  let end = Math.min(plain.length, start + maxLen);
+  start = Math.max(0, end - maxLen);
+  if (start > 0) {
+    const spaceIdx = plain.lastIndexOf(" ", start);
+    if (spaceIdx > start - 30) {
+      start = spaceIdx + 1;
+    }
+  }
+  if (end < plain.length) {
+    const spaceIdx = plain.indexOf(" ", end);
+    if (spaceIdx !== -1 && spaceIdx < end + 30) {
+      end = spaceIdx;
+    }
+  }
+  let excerpt = plain.slice(start, end);
+  if (excerpt.length > Math.ceil(maxLen * 1.2)) {
+    excerpt = excerpt.slice(0, maxLen);
+    const lastSpace = excerpt.lastIndexOf(" ");
+    if (lastSpace > maxLen * 0.5) {
+      excerpt = excerpt.slice(0, lastSpace);
+    }
+  }
+  const prefix = start > 0 ? "\u2026" : "";
+  const suffix = end < plain.length ? "\u2026" : "";
+  return `${prefix}${excerpt}${suffix}`;
+}
 function extractFirstParagraph(markdown) {
   const lines = markdown.split("\n");
   let inFence = false;
@@ -690,163 +859,292 @@ function ensureStateDirs(cwd, stateDir, scope) {
 }
 
 // src/indexing/pipeline.ts
-import path10 from "path";
+import path11 from "path";
 
 // src/vector/upstash.ts
-function chunkIndexName(scope) {
-  return `${scope.projectId}--${scope.scopeName}`;
-}
-function pageIndexName(scope) {
-  return `${scope.projectId}--${scope.scopeName}--pages`;
-}
+import { QueryMode, FusionAlgorithm } from "@upstash/vector";
 var UpstashSearchStore = class {
-  client;
+  index;
+  pagesNs;
+  chunksNs;
   constructor(opts) {
-    this.client = opts.client;
-  }
-  chunkIndex(scope) {
-    return this.client.index(chunkIndexName(scope));
-  }
-  pageIndex(scope) {
-    return this.client.index(pageIndexName(scope));
+    this.index = opts.index;
+    this.pagesNs = opts.index.namespace(opts.pagesNamespace);
+    this.chunksNs = opts.index.namespace(opts.chunksNamespace);
   }
   async upsertChunks(chunks, scope) {
     if (chunks.length === 0) return;
-    const index = this.chunkIndex(scope);
     const BATCH_SIZE = 100;
     for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
       const batch = chunks.slice(i, i + BATCH_SIZE);
-      await index.upsert(batch);
-    }
-  }
-  async search(query, opts, scope) {
-    const index = this.chunkIndex(scope);
-    const results = await index.search({
-      query,
-      limit: opts.limit,
-      semanticWeight: opts.semanticWeight,
-      inputEnrichment: opts.inputEnrichment,
-      reranking: opts.reranking,
-      filter: opts.filter
+      await this.chunksNs.upsert(
+        batch.map((c) => ({
+          id: c.id,
+          data: c.data,
+          metadata: {
+            ...c.metadata,
+            projectId: scope.projectId,
+            scopeName: scope.scopeName,
+            type: c.metadata.type || "chunk"
+          }
+        }))
+      );
+    }
+  }
+  async search(data, opts, scope) {
+    const filterParts = [
+      `projectId = '${scope.projectId}'`,
+      `scopeName = '${scope.scopeName}'`
+    ];
+    if (opts.filter) {
+      filterParts.push(opts.filter);
+    }
+    const results = await this.chunksNs.query({
+      data,
+      topK: opts.limit,
+      includeMetadata: true,
+      filter: filterParts.join(" AND "),
+      queryMode: QueryMode.HYBRID,
+      fusionAlgorithm: FusionAlgorithm.DBSF
+    });
+    return results.map((doc) => ({
+      id: String(doc.id),
+      score: doc.score,
+      metadata: {
+        projectId: doc.metadata?.projectId ?? "",
+        scopeName: doc.metadata?.scopeName ?? "",
+        url: doc.metadata?.url ?? "",
+        path: doc.metadata?.path ?? "",
+        title: doc.metadata?.title ?? "",
+        sectionTitle: doc.metadata?.sectionTitle ?? "",
+        headingPath: doc.metadata?.headingPath ? String(doc.metadata.headingPath).split(" > ").filter(Boolean) : [],
+        snippet: doc.metadata?.snippet ?? "",
+        chunkText: doc.metadata?.chunkText ?? "",
+        ordinal: doc.metadata?.ordinal ?? 0,
+        contentHash: doc.metadata?.contentHash ?? "",
+        depth: doc.metadata?.depth ?? 0,
+        incomingLinks: doc.metadata?.incomingLinks ?? 0,
+        routeFile: doc.metadata?.routeFile ?? "",
+        tags: doc.metadata?.tags ?? [],
+        description: doc.metadata?.description || void 0,
+        keywords: doc.metadata?.keywords?.length ? doc.metadata.keywords : void 0,
+        publishedAt: typeof doc.metadata?.publishedAt === "number" ? doc.metadata.publishedAt : void 0,
+        incomingAnchorText: doc.metadata?.incomingAnchorText || void 0
+      }
+    }));
+  }
+  async searchChunksByUrl(data, url, opts, scope) {
+    const filterParts = [
+      `projectId = '${scope.projectId}'`,
+      `scopeName = '${scope.scopeName}'`,
+      `url = '${url}'`
+    ];
+    if (opts.filter) {
+      filterParts.push(opts.filter);
+    }
+    const results = await this.chunksNs.query({
+      data,
+      topK: opts.limit,
+      includeMetadata: true,
+      filter: filterParts.join(" AND "),
+      queryMode: QueryMode.HYBRID,
+      fusionAlgorithm: FusionAlgorithm.DBSF
     });
     return results.map((doc) => ({
-      id: doc.id,
+      id: String(doc.id),
       score: doc.score,
       metadata: {
         projectId: doc.metadata?.projectId ?? "",
         scopeName: doc.metadata?.scopeName ?? "",
-        url: doc.content.url,
+        url: doc.metadata?.url ?? "",
         path: doc.metadata?.path ?? "",
-        title: doc.content.title,
-        sectionTitle: doc.content.sectionTitle,
-        headingPath: doc.content.headingPath ? doc.content.headingPath.split(" > ").filter(Boolean) : [],
+        title: doc.metadata?.title ?? "",
+        sectionTitle: doc.metadata?.sectionTitle ?? "",
+        headingPath: doc.metadata?.headingPath ? String(doc.metadata.headingPath).split(" > ").filter(Boolean) : [],
         snippet: doc.metadata?.snippet ?? "",
-        chunkText: doc.content.text,
+        chunkText: doc.metadata?.chunkText ?? "",
         ordinal: doc.metadata?.ordinal ?? 0,
         contentHash: doc.metadata?.contentHash ?? "",
         depth: doc.metadata?.depth ?? 0,
         incomingLinks: doc.metadata?.incomingLinks ?? 0,
         routeFile: doc.metadata?.routeFile ?? "",
-        tags: doc.content.tags ? doc.content.tags.split(",").filter(Boolean) : [],
+        tags: doc.metadata?.tags ?? [],
         description: doc.metadata?.description || void 0,
-        keywords: doc.metadata?.keywords ? doc.metadata.keywords.split(",").filter(Boolean) : void 0
+        keywords: doc.metadata?.keywords?.length ? doc.metadata.keywords : void 0,
+        publishedAt: typeof doc.metadata?.publishedAt === "number" ? doc.metadata.publishedAt : void 0,
+        incomingAnchorText: doc.metadata?.incomingAnchorText || void 0
       }
     }));
   }
-  async searchPages(query, opts, scope) {
-    const index = this.pageIndex(scope);
+  async searchPagesByText(data, opts, scope) {
+    return this.queryPages({ data }, opts, scope);
+  }
+  async searchPagesByVector(vector, opts, scope) {
+    return this.queryPages({ vector }, opts, scope);
+  }
+  async queryPages(input, opts, scope) {
+    const filterParts = [
+      `projectId = '${scope.projectId}'`,
+      `scopeName = '${scope.scopeName}'`
+    ];
+    if (opts.filter) {
+      filterParts.push(opts.filter);
+    }
     let results;
     try {
-      results = await index.search({
-        query,
-        limit: opts.limit,
-        semanticWeight: opts.semanticWeight,
-        inputEnrichment: opts.inputEnrichment,
-        reranking: true,
-        filter: opts.filter
+      results = await this.pagesNs.query({
+        ...input,
+        topK: opts.limit,
+        includeMetadata: true,
+        filter: filterParts.join(" AND "),
+        queryMode: QueryMode.HYBRID,
+        fusionAlgorithm: FusionAlgorithm.DBSF
       });
     } catch {
       return [];
     }
     return results.map((doc) => ({
-      id: doc.id,
+      id: String(doc.id),
       score: doc.score,
-      title: doc.content.title,
-      url: doc.content.url,
-      description: doc.content.description ?? "",
-      tags: doc.content.tags ? doc.content.tags.split(",").filter(Boolean) : [],
+      title: doc.metadata?.title ?? "",
+      url: doc.metadata?.url ?? "",
+      description: doc.metadata?.description ?? "",
+      tags: doc.metadata?.tags ?? [],
       depth: doc.metadata?.depth ?? 0,
       incomingLinks: doc.metadata?.incomingLinks ?? 0,
-      routeFile: doc.metadata?.routeFile ?? ""
+      routeFile: doc.metadata?.routeFile ?? "",
+      publishedAt: typeof doc.metadata?.publishedAt === "number" ? doc.metadata.publishedAt : void 0
     }));
   }
-  async deleteByIds(ids, scope) {
+  async deleteByIds(ids, _scope) {
     if (ids.length === 0) return;
-    const index = this.chunkIndex(scope);
-    const BATCH_SIZE = 500;
+    const BATCH_SIZE = 100;
     for (let i = 0; i < ids.length; i += BATCH_SIZE) {
       const batch = ids.slice(i, i + BATCH_SIZE);
-      await index.delete(batch);
+      await this.chunksNs.delete(batch);
     }
   }
   async deleteScope(scope) {
-    try {
-      const chunkIdx = this.chunkIndex(scope);
-      await chunkIdx.deleteIndex();
-    } catch {
-    }
-    try {
-      const pageIdx = this.pageIndex(scope);
-      await pageIdx.deleteIndex();
-    } catch {
+    for (const ns of [this.chunksNs, this.pagesNs]) {
+      const ids = [];
+      let cursor = "0";
+      try {
+        for (; ; ) {
+          const result = await ns.range({
+            cursor,
+            limit: 100,
+            includeMetadata: true
+          });
+          for (const doc of result.vectors) {
+            if (doc.metadata?.projectId === scope.projectId && doc.metadata?.scopeName === scope.scopeName) {
+              ids.push(String(doc.id));
+            }
+          }
+          if (!result.nextCursor || result.nextCursor === "0") break;
+          cursor = result.nextCursor;
+        }
+      } catch {
+      }
+      if (ids.length > 0) {
+        const BATCH_SIZE = 100;
+        for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+          const batch = ids.slice(i, i + BATCH_SIZE);
+          await ns.delete(batch);
+        }
+      }
     }
   }
   async listScopes(projectId) {
-    const allIndexes = await this.client.listIndexes();
-    const prefix = `${projectId}--`;
-    const scopeNames = /* @__PURE__ */ new Set();
-    for (const name of allIndexes) {
-      if (name.startsWith(prefix) && !name.endsWith("--pages")) {
-        const scopeName = name.slice(prefix.length);
-        scopeNames.add(scopeName);
-      }
-    }
-    const scopes = [];
-    for (const scopeName of scopeNames) {
-      const scope = {
-        projectId,
-        scopeName,
-        scopeId: `${projectId}:${scopeName}`
-      };
+    const scopeMap = /* @__PURE__ */ new Map();
+    for (const ns of [this.chunksNs, this.pagesNs]) {
+      let cursor = "0";
       try {
-        const info = await this.chunkIndex(scope).info();
-        scopes.push({
-          projectId,
-          scopeName,
-          lastIndexedAt: (/* @__PURE__ */ new Date()).toISOString(),
-          documentCount: info.documentCount
-        });
+        for (; ; ) {
+          const result = await ns.range({
+            cursor,
+            limit: 100,
+            includeMetadata: true
+          });
+          for (const doc of result.vectors) {
+            if (doc.metadata?.projectId === projectId) {
+              const scopeName = doc.metadata.scopeName ?? "";
+              scopeMap.set(scopeName, (scopeMap.get(scopeName) ?? 0) + 1);
+            }
+          }
+          if (!result.nextCursor || result.nextCursor === "0") break;
+          cursor = result.nextCursor;
+        }
       } catch {
-        scopes.push({
-          projectId,
-          scopeName,
-          lastIndexedAt: "unknown",
-          documentCount: 0
-        });
       }
     }
-    return scopes;
+    return [...scopeMap.entries()].map(([scopeName, count]) => ({
+      projectId,
+      scopeName,
+      lastIndexedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      documentCount: count
+    }));
   }
   async getContentHashes(scope) {
     const map = /* @__PURE__ */ new Map();
-    const index = this.chunkIndex(scope);
     let cursor = "0";
     try {
       for (; ; ) {
-        const result = await index.range({ cursor, limit: 100 });
-        for (const doc of result.documents) {
-          if (doc.metadata?.contentHash) {
-            map.set(doc.id, doc.metadata.contentHash);
+        const result = await this.chunksNs.range({
+          cursor,
+          limit: 100,
+          includeMetadata: true
+        });
+        for (const doc of result.vectors) {
+          if (doc.metadata?.projectId === scope.projectId && doc.metadata?.scopeName === scope.scopeName && doc.metadata?.contentHash) {
+            map.set(String(doc.id), doc.metadata.contentHash);
+          }
+        }
+        if (!result.nextCursor || result.nextCursor === "0") break;
+        cursor = result.nextCursor;
+      }
+    } catch {
+    }
+    return map;
+  }
+  async listPages(scope, opts) {
+    const cursor = opts?.cursor ?? "0";
+    const limit = opts?.limit ?? 50;
+    try {
+      const result = await this.pagesNs.range({
+        cursor,
+        limit,
+        includeMetadata: true
+      });
+      const pages = result.vectors.filter(
+        (doc) => doc.metadata?.projectId === scope.projectId && doc.metadata?.scopeName === scope.scopeName && (!opts?.pathPrefix || (doc.metadata?.url ?? "").startsWith(opts.pathPrefix))
+      ).map((doc) => ({
+        url: doc.metadata?.url ?? "",
+        title: doc.metadata?.title ?? "",
+        description: doc.metadata?.description ?? "",
+        routeFile: doc.metadata?.routeFile ?? ""
+      }));
+      const response = { pages };
+      if (result.nextCursor && result.nextCursor !== "0") {
+        response.nextCursor = result.nextCursor;
+      }
+      return response;
+    } catch {
+      return { pages: [] };
+    }
+  }
+  async getPageHashes(scope) {
+    const map = /* @__PURE__ */ new Map();
+    let cursor = "0";
+    try {
+      for (; ; ) {
+        const result = await this.pagesNs.range({
+          cursor,
+          limit: 100,
+          includeMetadata: true
+        });
+        for (const doc of result.vectors) {
+          if (doc.metadata?.projectId === scope.projectId && doc.metadata?.scopeName === scope.scopeName && doc.metadata?.contentHash) {
+            map.set(String(doc.id), doc.metadata.contentHash);
           }
         }
         if (!result.nextCursor || result.nextCursor === "0") break;
@@ -856,47 +1154,43 @@ var UpstashSearchStore = class {
     }
     return map;
   }
+  async deletePagesByIds(ids, _scope) {
+    if (ids.length === 0) return;
+    const BATCH_SIZE = 50;
+    for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+      const batch = ids.slice(i, i + BATCH_SIZE);
+      await this.pagesNs.delete(batch);
+    }
+  }
   async upsertPages(pages, scope) {
     if (pages.length === 0) return;
-    const index = this.pageIndex(scope);
     const BATCH_SIZE = 50;
     for (let i = 0; i < pages.length; i += BATCH_SIZE) {
       const batch = pages.slice(i, i + BATCH_SIZE);
-      const docs = batch.map((p) => ({
-        id: p.url,
-        content: {
-          title: p.title,
-          url: p.url,
-          type: "page",
-          description: p.description ?? "",
-          keywords: (p.keywords ?? []).join(","),
-          summary: p.summary ?? "",
-          tags: p.tags.join(",")
-        },
-        metadata: {
-          markdown: p.markdown,
-          projectId: p.projectId,
-          scopeName: p.scopeName,
-          routeFile: p.routeFile,
-          routeResolution: p.routeResolution,
-          incomingLinks: p.incomingLinks,
-          outgoingLinks: p.outgoingLinks,
-          depth: p.depth,
-          indexedAt: p.indexedAt
-        }
-      }));
-      await index.upsert(docs);
+      await this.pagesNs.upsert(
+        batch.map((p) => ({
+          id: p.id,
+          data: p.data,
+          metadata: {
+            ...p.metadata,
+            projectId: scope.projectId,
+            scopeName: scope.scopeName,
+            type: "page"
+          }
+        }))
+      );
     }
   }
   async getPage(url, scope) {
-    const index = this.pageIndex(scope);
     try {
-      const results = await index.fetch([url]);
+      const results = await this.pagesNs.fetch([url], {
+        includeMetadata: true
+      });
       const doc = results[0];
-      if (!doc) return null;
+      if (!doc || !doc.metadata) return null;
       return {
-        url: doc.content.url,
-        title: doc.content.title,
+        url: doc.metadata.url,
+        title: doc.metadata.title,
         markdown: doc.metadata.markdown,
         projectId: doc.metadata.projectId,
         scopeName: doc.metadata.scopeName,
@@ -904,27 +1198,86 @@ var UpstashSearchStore = class {
         routeResolution: doc.metadata.routeResolution,
         incomingLinks: doc.metadata.incomingLinks,
         outgoingLinks: doc.metadata.outgoingLinks,
+        outgoingLinkUrls: doc.metadata.outgoingLinkUrls ?? void 0,
         depth: doc.metadata.depth,
-        tags: doc.content.tags ? doc.content.tags.split(",").filter(Boolean) : [],
+        tags: doc.metadata.tags ?? [],
         indexedAt: doc.metadata.indexedAt,
-        summary: doc.content.summary || void 0,
-        description: doc.content.description || void 0,
-        keywords: doc.content.keywords ? doc.content.keywords.split(",").filter(Boolean) : void 0
+        summary: doc.metadata.summary || void 0,
+        description: doc.metadata.description || void 0,
+        keywords: doc.metadata.keywords?.length ? doc.metadata.keywords : void 0,
+        publishedAt: typeof doc.metadata.publishedAt === "number" ? doc.metadata.publishedAt : void 0
       };
     } catch {
       return null;
     }
   }
+  async fetchPageWithVector(url, scope) {
+    try {
+      const results = await this.pagesNs.fetch([url], {
+        includeMetadata: true,
+        includeVectors: true
+      });
+      const doc = results[0];
+      if (!doc || !doc.metadata || !doc.vector) return null;
+      if (doc.metadata.projectId !== scope.projectId || doc.metadata.scopeName !== scope.scopeName) {
+        return null;
+      }
+      return { metadata: doc.metadata, vector: doc.vector };
+    } catch {
+      return null;
+    }
+  }
+  async fetchPagesBatch(urls, scope) {
+    if (urls.length === 0) return [];
+    try {
+      const results = await this.pagesNs.fetch(urls, {
+        includeMetadata: true
+      });
+      const out = [];
+      for (const doc of results) {
+        if (!doc || !doc.metadata) continue;
+        if (doc.metadata.projectId !== scope.projectId || doc.metadata.scopeName !== scope.scopeName) {
+          continue;
+        }
+        out.push({
+          url: doc.metadata.url,
+          title: doc.metadata.title,
+          routeFile: doc.metadata.routeFile,
+          outgoingLinkUrls: doc.metadata.outgoingLinkUrls ?? []
+        });
+      }
+      return out;
+    } catch {
+      return [];
+    }
+  }
   async deletePages(scope) {
+    const ids = [];
+    let cursor = "0";
     try {
-      const index = this.pageIndex(scope);
-      await index.reset();
+      for (; ; ) {
+        const result = await this.pagesNs.range({
+          cursor,
+          limit: 100,
+          includeMetadata: true
+        });
+        for (const doc of result.vectors) {
+          if (doc.metadata?.projectId === scope.projectId && doc.metadata?.scopeName === scope.scopeName) {
+            ids.push(String(doc.id));
+          }
+        }
+        if (!result.nextCursor || result.nextCursor === "0") break;
+        cursor = result.nextCursor;
+      }
     } catch {
     }
+    if (ids.length > 0) {
+      await this.deletePagesByIds(ids, scope);
+    }
   }
   async health() {
     try {
-      await this.client.info();
+      await this.index.info();
       return { ok: true };
     } catch (error) {
       return {
@@ -934,14 +1287,31 @@ var UpstashSearchStore = class {
     }
   }
   async dropAllIndexes(projectId) {
-    const allIndexes = await this.client.listIndexes();
-    const prefix = `${projectId}--`;
-    for (const name of allIndexes) {
-      if (name.startsWith(prefix)) {
-        try {
-          const index = this.client.index(name);
-          await index.deleteIndex();
-        } catch {
+    for (const ns of [this.chunksNs, this.pagesNs]) {
+      const ids = [];
+      let cursor = "0";
+      try {
+        for (; ; ) {
+          const result = await ns.range({
+            cursor,
+            limit: 100,
+            includeMetadata: true
+          });
+          for (const doc of result.vectors) {
+            if (doc.metadata?.projectId === projectId) {
+              ids.push(String(doc.id));
+            }
+          }
+          if (!result.nextCursor || result.nextCursor === "0") break;
+          cursor = result.nextCursor;
+        }
+      } catch {
+      }
+      if (ids.length > 0) {
+        const BATCH_SIZE = 100;
+        for (let i = 0; i < ids.length; i += BATCH_SIZE) {
+          const batch = ids.slice(i, i + BATCH_SIZE);
+          await ns.delete(batch);
         }
       }
     }
@@ -955,12 +1325,16 @@ async function createUpstashStore(config) {
   if (!url || !token) {
     throw new SearchSocketError(
       "VECTOR_BACKEND_UNAVAILABLE",
-      `Missing Upstash Search credentials. Set ${config.upstash.urlEnv} and ${config.upstash.tokenEnv} environment variables, or pass upstash.url and upstash.token in your config.`
+      `Missing Upstash Vector credentials. Set ${config.upstash.urlEnv} and ${config.upstash.tokenEnv} environment variables, or pass upstash.url and upstash.token in your config.`
     );
   }
-  const { Search } = await import("@upstash/search");
-  const client = new Search({ url, token });
-  return new UpstashSearchStore({ client });
+  const { Index } = await import("@upstash/vector");
+  const index = new Index({ url, token });
+  return new UpstashSearchStore({
+    index,
+    pagesNamespace: config.upstash.namespaces.pages,
+    chunksNamespace: config.upstash.namespaces.chunks
+  });
 }
 
 // src/utils/hash.ts
@@ -1034,6 +1408,7 @@ function parseHeadingSections(markdown, headingPathDepth) {
     if (normalizeText(current.text)) {
       sections.push({
         sectionTitle: current.sectionTitle,
+        headingLevel: current.headingLevel,
         headingPath: current.headingPath,
         text: current.text.trim()
       });
@@ -1052,6 +1427,7 @@ function parseHeadingSections(markdown, headingPathDepth) {
       headingStack.length = level;
       current = {
         sectionTitle: title,
+        headingLevel: level,
         headingPath: headingStack.filter((entry) => Boolean(entry)).slice(0, headingPathDepth),
         text: `${line}
 `
@@ -1071,8 +1447,8 @@ function parseHeadingSections(markdown, headingPathDepth) {
   }
   return sections;
 }
-function blockify(text, config) {
-  const lines = text.split("\n");
+function blockify(text2, config) {
+  const lines = text2.split("\n");
   const blocks = [];
   let inFence = false;
   let current = [];
@@ -1179,20 +1555,21 @@ function splitOversizedBlock(block, config) {
   return chunks.length > 0 ? chunks : [trimmed];
 }
 function splitSection(section, config) {
-  const text = section.text.trim();
-  if (!text) {
+  const text2 = section.text.trim();
+  if (!text2) {
     return [];
   }
-  if (text.length <= config.maxChars) {
+  if (text2.length <= config.maxChars) {
     return [
       {
         sectionTitle: section.sectionTitle,
+        headingLevel: section.headingLevel,
         headingPath: section.headingPath,
-        chunkText: text
+        chunkText: text2
       }
     ];
   }
-  const blocks = blockify(text, config);
+  const blocks = blockify(text2, config);
   const chunks = [];
   let current = "";
   for (const block of blocks) {
@@ -1237,6 +1614,7 @@ ${chunk}`;
   }
   return merged.map((chunkText) => ({
     sectionTitle: section.sectionTitle,
+    headingLevel: section.headingLevel,
     headingPath: section.headingPath,
     chunkText
   }));
@@ -1252,6 +1630,18 @@ function buildSummaryChunkText(page) {
   }
   return parts.join("\n\n");
 }
+function buildEmbeddingTitle(chunk) {
+  if (!chunk.sectionTitle || chunk.headingLevel === void 0) return void 0;
+  if (chunk.headingPath.length > 1) {
+    const path16 = chunk.headingPath.join(" > ");
+    const lastInPath = chunk.headingPath[chunk.headingPath.length - 1];
+    if (lastInPath !== chunk.sectionTitle) {
+      return `${chunk.title} \u2014 ${path16} > ${chunk.sectionTitle}`;
+    }
+    return `${chunk.title} \u2014 ${path16}`;
+  }
+  return `${chunk.title} \u2014 ${chunk.sectionTitle}`;
+}
 function buildEmbeddingText(chunk, prependTitle) {
   if (!prependTitle) return chunk.chunkText;
   const prefix = chunk.sectionTitle ? `${chunk.title} \u2014 ${chunk.sectionTitle}` : chunk.title;
@@ -1282,10 +1672,14 @@ function chunkPage(page, config, scope) {
       tags: page.tags,
       contentHash: "",
       description: page.description,
-      keywords: page.keywords
+      keywords: page.keywords,
+      publishedAt: page.publishedAt,
+      incomingAnchorText: page.incomingAnchorText,
+      meta: page.meta
     };
     const embeddingText = buildEmbeddingText(summaryChunk, config.chunking.prependTitle);
-    summaryChunk.contentHash = sha256(normalizeText(embeddingText));
+    const metaSuffix = page.meta ? JSON.stringify(page.meta, Object.keys(page.meta).sort()) : "";
+    summaryChunk.contentHash = sha256(normalizeText(embeddingText) + metaSuffix);
     chunks.push(summaryChunk);
   }
   const ordinalOffset = config.chunking.pageSummaryChunk ? 1 : 0;
@@ -1302,6 +1696,7 @@ function chunkPage(page, config, scope) {
       path: page.url,
       title: page.title,
       sectionTitle: entry.sectionTitle,
+      headingLevel: entry.headingLevel,
       headingPath: entry.headingPath,
       chunkText: entry.chunkText,
       snippet: toSnippet(entry.chunkText),
@@ -1311,10 +1706,16 @@ function chunkPage(page, config, scope) {
       tags: page.tags,
       contentHash: "",
       description: page.description,
-      keywords: page.keywords
+      keywords: page.keywords,
+      publishedAt: page.publishedAt,
+      incomingAnchorText: page.incomingAnchorText,
+      meta: page.meta
     };
     const embeddingText = buildEmbeddingText(chunk, config.chunking.prependTitle);
-    chunk.contentHash = sha256(normalizeText(embeddingText));
+    const embeddingTitle = config.chunking.weightHeadings ? buildEmbeddingTitle(chunk) : void 0;
+    const chunkMetaSuffix = page.meta ? JSON.stringify(page.meta, Object.keys(page.meta).sort()) : "";
+    const hashInput = embeddingTitle ? `${normalizeText(embeddingText)}|title:${embeddingTitle}` : normalizeText(embeddingText);
+    chunk.contentHash = sha256(hashInput + chunkMetaSuffix);
     chunks.push(chunk);
   }
   return chunks;
@@ -1325,6 +1726,113 @@ import { load } from "cheerio";
 import matter from "gray-matter";
 import TurndownService from "turndown";
 import { gfm, highlightedCodeBlock, strikethrough, tables, taskListItems } from "turndown-plugin-gfm";
+
+// src/utils/structured-meta.ts
+var VALID_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function validateMetaKey(key) {
+  return VALID_KEY_RE.test(key);
+}
+function parseMetaValue(content, dataType) {
+  switch (dataType) {
+    case "number": {
+      const n = Number(content);
+      return Number.isFinite(n) ? n : content;
+    }
+    case "boolean":
+      return content === "true";
+    case "string[]":
+      return content ? content.split(",").map((s) => s.trim()) : [];
+    case "date": {
+      const ms = Number(content);
+      return Number.isFinite(ms) ? ms : content;
+    }
+    default:
+      return content;
+  }
+}
+function escapeFilterValue(s) {
+  return s.replace(/'/g, "''");
+}
+function buildMetaFilterString(filters) {
+  const clauses = [];
+  for (const [key, value] of Object.entries(filters)) {
+    if (!validateMetaKey(key)) continue;
+    const field = `meta.${key}`;
+    if (typeof value === "string") {
+      clauses.push(`${field} CONTAINS '${escapeFilterValue(value)}'`);
+    } else if (typeof value === "boolean") {
+      clauses.push(`${field} = ${value}`);
+    } else {
+      clauses.push(`${field} = ${value}`);
+    }
+  }
+  return clauses.join(" AND ");
+}
+
+// src/indexing/extractor.ts
+function normalizeDateToMs(value) {
+  if (value == null) return void 0;
+  if (value instanceof Date) {
+    const ts = value.getTime();
+    return Number.isFinite(ts) ? ts : void 0;
+  }
+  if (typeof value === "string") {
+    const ts = new Date(value).getTime();
+    return Number.isFinite(ts) ? ts : void 0;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : void 0;
+  }
+  return void 0;
+}
+var FRONTMATTER_DATE_FIELDS = ["date", "publishedAt", "updatedAt", "published_at", "updated_at"];
+function extractPublishedAtFromFrontmatter(data) {
+  for (const field of FRONTMATTER_DATE_FIELDS) {
+    const val = normalizeDateToMs(data[field]);
+    if (val !== void 0) return val;
+  }
+  return void 0;
+}
+function extractPublishedAtFromHtml($) {
+  const jsonLdScripts = $('script[type="application/ld+json"]');
+  for (let i = 0; i < jsonLdScripts.length; i++) {
+    try {
+      const raw = $(jsonLdScripts[i]).html();
+      if (!raw) continue;
+      const parsed = JSON.parse(raw);
+      const candidates = [];
+      if (Array.isArray(parsed)) {
+        candidates.push(...parsed);
+      } else if (parsed && typeof parsed === "object") {
+        candidates.push(parsed);
+        if (Array.isArray(parsed["@graph"])) {
+          candidates.push(...parsed["@graph"]);
+        }
+      }
+      for (const candidate of candidates) {
+        const val = normalizeDateToMs(candidate.datePublished);
+        if (val !== void 0) return val;
+      }
+    } catch {
+    }
+  }
+  const ogTime = $('meta[property="article:published_time"]').attr("content")?.trim();
+  if (ogTime) {
+    const val = normalizeDateToMs(ogTime);
+    if (val !== void 0) return val;
+  }
+  const itempropDate = $('meta[itemprop="datePublished"]').attr("content")?.trim() || $('time[itemprop="datePublished"]').attr("datetime")?.trim();
+  if (itempropDate) {
+    const val = normalizeDateToMs(itempropDate);
+    if (val !== void 0) return val;
+  }
+  const timeEl = $("time[datetime]").first().attr("datetime")?.trim();
+  if (timeEl) {
+    const val = normalizeDateToMs(timeEl);
+    if (val !== void 0) return val;
+  }
+  return void 0;
+}
 function hasTopLevelNoindexComment(markdown) {
   const lines = markdown.split(/\r?\n/);
   let inFence = false;
@@ -1340,6 +1848,97 @@ function hasTopLevelNoindexComment(markdown) {
   }
   return false;
 }
+var GARBAGE_ALT_WORDS = /* @__PURE__ */ new Set([
+  "image",
+  "photo",
+  "picture",
+  "icon",
+  "logo",
+  "banner",
+  "screenshot",
+  "thumbnail",
+  "img",
+  "graphic",
+  "illustration",
+  "spacer",
+  "pixel",
+  "placeholder",
+  "avatar",
+  "background"
+]);
+var IMAGE_EXT_RE = /\.(jpg|jpeg|png|gif|svg|webp|avif|bmp|ico)(\?.*)?$/i;
+function isMeaningfulAlt(alt) {
+  const trimmed = alt.trim();
+  if (!trimmed || trimmed.length < 5) return false;
+  if (IMAGE_EXT_RE.test(trimmed)) return false;
+  if (GARBAGE_ALT_WORDS.has(trimmed.toLowerCase())) return false;
+  return true;
+}
+function resolveImageText(img, $, imageDescAttr) {
+  const imgDesc = img.attr(imageDescAttr)?.trim();
+  if (imgDesc) return imgDesc;
+  const figure = img.closest("figure");
+  if (figure.length) {
+    const figDesc = figure.attr(imageDescAttr)?.trim();
+    if (figDesc) return figDesc;
+  }
+  const alt = img.attr("alt")?.trim() ?? "";
+  const caption = figure.length ? figure.find("figcaption").first().text().trim() : "";
+  if (isMeaningfulAlt(alt) && caption) {
+    return `${alt} \u2014 ${caption}`;
+  }
+  if (isMeaningfulAlt(alt)) {
+    return alt;
+  }
+  if (caption) {
+    return caption;
+  }
+  return null;
+}
+var STOP_ANCHORS = /* @__PURE__ */ new Set([
+  "here",
+  "click",
+  "click here",
+  "read more",
+  "link",
+  "this",
+  "more"
+]);
+function normalizeAnchorText(raw) {
+  const normalized = raw.replace(/\s+/g, " ").trim().toLowerCase();
+  if (normalized.length < 3) return "";
+  if (STOP_ANCHORS.has(normalized)) return "";
+  if (normalized.length > 100) return normalized.slice(0, 100);
+  return normalized;
+}
+function escapeHtml(text2) {
+  return text2.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function preprocessImages(root, $, imageDescAttr) {
+  root.find("picture").each((_i, el) => {
+    const picture = $(el);
+    const img = picture.find("img").first();
+    const parentFigure = picture.closest("figure");
+    const text2 = img.length ? resolveImageText(img, $, imageDescAttr) : null;
+    if (text2) {
+      if (parentFigure.length) parentFigure.find("figcaption").remove();
+      picture.replaceWith(`<span>${escapeHtml(text2)}</span>`);
+    } else {
+      picture.remove();
+    }
+  });
+  root.find("img").each((_i, el) => {
+    const img = $(el);
+    const parentFigure = img.closest("figure");
+    const text2 = resolveImageText(img, $, imageDescAttr);
+    if (text2) {
+      if (parentFigure.length) parentFigure.find("figcaption").remove();
+      img.replaceWith(`<span>${escapeHtml(text2)}</span>`);
+    } else {
+      img.remove();
+    }
+  });
+}
 function extractFromHtml(url, html, config) {
   const $ = load(html);
   const normalizedUrl = normalizeUrlPath(url);
@@ -1365,6 +1964,20 @@ function extractFromHtml(url, html, config) {
   if (weight === 0) {
     return null;
   }
+  if ($('meta[name="searchsocket:noindex"]').attr("content") === "true") {
+    return null;
+  }
+  const RESERVED_META_KEYS = /* @__PURE__ */ new Set(["noindex", "tags"]);
+  const meta = {};
+  $('meta[name^="searchsocket:"]').each((_i, el) => {
+    const name = $(el).attr("name") ?? "";
+    const key = name.slice("searchsocket:".length);
+    if (!key || RESERVED_META_KEYS.has(key) || !validateMetaKey(key)) return;
+    const content = $(el).attr("content") ?? "";
+    const dataType = $(el).attr("data-type") ?? "string";
+    meta[key] = parseMetaValue(content, dataType);
+  });
+  const componentTags = $('meta[name="searchsocket:tags"]').attr("content")?.trim();
   const description = $("meta[name='description']").attr("content")?.trim() || $("meta[property='og:description']").attr("content")?.trim() || void 0;
   const keywordsRaw = $("meta[name='keywords']").attr("content")?.trim();
   const keywords = keywordsRaw ? keywordsRaw.split(",").map((k) => k.trim()).filter(Boolean) : void 0;
@@ -1376,7 +1989,9 @@ function extractFromHtml(url, html, config) {
     root.find(selector).remove();
   }
   root.find(`[${config.extract.ignoreAttr}]`).remove();
+  preprocessImages(root, $, config.extract.imageDescAttr);
   const outgoingLinks = [];
+  const seenLinkKeys = /* @__PURE__ */ new Set();
   root.find("a[href]").each((_index, node) => {
     const href = $(node).attr("href");
     if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) {
@@ -1387,7 +2002,19 @@ function extractFromHtml(url, html, config) {
       if (!["http:", "https:"].includes(parsed.protocol)) {
         return;
       }
-      outgoingLinks.push(normalizeUrlPath(parsed.pathname));
+      const url2 = normalizeUrlPath(parsed.pathname);
+      let anchorText = normalizeAnchorText($(node).text());
+      if (!anchorText) {
+        const imgAlt = $(node).find("img").first().attr("alt") ?? "";
+        if (isMeaningfulAlt(imgAlt)) {
+          anchorText = normalizeAnchorText(imgAlt);
+        }
+      }
+      const key = `${url2}|${anchorText}`;
+      if (!seenLinkKeys.has(key)) {
+        seenLinkKeys.add(key);
+        outgoingLinks.push({ url: url2, anchorText });
+      }
     } catch {
     }
   });
@@ -1412,16 +2039,25 @@ function extractFromHtml(url, html, config) {
     return null;
   }
   const tags = normalizeUrlPath(url).split("/").filter(Boolean).slice(0, 1);
+  const publishedAt = extractPublishedAtFromHtml($);
+  if (componentTags) {
+    const extraTags = componentTags.split(",").map((t) => t.trim()).filter(Boolean);
+    for (const t of extraTags) {
+      if (!tags.includes(t)) tags.push(t);
+    }
+  }
   return {
     url: normalizeUrlPath(url),
     title,
     markdown,
-    outgoingLinks: [...new Set(outgoingLinks)],
+    outgoingLinks,
     noindex: false,
     tags,
     description,
     keywords,
-    weight
+    weight,
+    publishedAt,
+    meta: Object.keys(meta).length > 0 ? meta : void 0
   };
 }
 function extractFromMarkdown(url, markdown, title) {
@@ -1442,6 +2078,24 @@ function extractFromMarkdown(url, markdown, title) {
   if (mdWeight === 0) {
     return null;
   }
+  let mdMeta;
+  const rawMeta = searchsocketMeta?.meta;
+  if (rawMeta && typeof rawMeta === "object" && !Array.isArray(rawMeta)) {
+    const metaObj = {};
+    for (const [key, val] of Object.entries(rawMeta)) {
+      if (!validateMetaKey(key)) continue;
+      if (typeof val === "string" || typeof val === "number" || typeof val === "boolean") {
+        metaObj[key] = val;
+      } else if (Array.isArray(val) && val.every((v) => typeof v === "string")) {
+        metaObj[key] = val;
+      } else if (val instanceof Date) {
+        metaObj[key] = val.getTime();
+      }
+    }
+    if (Object.keys(metaObj).length > 0) {
+      mdMeta = metaObj;
+    }
+  }
   const content = parsed.content;
   const normalized = normalizeMarkdown(content);
   if (!normalizeText(normalized)) {
@@ -1456,6 +2110,7 @@ function extractFromMarkdown(url, markdown, title) {
     fmKeywords = frontmatter.keywords.split(",").map((k) => k.trim()).filter(Boolean);
   }
   if (fmKeywords && fmKeywords.length === 0) fmKeywords = void 0;
+  const publishedAt = extractPublishedAtFromFrontmatter(frontmatter);
   return {
     url: normalizeUrlPath(url),
     title: resolvedTitle,
@@ -1465,7 +2120,9 @@ function extractFromMarkdown(url, markdown, title) {
     tags: normalizeUrlPath(url).split("/").filter(Boolean).slice(0, 1),
     description: fmDescription,
     keywords: fmKeywords,
-    weight: mdWeight
+    weight: mdWeight,
+    publishedAt,
+    meta: mdMeta
   };
 }
 
@@ -1919,6 +2576,125 @@ function filePathToUrl(filePath, baseDir) {
   const noExt = relative.replace(/\.md$/i, "").replace(/\/index$/i, "");
   return normalizeUrlPath(noExt || "/");
 }
+var ROUTE_FILE_RE = /\+(page|layout|error)(@[^.]+)?\.svelte$/;
+function isSvelteComponentFile(filePath) {
+  if (!filePath.endsWith(".svelte")) return false;
+  return !ROUTE_FILE_RE.test(filePath);
+}
+function extractSvelteComponentMeta(source) {
+  const componentMatch = source.match(/<!--\s*@component\s*([\s\S]*?)\s*-->/);
+  const description = componentMatch?.[1]?.trim() || void 0;
+  const propsMatch = source.match(
+    /let\s+\{([\s\S]*?)\}\s*(?::\s*([^=;{][\s\S]*?))?\s*=\s*\$props\(\)/
+  );
+  const props = [];
+  if (propsMatch) {
+    const destructureBlock = propsMatch[1];
+    const typeAnnotation = propsMatch[2]?.trim();
+    let resolvedTypeMap;
+    if (typeAnnotation && /^[A-Z]\w*$/.test(typeAnnotation)) {
+      resolvedTypeMap = resolveTypeReference(source, typeAnnotation);
+    } else if (typeAnnotation && typeAnnotation.startsWith("{")) {
+      resolvedTypeMap = parseInlineTypeAnnotation(typeAnnotation);
+    }
+    const propEntries = splitDestructureBlock(destructureBlock);
+    for (const entry of propEntries) {
+      const trimmed = entry.trim();
+      if (!trimmed || trimmed.startsWith("...")) continue;
+      let propName;
+      let defaultValue;
+      const renameMatch = trimmed.match(/^(\w+)\s*:\s*\w+\s*(?:=\s*([\s\S]+))?$/);
+      if (renameMatch) {
+        propName = renameMatch[1];
+        defaultValue = renameMatch[2]?.trim();
+      } else {
+        const defaultMatch = trimmed.match(/^(\w+)\s*=\s*([\s\S]+)$/);
+        if (defaultMatch) {
+          propName = defaultMatch[1];
+          defaultValue = defaultMatch[2]?.trim();
+        } else {
+          propName = trimmed.match(/^(\w+)/)?.[1] ?? trimmed;
+        }
+      }
+      const propType = resolvedTypeMap?.get(propName);
+      props.push({
+        name: propName,
+        ...propType ? { type: propType } : {},
+        ...defaultValue ? { default: defaultValue } : {}
+      });
+    }
+  }
+  return { description, props };
+}
+function splitDestructureBlock(block) {
+  const entries = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of block) {
+    if (ch === "{" || ch === "[" || ch === "(") {
+      depth++;
+      current += ch;
+    } else if (ch === "}" || ch === "]" || ch === ")") {
+      depth--;
+      current += ch;
+    } else if (ch === "," && depth === 0) {
+      entries.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim()) entries.push(current);
+  return entries;
+}
+function resolveTypeReference(source, typeName) {
+  const startRe = new RegExp(`(?:interface\\s+${typeName}\\s*|type\\s+${typeName}\\s*=\\s*)\\{`);
+  const startMatch = source.match(startRe);
+  if (!startMatch || startMatch.index === void 0) return void 0;
+  const bodyStart = startMatch.index + startMatch[0].length;
+  let depth = 1;
+  let i = bodyStart;
+  while (i < source.length && depth > 0) {
+    if (source[i] === "{") depth++;
+    else if (source[i] === "}") depth--;
+    i++;
+  }
+  if (depth !== 0) return void 0;
+  const body = source.slice(bodyStart, i - 1);
+  return parseTypeMembers(body);
+}
+function parseInlineTypeAnnotation(annotation) {
+  const inner = annotation.replace(/^\{/, "").replace(/\}$/, "");
+  return parseTypeMembers(inner);
+}
+function parseTypeMembers(body) {
+  const map = /* @__PURE__ */ new Map();
+  const members = body.split(/[;\n]/).map((m) => m.trim()).filter(Boolean);
+  for (const member of members) {
+    const memberMatch = member.match(/^(\w+)\??\s*:\s*(.+)$/);
+    if (memberMatch) {
+      map.set(memberMatch[1], memberMatch[2].replace(/,\s*$/, "").trim());
+    }
+  }
+  return map;
+}
+function buildComponentMarkdown(componentName, meta) {
+  if (!meta.description && meta.props.length === 0) return "";
+  const parts = [`${componentName} component.`];
+  if (meta.description) {
+    parts.push(meta.description);
+  }
+  if (meta.props.length > 0) {
+    const propEntries = meta.props.map((p) => {
+      let entry = p.name;
+      if (p.type) entry += ` (${p.type})`;
+      if (p.default) entry += ` default: ${p.default}`;
+      return entry;
+    });
+    parts.push(`Props: ${propEntries.join(", ")}.`);
+  }
+  return parts.join(" ");
+}
 function normalizeSvelteToMarkdown(source) {
   return source.replace(/<script[\s\S]*?<\/script>/g, "").replace(/<style[\s\S]*?<\/style>/g, "").replace(/<[^>]+>/g, " ").replace(/\{[^}]+\}/g, " ").replace(/\s+/g, " ").trim();
 }
@@ -1938,12 +2714,26 @@ async function loadContentFilesPages(cwd, config, maxPages) {
   const pages = [];
   for (const filePath of selected) {
     const raw = await fs5.readFile(filePath, "utf8");
-    const markdown = filePath.endsWith(".md") ? raw : normalizeSvelteToMarkdown(raw);
+    let markdown;
+    let tags;
+    if (filePath.endsWith(".md")) {
+      markdown = raw;
+    } else if (isSvelteComponentFile(filePath)) {
+      const componentName = path7.basename(filePath, ".svelte");
+      const meta = extractSvelteComponentMeta(raw);
+      const componentMarkdown = buildComponentMarkdown(componentName, meta);
+      const templateContent = normalizeSvelteToMarkdown(raw);
+      markdown = componentMarkdown ? [componentMarkdown, templateContent].filter(Boolean).join("\n\n") : templateContent;
+      tags = ["component"];
+    } else {
+      markdown = normalizeSvelteToMarkdown(raw);
+    }
     pages.push({
       url: filePathToUrl(filePath, baseDir),
       markdown,
       sourcePath: path7.relative(cwd, filePath).replace(/\\/g, "/"),
-      outgoingLinks: []
+      outgoingLinks: [],
+      ...tags ? { tags } : {}
     });
   }
   return pages;
@@ -1958,9 +2748,9 @@ function extractLocs(xml) {
   const $ = cheerioLoad2(xml, { xmlMode: true });
   const locs = [];
   $("loc").each((_i, el) => {
-    const text = $(el).text().trim();
-    if (text) {
-      locs.push(text);
+    const text2 = $(el).text().trim();
+    if (text2) {
+      locs.push(text2);
     }
   });
   return locs;
@@ -2175,32 +2965,68 @@ function nonNegativeOrZero(value) {
   }
   return Math.max(0, value);
 }
-function normalizeForTitleMatch(text) {
-  return text.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, " ").trim();
+function normalizeForTitleMatch(text2) {
+  return text2.toLowerCase().replace(/[^a-z0-9\s]/g, "").replace(/\s+/g, " ").trim();
 }
-function rankHits(hits, config, query) {
+function rankHits(hits, config, query, debug) {
   const normalizedQuery = query ? normalizeForTitleMatch(query) : "";
   const titleMatchWeight = config.ranking.weights.titleMatch;
   return hits.map((hit) => {
-    let score = Number.isFinite(hit.score) ? hit.score : Number.NEGATIVE_INFINITY;
+    const baseScore = Number.isFinite(hit.score) ? hit.score : Number.NEGATIVE_INFINITY;
+    let score = baseScore;
+    let incomingLinkBoostValue = 0;
     if (config.ranking.enableIncomingLinkBoost) {
       const incomingBoost = Math.log(1 + nonNegativeOrZero(hit.metadata.incomingLinks));
-      score += incomingBoost * config.ranking.weights.incomingLinks;
+      incomingLinkBoostValue = incomingBoost * config.ranking.weights.incomingLinks;
+      score += incomingLinkBoostValue;
     }
+    let depthBoostValue = 0;
     if (config.ranking.enableDepthBoost) {
       const depthBoost = 1 / (1 + nonNegativeOrZero(hit.metadata.depth));
-      score += depthBoost * config.ranking.weights.depth;
+      depthBoostValue = depthBoost * config.ranking.weights.depth;
+      score += depthBoostValue;
     }
+    let titleMatchBoostValue = 0;
     if (normalizedQuery && titleMatchWeight > 0) {
       const normalizedTitle = normalizeForTitleMatch(hit.metadata.title);
       if (normalizedQuery.length > 0 && normalizedTitle.length > 0 && (normalizedTitle.includes(normalizedQuery) || normalizedQuery.includes(normalizedTitle))) {
-        score += titleMatchWeight;
+        titleMatchBoostValue = titleMatchWeight;
+        score += titleMatchBoostValue;
       }
     }
-    return {
+    let freshnessBoostValue = 0;
+    if (config.ranking.enableFreshnessBoost) {
+      const publishedAt = hit.metadata.publishedAt;
+      if (typeof publishedAt === "number" && Number.isFinite(publishedAt)) {
+        const daysSince = Math.max(0, (Date.now() - publishedAt) / 864e5);
+        const decay = 1 / (1 + nonNegativeOrZero(daysSince) * config.ranking.freshnessDecayRate);
+        freshnessBoostValue = decay * config.ranking.weights.freshness;
+        score += freshnessBoostValue;
+      }
+    }
+    let anchorTextMatchBoostValue = 0;
+    if (config.ranking.enableAnchorTextBoost && normalizedQuery && config.ranking.weights.anchorText > 0) {
+      const normalizedAnchorText = normalizeForTitleMatch(hit.metadata.incomingAnchorText ?? "");
+      if (normalizedAnchorText.length > 0 && normalizedQuery.length > 0 && (normalizedAnchorText.includes(normalizedQuery) || normalizedQuery.includes(normalizedAnchorText))) {
+        anchorTextMatchBoostValue = config.ranking.weights.anchorText;
+        score += anchorTextMatchBoostValue;
+      }
+    }
+    const result = {
       hit,
       finalScore: Number.isFinite(score) ? score : Number.NEGATIVE_INFINITY
     };
+    if (debug) {
+      result.breakdown = {
+        baseScore,
+        incomingLinkBoost: incomingLinkBoostValue,
+        depthBoost: depthBoostValue,
+        titleMatchBoost: titleMatchBoostValue,
+        freshnessBoost: freshnessBoostValue,
+        anchorTextMatchBoost: anchorTextMatchBoostValue
+      };
+    }
+    return result;
   }).sort((a, b) => {
     const delta = b.finalScore - a.finalScore;
     return Number.isNaN(delta) ? 0 : delta;
@@ -2209,12 +3035,13 @@ function rankHits(hits, config, query) {
 function trimByScoreGap(results, config) {
   if (results.length === 0) return results;
   const threshold = config.ranking.scoreGapThreshold;
-  const minScore = config.ranking.minScore;
-  if (minScore > 0 && results.length > 0) {
-    const sortedScores = results.map((r) => r.pageScore).sort((a, b) => a - b);
-    const mid = Math.floor(sortedScores.length / 2);
-    const median = sortedScores.length % 2 === 0 ? (sortedScores[mid - 1] + sortedScores[mid]) / 2 : sortedScores[mid];
-    if (median < minScore) return [];
+  const minScoreRatio = config.ranking.minScoreRatio;
+  if (minScoreRatio > 0 && results.length > 0) {
+    const topScore = results[0].pageScore;
+    if (Number.isFinite(topScore) && topScore > 0) {
+      const minThreshold = topScore * minScoreRatio;
+      results = results.filter((r) => r.pageScore >= minThreshold);
+    }
   }
   if (threshold > 0 && results.length > 1) {
     for (let i = 1; i < results.length; i++) {
@@ -2284,61 +3111,99 @@ function aggregateByPage(ranked, config) {
     return Number.isNaN(delta) ? 0 : delta;
   });
 }
-function mergePageAndChunkResults(pageHits, rankedChunks, config) {
-  if (pageHits.length === 0) return rankedChunks;
-  const w = config.search.pageSearchWeight;
-  const pageScoreMap = /* @__PURE__ */ new Map();
-  for (const ph of pageHits) {
-    pageScoreMap.set(ph.url, ph);
-  }
-  const pagesWithChunks = /* @__PURE__ */ new Set();
-  const merged = rankedChunks.map((ranked) => {
-    const url = ranked.hit.metadata.url;
-    const pageHit = pageScoreMap.get(url);
-    if (pageHit) {
-      pagesWithChunks.add(url);
-      const blended = (1 - w) * ranked.finalScore + w * pageHit.score;
-      return {
-        hit: ranked.hit,
-        finalScore: Number.isFinite(blended) ? blended : ranked.finalScore
-      };
+function rankPageHits(pageHits, config, query, debug) {
+  const normalizedQuery = query ? normalizeForTitleMatch(query) : "";
+  const titleMatchWeight = config.ranking.weights.titleMatch;
+  return pageHits.map((hit) => {
+    const baseScore = Number.isFinite(hit.score) ? hit.score : Number.NEGATIVE_INFINITY;
+    let score = baseScore;
+    let incomingLinkBoostValue = 0;
+    if (config.ranking.enableIncomingLinkBoost) {
+      const incomingBoost = Math.log(1 + nonNegativeOrZero(hit.incomingLinks));
+      incomingLinkBoostValue = incomingBoost * config.ranking.weights.incomingLinks;
+      score += incomingLinkBoostValue;
     }
-    return ranked;
-  });
-  for (const [url, pageHit] of pageScoreMap) {
-    if (pagesWithChunks.has(url)) continue;
-    const syntheticScore = pageHit.score * w;
-    const syntheticHit = {
-      id: `page:${url}`,
-      score: pageHit.score,
-      metadata: {
-        projectId: "",
-        scopeName: "",
-        url: pageHit.url,
-        path: pageHit.url,
-        title: pageHit.title,
-        sectionTitle: "",
-        headingPath: [],
-        snippet: pageHit.description || pageHit.title,
-        chunkText: pageHit.description || pageHit.title,
-        ordinal: 0,
-        contentHash: "",
-        depth: pageHit.depth,
-        incomingLinks: pageHit.incomingLinks,
-        routeFile: pageHit.routeFile,
-        tags: pageHit.tags
+    let depthBoostValue = 0;
+    if (config.ranking.enableDepthBoost) {
+      const depthBoost = 1 / (1 + nonNegativeOrZero(hit.depth));
+      depthBoostValue = depthBoost * config.ranking.weights.depth;
+      score += depthBoostValue;
+    }
+    let titleMatchBoostValue = 0;
+    if (normalizedQuery && titleMatchWeight > 0) {
+      const normalizedTitle = normalizeForTitleMatch(hit.title);
+      if (normalizedQuery.length > 0 && normalizedTitle.length > 0 && (normalizedTitle.includes(normalizedQuery) || normalizedQuery.includes(normalizedTitle))) {
+        titleMatchBoostValue = titleMatchWeight;
+        score += titleMatchBoostValue;
       }
-    };
-    merged.push({
-      hit: syntheticHit,
-      finalScore: Number.isFinite(syntheticScore) ? syntheticScore : 0
-    });
-  }
-  return merged.sort((a, b) => {
+    }
+    let freshnessBoostValue = 0;
+    if (config.ranking.enableFreshnessBoost) {
+      const publishedAt = hit.publishedAt;
+      if (typeof publishedAt === "number" && Number.isFinite(publishedAt)) {
+        const daysSince = Math.max(0, (Date.now() - publishedAt) / 864e5);
+        const decay = 1 / (1 + nonNegativeOrZero(daysSince) * config.ranking.freshnessDecayRate);
+        freshnessBoostValue = decay * config.ranking.weights.freshness;
+        score += freshnessBoostValue;
+      }
+    }
+    const pageWeight = findPageWeight(hit.url, config.ranking.pageWeights);
+    if (pageWeight !== 1) {
+      score *= pageWeight;
+    }
+    const result = {
+      url: hit.url,
+      title: hit.title,
+      description: hit.description,
+      routeFile: hit.routeFile,
+      depth: hit.depth,
+      incomingLinks: hit.incomingLinks,
+      tags: hit.tags,
+      baseScore,
+      finalScore: Number.isFinite(score) ? score : Number.NEGATIVE_INFINITY,
+      publishedAt: hit.publishedAt
+    };
+    if (debug) {
+      result.breakdown = {
+        baseScore,
+        pageWeight,
+        incomingLinkBoost: incomingLinkBoostValue,
+        depthBoost: depthBoostValue,
+        titleMatchBoost: titleMatchBoostValue,
+        freshnessBoost: freshnessBoostValue
+      };
+    }
+    return result;
+  }).filter((p) => findPageWeight(p.url, config.ranking.pageWeights) !== 0).sort((a, b) => {
     const delta = b.finalScore - a.finalScore;
     return Number.isNaN(delta) ? 0 : delta;
   });
 }
+function trimPagesByScoreGap(results, config) {
+  if (results.length === 0) return results;
+  const threshold = config.ranking.scoreGapThreshold;
+  const minScoreRatio = config.ranking.minScoreRatio;
+  if (minScoreRatio > 0 && results.length > 0) {
+    const topScore = results[0].finalScore;
+    if (Number.isFinite(topScore) && topScore > 0) {
+      const minThreshold = topScore * minScoreRatio;
+      results = results.filter((r) => r.finalScore >= minThreshold);
+    }
+  }
+  if (threshold > 0 && results.length > 1) {
+    for (let i = 1; i < results.length; i++) {
+      const prev = results[i - 1].finalScore;
+      const current = results[i].finalScore;
+      if (prev > 0) {
+        const gap = (prev - current) / prev;
+        if (gap >= threshold) {
+          return results.slice(0, i);
+        }
+      }
+    }
+  }
+  return results;
+}
 
 // src/utils/time.ts
 function nowIso() {
@@ -2348,6 +3213,85 @@ function hrTimeMs(start) {
   return Number(process.hrtime.bigint() - start) / 1e6;
 }
 
+// src/indexing/llms-txt.ts
+import fs8 from "fs/promises";
+import path10 from "path";
+function resolvePageUrl(pageUrl, baseUrl) {
+  if (!baseUrl) return pageUrl;
+  try {
+    return new URL(pageUrl, baseUrl).href;
+  } catch {
+    return pageUrl;
+  }
+}
+function generateLlmsTxt(pages, config) {
+  const title = config.llmsTxt.title ?? config.project.id;
+  const description = config.llmsTxt.description;
+  const baseUrl = config.project.baseUrl;
+  const lines = [`# ${title}`];
+  if (description) {
+    lines.push("", `> ${description}`);
+  }
+  const filtered = pages.filter(
+    (p) => p.url !== "/llms.txt" && p.url !== "/llms-full.txt"
+  );
+  const sorted = [...filtered].sort((a, b) => {
+    if (a.depth !== b.depth) return a.depth - b.depth;
+    return b.incomingLinks - a.incomingLinks;
+  });
+  if (sorted.length > 0) {
+    lines.push("", "## Pages", "");
+    for (const page of sorted) {
+      const url = resolvePageUrl(page.url, baseUrl);
+      if (page.description) {
+        lines.push(`- [${page.title}](${url}): ${page.description}`);
+      } else {
+        lines.push(`- [${page.title}](${url})`);
+      }
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function generateLlmsFullTxt(pages, config) {
+  const title = config.llmsTxt.title ?? config.project.id;
+  const description = config.llmsTxt.description;
+  const baseUrl = config.project.baseUrl;
+  const lines = [`# ${title}`];
+  if (description) {
+    lines.push("", `> ${description}`);
+  }
+  const filtered = pages.filter(
+    (p) => p.url !== "/llms.txt" && p.url !== "/llms-full.txt"
+  );
+  const sorted = [...filtered].sort((a, b) => {
+    if (a.depth !== b.depth) return a.depth - b.depth;
+    return b.incomingLinks - a.incomingLinks;
+  });
+  for (const page of sorted) {
+    const url = resolvePageUrl(page.url, baseUrl);
+    lines.push("", "---", "", `## [${page.title}](${url})`, "");
+    lines.push(page.markdown.trim());
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+async function writeLlmsTxt(pages, config, cwd, logger3) {
+  const outputPath = path10.resolve(cwd, config.llmsTxt.outputPath);
+  const outputDir = path10.dirname(outputPath);
+  await fs8.mkdir(outputDir, { recursive: true });
+  const content = generateLlmsTxt(pages, config);
+  await fs8.writeFile(outputPath, content, "utf8");
+  logger3.info(`Generated llms.txt at ${config.llmsTxt.outputPath}`);
+  if (config.llmsTxt.generateFull) {
+    const fullPath = outputPath.replace(/\.txt$/, "-full.txt");
+    const fullContent = generateLlmsFullTxt(pages, config);
+    await fs8.writeFile(fullPath, fullContent, "utf8");
+    const relativeFull = path10.relative(cwd, fullPath);
+    logger3.info(`Generated llms-full.txt at ${relativeFull}`);
+  }
+}
+
 // src/indexing/pipeline.ts
 function buildPageSummary(page, maxChars = 3500) {
   const parts = [page.title];
@@ -2365,26 +3309,44 @@ function buildPageSummary(page, maxChars = 3500) {
   if (joined.length <= maxChars) return joined;
   return joined.slice(0, maxChars).trim();
 }
+function buildPageContentHash(page) {
+  const parts = [
+    page.title,
+    page.description ?? "",
+    (page.keywords ?? []).slice().sort().join(","),
+    page.tags.slice().sort().join(","),
+    page.markdown,
+    String(page.outgoingLinks),
+    String(page.publishedAt ?? ""),
+    page.incomingAnchorText ?? "",
+    (page.outgoingLinkUrls ?? []).slice().sort().join(","),
+    page.meta ? JSON.stringify(page.meta, Object.keys(page.meta).sort()) : ""
+  ];
+  return sha256(parts.join("|"));
+}
 var IndexPipeline = class _IndexPipeline {
   cwd;
   config;
   store;
   logger;
+  hooks;
   constructor(options) {
     this.cwd = options.cwd;
     this.config = options.config;
     this.store = options.store;
     this.logger = options.logger;
+    this.hooks = options.hooks;
   }
   static async create(options = {}) {
-    const cwd = path10.resolve(options.cwd ?? process.cwd());
+    const cwd = path11.resolve(options.cwd ?? process.cwd());
     const config = options.config ?? await loadConfig({ cwd, configPath: options.configPath });
     const store = options.store ?? await createUpstashStore(config);
     return new _IndexPipeline({
       cwd,
       config,
       store,
-      logger: options.logger ?? new Logger()
+      logger: options.logger ?? new Logger(),
+      hooks: options.hooks ?? {}
     });
   }
   getConfig() {
@@ -2405,7 +3367,7 @@ var IndexPipeline = class _IndexPipeline {
     const scope = resolveScope(this.config, options.scopeOverride);
     ensureStateDirs(this.cwd, this.config.state.dir, scope);
     const sourceMode = options.sourceOverride ?? this.config.source.mode;
-    this.logger.info(`Indexing scope "${scope.scopeName}" (source: ${sourceMode}, backend: upstash-search)`);
+    this.logger.info(`Indexing scope "${scope.scopeName}" (source: ${sourceMode}, backend: upstash-vector)`);
     if (options.force) {
       this.logger.info("Force mode enabled \u2014 full rebuild");
     }
@@ -2414,8 +3376,9 @@ var IndexPipeline = class _IndexPipeline {
     }
     const manifestStart = stageStart();
     const existingHashes = options.force ? /* @__PURE__ */ new Map() : await this.store.getContentHashes(scope);
+    const existingPageHashes = options.force ? /* @__PURE__ */ new Map() : await this.store.getPageHashes(scope);
     stageEnd("manifest", manifestStart);
-    this.logger.debug(`Manifest: ${existingHashes.size} existing chunk hashes loaded`);
+    this.logger.debug(`Manifest: ${existingHashes.size} existing chunk hashes, ${existingPageHashes.size} existing page hashes loaded`);
     const sourceStart = stageStart();
     this.logger.info(`Loading pages (source: ${sourceMode})...`);
     let sourcePages;
@@ -2451,11 +3414,11 @@ var IndexPipeline = class _IndexPipeline {
       let robotsRules = null;
       if (sourceMode === "static-output") {
         robotsRules = await loadRobotsTxtFromDir(
-          path10.resolve(this.cwd, this.config.source.staticOutputDir)
+          path11.resolve(this.cwd, this.config.source.staticOutputDir)
         );
       } else if (sourceMode === "build" && this.config.source.build) {
         robotsRules = await loadRobotsTxtFromDir(
-          path10.resolve(this.cwd, this.config.source.build.outputDir)
+          path11.resolve(this.cwd, this.config.source.build.outputDir)
         );
       } else if (sourceMode === "crawl" && this.config.source.crawl) {
         robotsRules = await fetchRobotsTxt(this.config.source.crawl.baseUrl);
@@ -2492,11 +3455,61 @@ var IndexPipeline = class _IndexPipeline {
         );
         continue;
       }
-      extractedPages.push(extracted);
+      if (sourcePage.tags && sourcePage.tags.length > 0) {
+        extracted.tags = [.../* @__PURE__ */ new Set([...extracted.tags, ...sourcePage.tags])];
+      }
+      let accepted;
+      if (this.hooks.transformPage) {
+        const transformed = await this.hooks.transformPage(extracted);
+        if (transformed === null) {
+          this.logger.debug(`Page ${sourcePage.url} skipped by transformPage hook`);
+          continue;
+        }
+        accepted = transformed;
+      } else {
+        accepted = extracted;
+      }
+      extractedPages.push(accepted);
       this.logger.event("page_extracted", {
-        url: extracted.url
+        url: accepted.url
       });
     }
+    const customRecords = options.customRecords ?? [];
+    if (customRecords.length > 0) {
+      this.logger.info(`Processing ${customRecords.length} custom record${customRecords.length === 1 ? "" : "s"}...`);
+      for (const record of customRecords) {
+        const normalizedUrl = normalizeUrlPath(record.url);
+        const normalized = normalizeMarkdown(record.content);
+        if (!normalized.trim()) {
+          this.logger.warn(`Custom record ${normalizedUrl} has empty content and was skipped.`);
+          continue;
+        }
+        const urlTags = normalizedUrl.split("/").filter(Boolean).slice(0, 1);
+        const tags = record.tags ? [.../* @__PURE__ */ new Set([...urlTags, ...record.tags])] : urlTags;
+        const extracted = {
+          url: normalizedUrl,
+          title: record.title,
+          markdown: normalized,
+          outgoingLinks: [],
+          noindex: false,
+          tags,
+          weight: record.weight
+        };
+        let accepted;
+        if (this.hooks.transformPage) {
+          const transformed = await this.hooks.transformPage(extracted);
+          if (transformed === null) {
+            this.logger.debug(`Custom record ${normalizedUrl} skipped by transformPage hook`);
+            continue;
+          }
+          accepted = transformed;
+        } else {
+          accepted = extracted;
+        }
+        extractedPages.push(accepted);
+        this.logger.event("page_extracted", { url: accepted.url, custom: true });
+      }
+    }
     extractedPages.sort((a, b) => a.url.localeCompare(b.url));
     const uniquePages = [];
     const seenUrls = /* @__PURE__ */ new Set();
@@ -2529,15 +3542,28 @@ var IndexPipeline = class _IndexPipeline {
     const linkStart = stageStart();
     const pageSet = new Set(indexablePages.map((page) => normalizeUrlPath(page.url)));
     const incomingLinkCount = /* @__PURE__ */ new Map();
+    const incomingAnchorTexts = /* @__PURE__ */ new Map();
     for (const page of indexablePages) {
       incomingLinkCount.set(page.url, incomingLinkCount.get(page.url) ?? 0);
     }
     for (const page of indexablePages) {
-      for (const outgoing of page.outgoingLinks) {
+      const seenForCount = /* @__PURE__ */ new Set();
+      const seenForAnchor = /* @__PURE__ */ new Set();
+      for (const { url: outgoing, anchorText } of page.outgoingLinks) {
         if (!pageSet.has(outgoing)) {
           continue;
         }
-        incomingLinkCount.set(outgoing, (incomingLinkCount.get(outgoing) ?? 0) + 1);
+        if (!seenForCount.has(outgoing)) {
+          seenForCount.add(outgoing);
+          incomingLinkCount.set(outgoing, (incomingLinkCount.get(outgoing) ?? 0) + 1);
+        }
+        if (anchorText && !seenForAnchor.has(outgoing)) {
+          seenForAnchor.add(outgoing);
+          if (!incomingAnchorTexts.has(outgoing)) {
+            incomingAnchorTexts.set(outgoing, /* @__PURE__ */ new Set());
+          }
+          incomingAnchorTexts.get(outgoing).add(anchorText);
+        }
       }
     }
     stageEnd("links", linkStart);
@@ -2556,6 +3582,15 @@ var IndexPipeline = class _IndexPipeline {
         });
       }
     }
+    for (const record of customRecords) {
+      const normalizedUrl = normalizeUrlPath(record.url);
+      if (!precomputedRoutes.has(normalizedUrl)) {
+        precomputedRoutes.set(normalizedUrl, {
+          routeFile: "",
+          routeResolution: "exact"
+        });
+      }
+    }
     for (const page of indexablePages) {
       const routeMatch = precomputedRoutes.get(normalizeUrlPath(page.url)) ?? mapUrlToRoute(page.url, routePatterns);
       if (routeMatch.routeResolution === "best-effort") {
@@ -2573,6 +3608,17 @@ var IndexPipeline = class _IndexPipeline {
       } else {
         routeExact += 1;
       }
+      const anchorSet = incomingAnchorTexts.get(page.url);
+      let incomingAnchorText;
+      if (anchorSet && anchorSet.size > 0) {
+        let joined = "";
+        for (const phrase of anchorSet) {
+          const next = joined ? `${joined} ${phrase}` : phrase;
+          if (next.length > 500) break;
+          joined = next;
+        }
+        incomingAnchorText = joined || void 0;
+      }
       const indexedPage = {
         url: page.url,
         title: page.title,
@@ -2582,40 +3628,113 @@ var IndexPipeline = class _IndexPipeline {
         generatedAt: nowIso(),
         incomingLinks: incomingLinkCount.get(page.url) ?? 0,
         outgoingLinks: page.outgoingLinks.length,
+        outgoingLinkUrls: page.outgoingLinks.map((l) => typeof l === "string" ? l : l.url),
         depth: getUrlDepth(page.url),
         tags: page.tags,
         markdown: page.markdown,
         description: page.description,
-        keywords: page.keywords
+        keywords: page.keywords,
+        publishedAt: page.publishedAt,
+        incomingAnchorText,
+        meta: page.meta
       };
       pages.push(indexedPage);
       this.logger.event("page_indexed", { url: page.url });
     }
+    const pageRecords = pages.map((p) => {
+      const summary = buildPageSummary(p);
+      return {
+        url: p.url,
+        title: p.title,
+        markdown: p.markdown,
+        projectId: scope.projectId,
+        scopeName: scope.scopeName,
+        routeFile: p.routeFile,
+        routeResolution: p.routeResolution,
+        incomingLinks: p.incomingLinks,
+        outgoingLinks: p.outgoingLinks,
+        outgoingLinkUrls: p.outgoingLinkUrls,
+        depth: p.depth,
+        tags: p.tags,
+        indexedAt: p.generatedAt,
+        summary,
+        description: p.description,
+        keywords: p.keywords,
+        contentHash: buildPageContentHash(p),
+        publishedAt: p.publishedAt,
+        meta: p.meta
+      };
+    });
+    const currentPageUrls = new Set(pageRecords.map((r) => r.url));
+    const changedPages = pageRecords.filter(
+      (r) => !existingPageHashes.has(r.url) || existingPageHashes.get(r.url) !== r.contentHash
+    );
+    const deletedPageUrls = [...existingPageHashes.keys()].filter((url) => !currentPageUrls.has(url));
     if (!options.dryRun) {
-      const pageRecords = pages.map((p) => {
-        const summary = buildPageSummary(p);
-        return {
-          url: p.url,
-          title: p.title,
-          markdown: p.markdown,
-          projectId: scope.projectId,
-          scopeName: scope.scopeName,
-          routeFile: p.routeFile,
-          routeResolution: p.routeResolution,
-          incomingLinks: p.incomingLinks,
-          outgoingLinks: p.outgoingLinks,
-          depth: p.depth,
-          tags: p.tags,
-          indexedAt: p.generatedAt,
-          summary,
-          description: p.description,
-          keywords: p.keywords
-        };
-      });
-      await this.store.deletePages(scope);
-      await this.store.upsertPages(pageRecords, scope);
+      if (options.force) {
+        await this.store.deletePages(scope);
+        this.logger.info(`Upserting ${pageRecords.length} page summaries...`);
+        const pageDocs = pageRecords.map((r) => ({
+          id: r.url,
+          data: r.summary ?? r.title,
+          metadata: {
+            title: r.title,
+            url: r.url,
+            description: r.description ?? "",
+            keywords: r.keywords ?? [],
+            summary: r.summary ?? "",
+            tags: r.tags,
+            markdown: r.markdown,
+            routeFile: r.routeFile,
+            routeResolution: r.routeResolution,
+            incomingLinks: r.incomingLinks,
+            outgoingLinks: r.outgoingLinks,
+            outgoingLinkUrls: r.outgoingLinkUrls ?? [],
+            depth: r.depth,
+            indexedAt: r.indexedAt,
+            contentHash: r.contentHash ?? "",
+            publishedAt: r.publishedAt ?? null,
+            ...r.meta && Object.keys(r.meta).length > 0 ? { meta: r.meta } : {}
+          }
+        }));
+        await this.store.upsertPages(pageDocs, scope);
+      } else {
+        if (changedPages.length > 0) {
+          this.logger.info(`Upserting ${changedPages.length} changed page summaries...`);
+          const pageDocs = changedPages.map((r) => ({
+            id: r.url,
+            data: r.summary ?? r.title,
+            metadata: {
+              title: r.title,
+              url: r.url,
+              description: r.description ?? "",
+              keywords: r.keywords ?? [],
+              summary: r.summary ?? "",
+              tags: r.tags,
+              markdown: r.markdown,
+              routeFile: r.routeFile,
+              routeResolution: r.routeResolution,
+              incomingLinks: r.incomingLinks,
+              outgoingLinks: r.outgoingLinks,
+              outgoingLinkUrls: r.outgoingLinkUrls ?? [],
+              depth: r.depth,
+              indexedAt: r.indexedAt,
+              contentHash: r.contentHash ?? "",
+              publishedAt: r.publishedAt ?? null,
+              ...r.meta && Object.keys(r.meta).length > 0 ? { meta: r.meta } : {}
+            }
+          }));
+          await this.store.upsertPages(pageDocs, scope);
+        }
+        if (deletedPageUrls.length > 0) {
+          await this.store.deletePagesByIds(deletedPageUrls, scope);
+        }
+      }
     }
+    const pagesChanged = options.force ? pageRecords.length : changedPages.length;
+    const pagesDeleted = deletedPageUrls.length;
     stageEnd("pages", pagesStart);
+    this.logger.info(`Page changes: ${pagesChanged} changed/new, ${pagesDeleted} deleted, ${pageRecords.length - changedPages.length} unchanged`);
     this.logger.info(`Indexed ${pages.length} page${pages.length === 1 ? "" : "s"} (${routeExact} exact, ${routeBestEffort} best-effort) (${stageTimingsMs["pages"]}ms)`);
     const chunkStart = stageStart();
     this.logger.info("Chunking pages...");
@@ -2624,6 +3743,18 @@ var IndexPipeline = class _IndexPipeline {
     if (typeof maxChunks === "number") {
       chunks = chunks.slice(0, maxChunks);
     }
+    if (this.hooks.transformChunk) {
+      const transformed = [];
+      for (const chunk of chunks) {
+        const result = await this.hooks.transformChunk(chunk);
+        if (result === null) {
+          this.logger.debug(`Chunk ${chunk.chunkKey} skipped by transformChunk hook`);
+          continue;
+        }
+        transformed.push(result);
+      }
+      chunks = transformed;
+    }
     for (const chunk of chunks) {
       this.logger.event("chunked", {
         url: chunk.url,
@@ -2636,7 +3767,7 @@ var IndexPipeline = class _IndexPipeline {
     for (const chunk of chunks) {
       currentChunkMap.set(chunk.chunkKey, chunk);
     }
-    const changedChunks = chunks.filter((chunk) => {
+    let changedChunks = chunks.filter((chunk) => {
       if (options.force) {
         return true;
       }
@@ -2650,38 +3781,43 @@ var IndexPipeline = class _IndexPipeline {
       return existingHash !== chunk.contentHash;
     });
     const deletes = [...existingHashes.keys()].filter((chunkKey) => !currentChunkMap.has(chunkKey));
+    if (this.hooks.beforeIndex) {
+      changedChunks = await this.hooks.beforeIndex(changedChunks);
+    }
     this.logger.info(`Changes detected: ${changedChunks.length} changed, ${deletes.length} deleted, ${chunks.length - changedChunks.length} unchanged`);
     const upsertStart = stageStart();
     let documentsUpserted = 0;
     if (!options.dryRun && changedChunks.length > 0) {
-      this.logger.info(`Upserting ${changedChunks.length} chunk${changedChunks.length === 1 ? "" : "s"} to Upstash Search...`);
-      const UPSTASH_CONTENT_LIMIT = 4096;
-      const FIELD_OVERHEAD = 200;
-      const MAX_TEXT_CHARS = UPSTASH_CONTENT_LIMIT - FIELD_OVERHEAD;
+      this.logger.info(`Upserting ${changedChunks.length} chunk${changedChunks.length === 1 ? "" : "s"} to Upstash Vector...`);
       const docs = changedChunks.map((chunk) => {
-        const title = chunk.title;
-        const sectionTitle = chunk.sectionTitle ?? "";
-        const url = chunk.url;
-        const tags = chunk.tags.join(",");
-        const headingPath = chunk.headingPath.join(" > ");
-        const otherFieldsLen = title.length + sectionTitle.length + url.length + tags.length + headingPath.length;
-        const textBudget = Math.max(500, UPSTASH_CONTENT_LIMIT - otherFieldsLen - 50);
-        const text = buildEmbeddingText(chunk, this.config.chunking.prependTitle).slice(0, textBudget);
+        const embeddingText = buildEmbeddingText(chunk, this.config.chunking.prependTitle);
+        if (embeddingText.length > 2e3) {
+          this.logger.warn(
+            `Chunk ${chunk.chunkKey} text is ${embeddingText.length} chars (~${Math.round(embeddingText.length / 4)} tokens), which may exceed the 512-token model limit and be silently truncated.`
+          );
+        }
         return {
           id: chunk.chunkKey,
-          content: { title, sectionTitle, text, url, tags, headingPath },
+          data: embeddingText,
           metadata: {
-            projectId: scope.projectId,
-            scopeName: scope.scopeName,
+            url: chunk.url,
             path: chunk.path,
+            title: chunk.title,
+            sectionTitle: chunk.sectionTitle ?? "",
+            headingPath: chunk.headingPath.join(" > "),
             snippet: chunk.snippet,
+            chunkText: embeddingText,
+            tags: chunk.tags,
             ordinal: chunk.ordinal,
             contentHash: chunk.contentHash,
             depth: chunk.depth,
             incomingLinks: chunk.incomingLinks,
             routeFile: chunk.routeFile,
             description: chunk.description ?? "",
-            keywords: (chunk.keywords ?? []).join(",")
+            keywords: chunk.keywords ?? [],
+            publishedAt: chunk.publishedAt ?? null,
+            incomingAnchorText: chunk.incomingAnchorText ?? "",
+            ...chunk.meta && Object.keys(chunk.meta).length > 0 ? { meta: chunk.meta } : {}
           }
         };
       });
@@ -2699,9 +3835,16 @@ var IndexPipeline = class _IndexPipeline {
     } else {
       this.logger.info("No chunks to upsert \u2014 all up to date");
     }
+    if (this.config.llmsTxt.enable && !options.dryRun) {
+      const llmsStart = stageStart();
+      await writeLlmsTxt(pages, this.config, this.cwd, this.logger);
+      stageEnd("llms_txt", llmsStart);
+    }
     this.logger.info("Done.");
-    return {
+    const stats = {
       pagesProcessed: pages.length,
+      pagesChanged,
+      pagesDeleted,
       chunksTotal: chunks.length,
       chunksChanged: changedChunks.length,
       documentsUpserted,
@@ -2710,10 +3853,15 @@ var IndexPipeline = class _IndexPipeline {
       routeBestEffort,
       stageTimingsMs
     };
+    if (this.hooks.afterIndex) {
+      await this.hooks.afterIndex(stats);
+    }
+    return stats;
   }
 };
 
 // src/mcp/server.ts
+import { createHash as createHash2, timingSafeEqual } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -2721,16 +3869,139 @@ import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js
 import { z as z3 } from "zod";
 
 // src/search/engine.ts
-import path11 from "path";
+import path12 from "path";
 import { z as z2 } from "zod";
+
+// src/search/related-pages.ts
+function diceScore(urlA, urlB) {
+  const segmentsA = urlA.split("/").filter(Boolean);
+  const segmentsB = urlB.split("/").filter(Boolean);
+  if (segmentsA.length === 0 && segmentsB.length === 0) return 1;
+  if (segmentsA.length === 0 || segmentsB.length === 0) return 0;
+  let shared = 0;
+  const minLen = Math.min(segmentsA.length, segmentsB.length);
+  for (let i = 0; i < minLen; i++) {
+    if (segmentsA[i] === segmentsB[i]) {
+      shared++;
+    } else {
+      break;
+    }
+  }
+  return 2 * shared / (segmentsA.length + segmentsB.length);
+}
+function compositeScore(isLinked, dice, semantic) {
+  return (isLinked ? 0.5 : 0) + 0.3 * dice + 0.2 * semantic;
+}
+function dominantRelationshipType(isOutgoing, isIncoming, dice) {
+  if (isOutgoing) return "outgoing_link";
+  if (isIncoming) return "incoming_link";
+  if (dice > 0.4) return "sibling";
+  return "semantic";
+}
+
+// src/search/engine.ts
+var rankingOverridesSchema = z2.object({
+  ranking: z2.object({
+    enableIncomingLinkBoost: z2.boolean().optional(),
+    enableDepthBoost: z2.boolean().optional(),
+    aggregationCap: z2.number().int().positive().optional(),
+    aggregationDecay: z2.number().min(0).max(1).optional(),
+    minChunkScoreRatio: z2.number().min(0).max(1).optional(),
+    minScoreRatio: z2.number().min(0).max(1).optional(),
+    scoreGapThreshold: z2.number().min(0).max(1).optional(),
+    weights: z2.object({
+      incomingLinks: z2.number().optional(),
+      depth: z2.number().optional(),
+      aggregation: z2.number().optional(),
+      titleMatch: z2.number().optional()
+    }).optional()
+  }).optional(),
+  search: z2.object({
+    pageSearchWeight: z2.number().min(0).max(1).optional()
+  }).optional()
+}).optional();
 var requestSchema = z2.object({
   q: z2.string().trim().min(1),
   topK: z2.number().int().positive().max(100).optional(),
   scope: z2.string().optional(),
   pathPrefix: z2.string().optional(),
   tags: z2.array(z2.string()).optional(),
-  groupBy: z2.enum(["page", "chunk"]).optional()
+  filters: z2.record(z2.string(), z2.union([z2.string(), z2.number(), z2.boolean()])).optional(),
+  groupBy: z2.enum(["page", "chunk"]).optional(),
+  maxSubResults: z2.number().int().positive().max(20).optional(),
+  debug: z2.boolean().optional(),
+  rankingOverrides: rankingOverridesSchema
 });
+var MAX_SITE_STRUCTURE_PAGES = 2e3;
+function makeNode(url, depth) {
+  return { url, title: "", depth, routeFile: "", isIndexed: false, childCount: 0, children: [] };
+}
+function buildTree(pages, pathPrefix) {
+  const nodeMap = /* @__PURE__ */ new Map();
+  const root = makeNode("/", 0);
+  nodeMap.set("/", root);
+  for (const page of pages) {
+    const normalized = normalizeUrlPath(page.url);
+    const segments = normalized.split("/").filter(Boolean);
+    if (segments.length === 0) {
+      root.title = page.title;
+      root.routeFile = page.routeFile;
+      root.isIndexed = true;
+      continue;
+    }
+    for (let i = 1; i <= segments.length; i++) {
+      const partialUrl = "/" + segments.slice(0, i).join("/");
+      if (!nodeMap.has(partialUrl)) {
+        nodeMap.set(partialUrl, makeNode(partialUrl, i));
+      }
+    }
+    const node = nodeMap.get(normalized);
+    node.title = page.title;
+    node.routeFile = page.routeFile;
+    node.isIndexed = true;
+  }
+  for (const [url, node] of nodeMap) {
+    if (url === "/") continue;
+    const segments = url.split("/").filter(Boolean);
+    const parentUrl = segments.length === 1 ? "/" : "/" + segments.slice(0, -1).join("/");
+    const parent = nodeMap.get(parentUrl) ?? root;
+    parent.children.push(node);
+  }
+  const sortAndCount = (node) => {
+    node.children.sort((a, b) => a.url.localeCompare(b.url));
+    node.childCount = node.children.length;
+    for (const child of node.children) {
+      sortAndCount(child);
+    }
+  };
+  sortAndCount(root);
+  if (pathPrefix) {
+    const normalizedPrefix = normalizeUrlPath(pathPrefix);
+    const subtreeRoot = nodeMap.get(normalizedPrefix);
+    if (subtreeRoot) {
+      return subtreeRoot;
+    }
+    return makeNode(normalizedPrefix, normalizedPrefix.split("/").filter(Boolean).length);
+  }
+  return root;
+}
+function mergeRankingOverrides(base, overrides) {
+  return {
+    ...base,
+    search: {
+      ...base.search,
+      ...overrides.search
+    },
+    ranking: {
+      ...base.ranking,
+      ...overrides.ranking,
+      weights: {
+        ...base.ranking.weights,
+        ...overrides.ranking?.weights
+      }
+    }
+  };
+}
 var SearchEngine = class _SearchEngine {
   cwd;
   config;
@@ -2741,7 +4012,7 @@ var SearchEngine = class _SearchEngine {
     this.store = options.store;
   }
   static async create(options = {}) {
-    const cwd = path11.resolve(options.cwd ?? process.cwd());
+    const cwd = path12.resolve(options.cwd ?? process.cwd());
     const config = options.config ?? await loadConfig({ cwd, configPath: options.configPath });
     const store = options.store ?? await createUpstashStore(config);
     return new _SearchEngine({
@@ -2760,125 +4031,203 @@ var SearchEngine = class _SearchEngine {
     }
     const input = parsed.data;
     const totalStart = process.hrtime.bigint();
+    const effectiveConfig = input.debug && input.rankingOverrides ? mergeRankingOverrides(this.config, input.rankingOverrides) : this.config;
     const resolvedScope = resolveScope(this.config, input.scope);
     const topK = input.topK ?? 10;
+    const maxSubResults = input.maxSubResults ?? 5;
     const groupByPage = (input.groupBy ?? "page") === "page";
-    const candidateK = groupByPage ? Math.max(topK * 10, 50) : Math.max(50, topK);
-    const filterParts = [];
-    if (input.pathPrefix) {
-      const prefix = input.pathPrefix.startsWith("/") ? input.pathPrefix : `/${input.pathPrefix}`;
-      filterParts.push(`url GLOB '${prefix}*'`);
-    }
-    if (input.tags && input.tags.length > 0) {
-      for (const tag of input.tags) {
-        filterParts.push(`tags GLOB '*${tag}*'`);
+    const queryText = input.q;
+    const pathPrefix = input.pathPrefix ? input.pathPrefix.startsWith("/") ? input.pathPrefix : `/${input.pathPrefix}` : void 0;
+    const filterTags = input.tags && input.tags.length > 0 ? input.tags : void 0;
+    const metaFilterStr = input.filters && Object.keys(input.filters).length > 0 ? buildMetaFilterString(input.filters) : "";
+    const metaFilter = metaFilterStr || void 0;
+    const applyPagePostFilters = (hits) => {
+      let filtered = hits;
+      if (pathPrefix) {
+        filtered = filtered.filter((h) => h.url.startsWith(pathPrefix));
       }
-    }
-    const filter = filterParts.length > 0 ? filterParts.join(" AND ") : void 0;
-    const useDualSearch = this.config.search.dualSearch && groupByPage;
+      if (filterTags) {
+        filtered = filtered.filter(
+          (h) => filterTags.every((tag) => h.tags.includes(tag))
+        );
+      }
+      return filtered;
+    };
+    const applyChunkPostFilters = (hits) => {
+      let filtered = hits;
+      if (filterTags) {
+        filtered = filtered.filter(
+          (h) => filterTags.every((tag) => h.metadata.tags.includes(tag))
+        );
+      }
+      return filtered;
+    };
     const searchStart = process.hrtime.bigint();
-    let ranked;
-    if (useDualSearch) {
-      const chunkLimit = Math.max(topK * 10, 100);
-      const pageLimit = 20;
-      const [pageHits, chunkHits] = await Promise.all([
-        this.store.searchPages(
-          input.q,
-          {
-            limit: pageLimit,
-            semanticWeight: this.config.search.semanticWeight,
-            inputEnrichment: this.config.search.inputEnrichment,
-            filter
-          },
-          resolvedScope
-        ),
-        this.store.search(
-          input.q,
-          {
-            limit: chunkLimit,
-            semanticWeight: this.config.search.semanticWeight,
-            inputEnrichment: this.config.search.inputEnrichment,
-            reranking: false,
-            filter
-          },
+    if (groupByPage) {
+      const fetchMultiplier = pathPrefix || filterTags ? 2 : 1;
+      const pageLimit = Math.max(topK * 2, 20);
+      const pageHits = await this.store.searchPagesByText(
+        queryText,
+        { limit: pageLimit * fetchMultiplier, filter: metaFilter },
+        resolvedScope
+      );
+      const filteredPages = applyPagePostFilters(pageHits);
+      let rankedPages = rankPageHits(filteredPages, effectiveConfig, input.q, input.debug);
+      rankedPages = trimPagesByScoreGap(rankedPages, effectiveConfig);
+      const topPages = rankedPages.slice(0, topK);
+      const chunkPromises = topPages.map(
+        (page) => this.store.searchChunksByUrl(
+          queryText,
+          page.url,
+          { limit: maxSubResults, filter: metaFilter },
           resolvedScope
-        )
-      ]);
-      const rankedChunks = rankHits(chunkHits, this.config, input.q);
-      ranked = mergePageAndChunkResults(pageHits, rankedChunks, this.config);
+        ).then((chunks) => applyChunkPostFilters(chunks))
+      );
+      const allChunks = await Promise.all(chunkPromises);
+      const searchMs = hrTimeMs(searchStart);
+      const results = this.buildPageFirstResults(topPages, allChunks, input.q, input.debug, maxSubResults);
+      return {
+        q: input.q,
+        scope: resolvedScope.scopeName,
+        results,
+        meta: {
+          timingsMs: {
+            search: Math.round(searchMs),
+            total: Math.round(hrTimeMs(totalStart))
+          }
+        }
+      };
     } else {
+      const candidateK = Math.max(50, topK);
+      const fetchMultiplier = pathPrefix || filterTags ? 2 : 1;
       const hits = await this.store.search(
-        input.q,
-        {
-          limit: candidateK,
-          semanticWeight: this.config.search.semanticWeight,
-          inputEnrichment: this.config.search.inputEnrichment,
-          reranking: this.config.search.reranking,
-          filter
-        },
+        queryText,
+        { limit: candidateK * fetchMultiplier, filter: metaFilter },
         resolvedScope
       );
-      ranked = rankHits(hits, this.config, input.q);
-    }
-    const searchMs = hrTimeMs(searchStart);
-    const results = this.buildResults(ranked, topK, groupByPage, input.q);
-    return {
-      q: input.q,
-      scope: resolvedScope.scopeName,
-      results,
-      meta: {
-        timingsMs: {
-          search: Math.round(searchMs),
-          total: Math.round(hrTimeMs(totalStart))
+      let filtered = hits;
+      if (pathPrefix) {
+        filtered = filtered.filter((h) => h.metadata.url.startsWith(pathPrefix));
+      }
+      if (filterTags) {
+        filtered = filtered.filter(
+          (h) => filterTags.every((tag) => h.metadata.tags.includes(tag))
+        );
+      }
+      const ranked = rankHits(filtered, effectiveConfig, input.q, input.debug);
+      const searchMs = hrTimeMs(searchStart);
+      const results = this.buildResults(ranked, topK, false, maxSubResults, input.q, input.debug, effectiveConfig);
+      return {
+        q: input.q,
+        scope: resolvedScope.scopeName,
+        results,
+        meta: {
+          timingsMs: {
+            search: Math.round(searchMs),
+            total: Math.round(hrTimeMs(totalStart))
+          }
         }
+      };
+    }
+  }
+  buildPageFirstResults(rankedPages, allChunks, query, debug, maxSubResults = 5) {
+    return rankedPages.map((page, i) => {
+      const chunks = allChunks[i] ?? [];
+      const bestChunk = chunks[0];
+      const snippet = bestChunk ? query ? queryAwareExcerpt(bestChunk.metadata.chunkText, query) : toSnippet(bestChunk.metadata.chunkText) : page.description || page.title;
+      const result = {
+        url: page.url,
+        title: page.title,
+        sectionTitle: bestChunk?.metadata.sectionTitle || void 0,
+        snippet,
+        chunkText: bestChunk?.metadata.chunkText || void 0,
+        score: Number(page.finalScore.toFixed(6)),
+        routeFile: page.routeFile,
+        chunks: chunks.length > 0 ? chunks.slice(0, maxSubResults).map((c) => ({
+          sectionTitle: c.metadata.sectionTitle || void 0,
+          snippet: query ? queryAwareExcerpt(c.metadata.chunkText, query) : toSnippet(c.metadata.chunkText),
+          chunkText: c.metadata.chunkText || void 0,
+          headingPath: c.metadata.headingPath,
+          score: Number(c.score.toFixed(6))
+        })) : void 0
+      };
+      if (debug && page.breakdown) {
+        result.breakdown = {
+          baseScore: page.breakdown.baseScore,
+          incomingLinkBoost: page.breakdown.incomingLinkBoost,
+          depthBoost: page.breakdown.depthBoost,
+          titleMatchBoost: page.breakdown.titleMatchBoost,
+          freshnessBoost: page.breakdown.freshnessBoost,
+          anchorTextMatchBoost: 0
+        };
       }
-    };
+      return result;
+    });
   }
-  ensureSnippet(hit) {
+  ensureSnippet(hit, query) {
+    const chunkText = hit.hit.metadata.chunkText;
+    if (query && chunkText) return queryAwareExcerpt(chunkText, query);
     const snippet = hit.hit.metadata.snippet;
     if (snippet && snippet.length >= 30) return snippet;
-    const chunkText = hit.hit.metadata.chunkText;
     if (chunkText) return toSnippet(chunkText);
     return snippet || "";
   }
-  buildResults(ordered, topK, groupByPage, _query) {
+  buildResults(ordered, topK, groupByPage, maxSubResults, query, debug, config) {
+    const cfg = config ?? this.config;
     if (groupByPage) {
-      let pages = aggregateByPage(ordered, this.config);
-      pages = trimByScoreGap(pages, this.config);
-      const minRatio = this.config.ranking.minChunkScoreRatio;
+      let pages = aggregateByPage(ordered, cfg);
+      pages = trimByScoreGap(pages, cfg);
+      const minRatio = cfg.ranking.minChunkScoreRatio;
       return pages.slice(0, topK).map((page) => {
         const bestScore = page.bestChunk.finalScore;
         const minChunkScore = Number.isFinite(bestScore) ? bestScore * minRatio : Number.NEGATIVE_INFINITY;
-        const meaningful = page.matchingChunks.filter((c) => c.finalScore >= minChunkScore).slice(0, 5);
-        return {
+        const meaningful = page.matchingChunks.filter((c) => c.finalScore >= minChunkScore).slice(0, maxSubResults);
+        const result = {
           url: page.url,
           title: page.title,
           sectionTitle: page.bestChunk.hit.metadata.sectionTitle || void 0,
-          snippet: this.ensureSnippet(page.bestChunk),
+          snippet: this.ensureSnippet(page.bestChunk, query),
+          chunkText: page.bestChunk.hit.metadata.chunkText || void 0,
           score: Number(page.pageScore.toFixed(6)),
           routeFile: page.routeFile,
-          chunks: meaningful.length > 1 ? meaningful.map((c) => ({
+          chunks: meaningful.length >= 1 ? meaningful.map((c) => ({
             sectionTitle: c.hit.metadata.sectionTitle || void 0,
-            snippet: this.ensureSnippet(c),
+            snippet: this.ensureSnippet(c, query),
+            chunkText: c.hit.metadata.chunkText || void 0,
             headingPath: c.hit.metadata.headingPath,
             score: Number(c.finalScore.toFixed(6))
           })) : void 0
         };
+        if (debug && page.bestChunk.breakdown) {
+          result.breakdown = page.bestChunk.breakdown;
+        }
+        return result;
       });
     } else {
       let filtered = ordered;
-      const minScore = this.config.ranking.minScore;
-      if (minScore > 0) {
-        filtered = ordered.filter((entry) => entry.finalScore >= minScore);
-      }
-      return filtered.slice(0, topK).map(({ hit, finalScore }) => ({
-        url: hit.metadata.url,
-        title: hit.metadata.title,
-        sectionTitle: hit.metadata.sectionTitle || void 0,
-        snippet: this.ensureSnippet({ hit, finalScore }),
-        score: Number(finalScore.toFixed(6)),
-        routeFile: hit.metadata.routeFile
-      }));
+      const minScoreRatio = cfg.ranking.minScoreRatio;
+      if (minScoreRatio > 0 && ordered.length > 0) {
+        const topScore = ordered[0].finalScore;
+        if (Number.isFinite(topScore) && topScore > 0) {
+          const threshold = topScore * minScoreRatio;
+          filtered = ordered.filter((entry) => entry.finalScore >= threshold);
+        }
+      }
+      return filtered.slice(0, topK).map(({ hit, finalScore, breakdown }) => {
+        const result = {
+          url: hit.metadata.url,
+          title: hit.metadata.title,
+          sectionTitle: hit.metadata.sectionTitle || void 0,
+          snippet: this.ensureSnippet({ hit, finalScore }, query),
+          chunkText: hit.metadata.chunkText || void 0,
+          score: Number(finalScore.toFixed(6)),
+          routeFile: hit.metadata.routeFile
+        };
+        if (debug && breakdown) {
+          result.breakdown = breakdown;
+        }
+        return result;
+      });
     }
   }
   async getPage(pathOrUrl, scope) {
@@ -2904,6 +4253,116 @@ var SearchEngine = class _SearchEngine {
       markdown: page.markdown
     };
   }
+  async listPages(opts) {
+    const resolvedScope = resolveScope(this.config, opts?.scope);
+    const pathPrefix = opts?.pathPrefix ? opts.pathPrefix.startsWith("/") ? opts.pathPrefix : `/${opts.pathPrefix}` : void 0;
+    return this.store.listPages(resolvedScope, {
+      cursor: opts?.cursor,
+      limit: opts?.limit,
+      pathPrefix
+    });
+  }
+  async getSiteStructure(opts) {
+    const maxPages = Math.min(opts?.maxPages ?? MAX_SITE_STRUCTURE_PAGES, MAX_SITE_STRUCTURE_PAGES);
+    const allPages = [];
+    let cursor;
+    let truncated = false;
+    do {
+      const result = await this.listPages({
+        pathPrefix: opts?.pathPrefix,
+        scope: opts?.scope,
+        cursor,
+        limit: 200
+      });
+      allPages.push(...result.pages);
+      cursor = result.nextCursor;
+      if (allPages.length >= maxPages) {
+        truncated = allPages.length > maxPages || !!cursor;
+        allPages.length = maxPages;
+        break;
+      }
+    } while (cursor);
+    const root = buildTree(allPages, opts?.pathPrefix);
+    return {
+      root,
+      totalPages: allPages.length,
+      truncated
+    };
+  }
+  async getRelatedPages(pathOrUrl, opts) {
+    const resolvedScope = resolveScope(this.config, opts?.scope);
+    const urlPath = this.resolveInputPath(pathOrUrl);
+    const topK = Math.min(opts?.topK ?? 10, 25);
+    const source = await this.store.fetchPageWithVector(urlPath, resolvedScope);
+    if (!source) {
+      throw new SearchSocketError("INVALID_REQUEST", `Indexed page not found for ${urlPath}`, 404);
+    }
+    const sourceOutgoing = new Set(source.metadata.outgoingLinkUrls ?? []);
+    const semanticHits = await this.store.searchPagesByVector(
+      source.vector,
+      { limit: 50 },
+      resolvedScope
+    );
+    const filteredHits = semanticHits.filter((h) => h.url !== urlPath);
+    const semanticScoreMap = /* @__PURE__ */ new Map();
+    for (const hit of filteredHits) {
+      semanticScoreMap.set(hit.url, hit.score);
+    }
+    const candidateUrls = /* @__PURE__ */ new Set();
+    for (const hit of filteredHits) {
+      candidateUrls.add(hit.url);
+    }
+    for (const url of sourceOutgoing) {
+      if (url !== urlPath) candidateUrls.add(url);
+    }
+    const missingUrls = [...sourceOutgoing].filter(
+      (u) => u !== urlPath && !semanticScoreMap.has(u)
+    );
+    const fetchedPages = missingUrls.length > 0 ? await this.store.fetchPagesBatch(missingUrls, resolvedScope) : [];
+    const metaMap = /* @__PURE__ */ new Map();
+    for (const hit of filteredHits) {
+      metaMap.set(hit.url, { title: hit.title, routeFile: hit.routeFile, outgoingLinkUrls: [] });
+    }
+    for (const p of fetchedPages) {
+      metaMap.set(p.url, { title: p.title, routeFile: p.routeFile, outgoingLinkUrls: p.outgoingLinkUrls });
+    }
+    const semanticUrls = filteredHits.map((h) => h.url);
+    if (semanticUrls.length > 0) {
+      const semanticPageData = await this.store.fetchPagesBatch(semanticUrls, resolvedScope);
+      for (const p of semanticPageData) {
+        const existing = metaMap.get(p.url);
+        if (existing) {
+          existing.outgoingLinkUrls = p.outgoingLinkUrls;
+        }
+      }
+    }
+    const candidates = [];
+    for (const url of candidateUrls) {
+      const meta = metaMap.get(url);
+      if (!meta) continue;
+      const isOutgoing = sourceOutgoing.has(url);
+      const isIncoming = meta.outgoingLinkUrls.includes(urlPath);
+      const isLinked = isOutgoing || isIncoming;
+      const dice = diceScore(urlPath, url);
+      const semantic = semanticScoreMap.get(url) ?? 0;
+      const score = compositeScore(isLinked, dice, semantic);
+      const relationshipType = dominantRelationshipType(isOutgoing, isIncoming, dice);
+      candidates.push({
+        url,
+        title: meta.title,
+        score: Number(score.toFixed(6)),
+        relationshipType,
+        routeFile: meta.routeFile
+      });
+    }
+    candidates.sort((a, b) => b.score - a.score);
+    const results = candidates.slice(0, topK);
+    return {
+      sourceUrl: urlPath,
+      scope: resolvedScope.scopeName,
+      relatedPages: results
+    };
+  }
   async health() {
     return this.store.health();
   }
@@ -2928,14 +4387,40 @@ function createServer(engine) {
   server.registerTool(
     "search",
     {
-      description: "Semantic site search powered by Upstash Search. Returns url/title/snippet/score/routeFile for each match. Supports optional scope, pathPrefix, tags, topK, and groupBy.",
+      description: `Semantic site search powered by Upstash Search. Returns url, title, snippet, chunkText, score, and routeFile per result. chunkText contains the full raw chunk markdown. When groupBy is 'page' (default), each result includes a chunks array with section-level sub-results containing sectionTitle, headingPath, snippet, and score. Supports optional filters for structured metadata (e.g. {"version": 2, "deprecated": false}).`,
       inputSchema: {
         query: z3.string().min(1),
         scope: z3.string().optional(),
         topK: z3.number().int().positive().max(100).optional(),
         pathPrefix: z3.string().optional(),
         tags: z3.array(z3.string()).optional(),
-        groupBy: z3.enum(["page", "chunk"]).optional()
+        filters: z3.record(z3.string(), z3.union([z3.string(), z3.number(), z3.boolean()])).optional(),
+        groupBy: z3.enum(["page", "chunk"]).optional(),
+        maxSubResults: z3.number().int().positive().max(20).optional()
+      },
+      outputSchema: {
+        q: z3.string(),
+        scope: z3.string(),
+        results: z3.array(z3.object({
+          url: z3.string(),
+          title: z3.string(),
+          sectionTitle: z3.string().optional(),
+          snippet: z3.string(),
+          score: z3.number(),
+          routeFile: z3.string(),
+          chunks: z3.array(z3.object({
+            sectionTitle: z3.string().optional(),
+            snippet: z3.string(),
+            headingPath: z3.array(z3.string()),
+            score: z3.number()
+          })).optional()
+        })),
+        meta: z3.object({
+          timingsMs: z3.object({
+            search: z3.number(),
+            total: z3.number()
+          })
+        })
       }
     },
     async (input) => {
@@ -2945,7 +4430,9 @@ function createServer(engine) {
         scope: input.scope,
         pathPrefix: input.pathPrefix,
         tags: input.tags,
-        groupBy: input.groupBy
+        filters: input.filters,
+        groupBy: input.groupBy,
+        maxSubResults: input.maxSubResults
       });
       return {
         content: [
@@ -2953,7 +4440,8 @@ function createServer(engine) {
             type: "text",
             text: JSON.stringify(result, null, 2)
           }
-        ]
+        ],
+        structuredContent: result
       };
     }
   );
@@ -2978,8 +4466,134 @@ function createServer(engine) {
       };
     }
   );
+  server.registerTool(
+    "list_pages",
+    {
+      description: "List indexed pages with optional path prefix filtering and cursor-based pagination. Returns url, title, description, and routeFile for each page. Use nextCursor to fetch subsequent pages.",
+      inputSchema: {
+        pathPrefix: z3.string().optional(),
+        cursor: z3.string().optional(),
+        limit: z3.number().int().positive().max(200).optional(),
+        scope: z3.string().optional()
+      }
+    },
+    async (input) => {
+      const result = await engine.listPages({
+        pathPrefix: input.pathPrefix,
+        cursor: input.cursor,
+        limit: input.limit,
+        scope: input.scope
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_site_structure",
+    {
+      description: "Returns the hierarchical page tree derived from URL paths. Use this to understand site navigation structure, find where pages belong, or scope further operations to a section. Nodes with isIndexed: false are implicit structural parents not directly in the index. Large sites (>2000 pages) return truncated: true.",
+      inputSchema: {
+        pathPrefix: z3.string().optional(),
+        scope: z3.string().optional(),
+        maxPages: z3.number().int().positive().max(2e3).optional()
+      }
+    },
+    async (input) => {
+      const result = await engine.getSiteStructure({
+        pathPrefix: input.pathPrefix,
+        scope: input.scope,
+        maxPages: input.maxPages
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "find_source_file",
+    {
+      description: "Find the SvelteKit source file for a piece of site content. Use this when you need to locate and edit content on the site. Returns the URL, route file path, section title, and a content snippet.",
+      inputSchema: {
+        query: z3.string().min(1),
+        scope: z3.string().optional()
+      }
+    },
+    async (input) => {
+      const result = await engine.search({
+        q: input.query,
+        topK: 1,
+        scope: input.scope
+      });
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "No matching content found for the given query."
+              })
+            }
+          ]
+        };
+      }
+      const match = result.results[0];
+      const { url, routeFile, sectionTitle, snippet } = match;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ url, routeFile, sectionTitle, snippet })
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "get_related_pages",
+    {
+      description: "Find pages related to a given URL using link graph, semantic similarity, and structural proximity. Returns related pages ranked by a composite relatedness score. Use this to discover content connected to a known page.",
+      inputSchema: {
+        pathOrUrl: z3.string().min(1),
+        scope: z3.string().optional(),
+        topK: z3.number().int().positive().max(25).optional()
+      }
+    },
+    async (input) => {
+      const result = await engine.getRelatedPages(input.pathOrUrl, {
+        topK: input.topK,
+        scope: input.scope
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
   return server;
 }
+function resolveApiKey(config) {
+  return config.mcp.http.apiKey ?? (config.mcp.http.apiKeyEnv ? process.env[config.mcp.http.apiKeyEnv] : void 0);
+}
+function verifyApiKey(provided, expected) {
+  const a = createHash2("sha256").update(provided).digest();
+  const b = createHash2("sha256").update(expected).digest();
+  return timingSafeEqual(a, b);
+}
 function redirectConsoleToStderr() {
   const originalLog = console.log;
   console.log = (...args) => {
@@ -2996,89 +4610,945 @@ async function startHttpServer(serverFactory, config, opts) {
   const app = createMcpExpressApp();
   const port = opts.httpPort ?? config.mcp.http.port;
   const endpointPath = opts.httpPath ?? config.mcp.http.path;
+  const isPublic = config.mcp.access === "public";
+  const host = isPublic ? "0.0.0.0" : "127.0.0.1";
+  const apiKey = isPublic ? resolveApiKey(config) : void 0;
   app.post(endpointPath, async (req, res) => {
+    if (isPublic && apiKey) {
+      const authHeader = req.headers["authorization"];
+      const provided = (authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : void 0) ?? req.headers["x-api-key"] ?? "";
+      if (!provided || !verifyApiKey(provided, apiKey)) {
+        res.status(401).json({
+          jsonrpc: "2.0",
+          error: { code: -32001, message: "Unauthorized" },
+          id: null
+        });
+        return;
+      }
+    }
     const server = serverFactory();
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: void 0
     });
     try {
-      await server.connect(transport);
-      await transport.handleRequest(req, res, req.body);
-      res.on("close", () => {
-        transport.close();
-        server.close();
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      res.on("close", () => {
+        transport.close();
+        server.close();
+      });
+    } catch (error) {
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: error instanceof Error ? error.message : "Internal server error"
+          },
+          id: null
+        });
+      }
+    }
+  });
+  app.get(endpointPath, (_req, res) => {
+    res.writeHead(405).end(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: -32e3,
+          message: "Method not allowed"
+        },
+        id: null
+      })
+    );
+  });
+  app.delete(endpointPath, (_req, res) => {
+    res.writeHead(405).end(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: -32e3,
+          message: "Method not allowed"
+        },
+        id: null
+      })
+    );
+  });
+  await new Promise((resolve, reject) => {
+    const instance = app.listen(port, host, () => {
+      process.stderr.write(`SearchSocket MCP HTTP server listening on http://${host}:${port}${endpointPath}
+`);
+      if (isPublic) {
+        process.stderr.write("WARNING: Server is in public mode. Ensure HTTPS is configured via a reverse proxy for production use.\n");
+      }
+      resolve();
+    });
+    instance.once("error", reject);
+    process.on("SIGINT", async () => {
+      await new Promise((shutdownResolve) => instance.close(() => shutdownResolve()));
+      process.exit(0);
+    });
+  });
+}
+async function runMcpServer(options = {}) {
+  const config = await loadConfig({
+    cwd: options.cwd,
+    configPath: options.configPath
+  });
+  if (options.access) config.mcp.access = options.access;
+  if (options.apiKey) config.mcp.http.apiKey = options.apiKey;
+  if (config.mcp.access === "public" && !resolveApiKey(config)) {
+    throw new Error(
+      'MCP access is "public" but no API key is configured. Pass --api-key or set mcp.http.apiKey / mcp.http.apiKeyEnv in config.'
+    );
+  }
+  const resolvedTransport = options.transport ?? config.mcp.transport;
+  if (resolvedTransport === "stdio") {
+    redirectConsoleToStderr();
+  }
+  const engine = await SearchEngine.create({
+    cwd: options.cwd,
+    configPath: options.configPath,
+    config
+  });
+  if (resolvedTransport === "http") {
+    await startHttpServer(() => createServer(engine), config, options);
+    return;
+  }
+  const server = createServer(engine);
+  const stdioTransport = new StdioServerTransport();
+  await server.connect(stdioTransport);
+}
+
+// src/playground/server.ts
+import express from "express";
+
+// src/playground/playground.html
+var playground_default = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SearchSocket Playground</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f8f9fa; color: #1a1a2e; padding: 2rem; max-width: 900px; margin: 0 auto; }
+  h1 { font-size: 1.5rem; margin-bottom: 1.5rem; color: #16213e; }
+  h1 span { font-weight: 400; color: #888; }
+  .search-box { display: flex; gap: 0.5rem; margin-bottom: 0.5rem; }
+  .search-box input { flex: 1; padding: 0.75rem 1rem; font-size: 1rem; border: 2px solid #ddd; border-radius: 8px; outline: none; transition: border-color 0.2s; }
+  .search-box input:focus { border-color: #4361ee; }
+  .search-opts { display: flex; gap: 1rem; margin-bottom: 1.5rem; font-size: 0.85rem; color: #555; align-items: center; }
+  .search-opts label { display: flex; align-items: center; gap: 0.3rem; cursor: pointer; }
+  .search-opts select { padding: 0.25rem 0.5rem; border: 1px solid #ccc; border-radius: 4px; font-size: 0.85rem; }
+  .meta { font-size: 0.8rem; color: #888; margin-bottom: 1rem; }
+  .result { background: #fff; border: 1px solid #e0e0e0; border-radius: 8px; padding: 1rem 1.25rem; margin-bottom: 0.75rem; }
+  .result-header { display: flex; justify-content: space-between; align-items: flex-start; gap: 1rem; }
+  .result-title { font-size: 1.05rem; font-weight: 600; color: #16213e; text-decoration: none; }
+  .result-title:hover { color: #4361ee; }
+  .result-score { font-size: 0.8rem; font-weight: 600; color: #4361ee; white-space: nowrap; background: #eef1ff; padding: 0.2rem 0.5rem; border-radius: 4px; }
+  .result-url { font-size: 0.8rem; color: #888; margin-top: 0.2rem; }
+  .result-snippet { font-size: 0.9rem; color: #444; margin-top: 0.5rem; line-height: 1.5; }
+  .result-meta { display: flex; gap: 0.75rem; flex-wrap: wrap; margin-top: 0.5rem; font-size: 0.78rem; color: #777; }
+  .result-meta span { background: #f0f0f0; padding: 0.15rem 0.5rem; border-radius: 4px; }
+  .breakdown { margin-top: 0.5rem; padding: 0.5rem 0.75rem; background: #f8f9fa; border-radius: 6px; font-size: 0.8rem; }
+  .breakdown-row { display: flex; justify-content: space-between; padding: 0.15rem 0; }
+  .breakdown-label { color: #555; }
+  .breakdown-value { font-family: monospace; color: #333; }
+  .chunks-toggle { font-size: 0.8rem; color: #4361ee; cursor: pointer; margin-top: 0.5rem; border: none; background: none; padding: 0; text-decoration: underline; }
+  .chunks { margin-top: 0.5rem; padding-left: 1rem; border-left: 3px solid #e0e0e0; }
+  .chunk { margin-bottom: 0.5rem; font-size: 0.85rem; }
+  .chunk-heading { font-size: 0.78rem; color: #4361ee; margin-bottom: 0.15rem; }
+  .chunk-score { font-size: 0.75rem; color: #999; }
+  .chunk-snippet { color: #555; line-height: 1.4; }
+  .empty { text-align: center; padding: 3rem; color: #999; }
+  .loading { text-align: center; padding: 2rem; color: #999; }
+  .hidden { display: none; }
+
+  /* Ranking Tuner */
+  .tuner { margin-bottom: 1.5rem; border: 1px solid #e0e0e0; border-radius: 8px; background: #fff; }
+  .tuner > summary { padding: 0.75rem 1rem; font-weight: 600; font-size: 0.95rem; cursor: pointer; color: #16213e; user-select: none; }
+  .tuner > summary:hover { color: #4361ee; }
+  .tuner-body { padding: 0.5rem 1rem 1rem; }
+  .tuner-actions { display: flex; gap: 0.5rem; margin-bottom: 0.75rem; }
+  .tuner-actions button { padding: 0.35rem 0.75rem; font-size: 0.8rem; border: 1px solid #ccc; border-radius: 4px; background: #fff; cursor: pointer; color: #555; }
+  .tuner-actions button:hover { border-color: #4361ee; color: #4361ee; }
+  .tuner-group { margin-bottom: 0.5rem; border: 1px solid #eee; border-radius: 6px; }
+  .tuner-group > summary { padding: 0.5rem 0.75rem; font-size: 0.85rem; font-weight: 600; cursor: pointer; color: #444; user-select: none; }
+  .tuner-group[open] { margin-bottom: 0.75rem; }
+  .tuner-group-body { padding: 0.25rem 0.75rem 0.5rem; }
+  .tuner-row { display: grid; grid-template-columns: 140px 1fr 70px 24px; gap: 8px; align-items: center; margin-bottom: 0.35rem; }
+  .tuner-row label { font-size: 0.8rem; color: #555; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .tuner-row label.modified { color: #4361ee; font-weight: 600; }
+  .tuner-row input[type="range"] { width: 100%; height: 6px; cursor: pointer; }
+  .tuner-row input[type="number"] { width: 70px; padding: 0.2rem 0.35rem; font-size: 0.8rem; border: 1px solid #ccc; border-radius: 4px; text-align: right; }
+  .tuner-row input[type="checkbox"] { width: 16px; height: 16px; cursor: pointer; }
+  .tuner-row .reset-btn { width: 20px; height: 20px; border: none; background: none; cursor: pointer; color: #999; font-size: 1rem; padding: 0; line-height: 1; visibility: hidden; }
+  .tuner-row .reset-btn.visible { visibility: visible; }
+  .tuner-row .reset-btn:hover { color: #4361ee; }
+  .tuner-bool-row { display: grid; grid-template-columns: 140px 1fr 24px; gap: 8px; align-items: center; margin-bottom: 0.35rem; }
+  .tuner-bool-row label { font-size: 0.8rem; color: #555; }
+  .tuner-bool-row label.modified { color: #4361ee; font-weight: 600; }
+  .tuner-bool-row .reset-btn { width: 20px; height: 20px; border: none; background: none; cursor: pointer; color: #999; font-size: 1rem; padding: 0; line-height: 1; visibility: hidden; }
+  .tuner-bool-row .reset-btn.visible { visibility: visible; }
+  .tuner-export { margin-top: 0.75rem; }
+  .tuner-export textarea { width: 100%; height: 120px; font-family: monospace; font-size: 0.8rem; padding: 0.5rem; border: 1px solid #ccc; border-radius: 6px; background: #f8f9fa; resize: vertical; }
+</style>
+</head>
+<body>
+<h1>SearchSocket <span>Playground</span></h1>
+<div class="search-box">
+  <input type="text" id="q" placeholder="Type a search query..." autocomplete="off" autofocus>
+</div>
+<div class="search-opts">
+  <label>
+    Group by:
+    <select id="groupBy">
+      <option value="page">Page</option>
+      <option value="chunk">Chunk</option>
+    </select>
+  </label>
+  <label>
+    Top K:
+    <select id="topK">
+      <option value="5">5</option>
+      <option value="10" selected>10</option>
+      <option value="20">20</option>
+      <option value="50">50</option>
+    </select>
+  </label>
+</div>
+
+<details class="tuner" id="tunerPanel">
+  <summary>Ranking Tuner</summary>
+  <div class="tuner-body">
+    <div class="tuner-actions">
+      <button id="resetAll" type="button">Reset All</button>
+      <button id="exportConfig" type="button">Export Config</button>
+    </div>
+    <div id="tunerGroups"></div>
+    <div class="tuner-export hidden" id="exportArea">
+      <textarea id="exportText" readonly></textarea>
+    </div>
+  </div>
+</details>
+
+<div id="meta" class="meta"></div>
+<div id="results"></div>
+
+<script>
+(function() {
+  var qInput = document.getElementById('q');
+  var groupBySelect = document.getElementById('groupBy');
+  var topKSelect = document.getElementById('topK');
+  var resultsDiv = document.getElementById('results');
+  var metaDiv = document.getElementById('meta');
+  var tunerGroupsDiv = document.getElementById('tunerGroups');
+  var exportArea = document.getElementById('exportArea');
+  var exportText = document.getElementById('exportText');
+
+  var debounceTimer = null;
+  var requestId = 0;
+  var baselineConfig = null;
+  var tunerParams = [];
+
+  var PARAM_DEFS = [
+    { group: 'Thresholds', key: 'ranking.minScoreRatio', label: 'minScoreRatio', min: 0, max: 1, step: 0.01 },
+    { group: 'Thresholds', key: 'ranking.scoreGapThreshold', label: 'scoreGapThreshold', min: 0, max: 1, step: 0.01 },
+    { group: 'Thresholds', key: 'ranking.minChunkScoreRatio', label: 'minChunkScoreRatio', min: 0, max: 1, step: 0.01 },
+    { group: 'Boosts', key: 'ranking.enableIncomingLinkBoost', label: 'incomingLinkBoost', type: 'bool' },
+    { group: 'Boosts', key: 'ranking.enableDepthBoost', label: 'depthBoost', type: 'bool' },
+    { group: 'Weights', key: 'ranking.weights.incomingLinks', label: 'incomingLinks', min: 0, max: 1, step: 0.01 },
+    { group: 'Weights', key: 'ranking.weights.depth', label: 'depth', min: 0, max: 1, step: 0.01 },
+    { group: 'Weights', key: 'ranking.weights.aggregation', label: 'aggregation', min: 0, max: 1, step: 0.01 },
+    { group: 'Weights', key: 'ranking.weights.titleMatch', label: 'titleMatch', min: 0, max: 1, step: 0.01 },
+    { group: 'Aggregation', key: 'ranking.aggregationCap', label: 'aggregationCap', min: 1, max: 20, step: 1 },
+    { group: 'Aggregation', key: 'ranking.aggregationDecay', label: 'aggregationDecay', min: 0, max: 1, step: 0.01 },
+    { group: 'Search', key: 'search.pageSearchWeight', label: 'pageSearchWeight', min: 0, max: 1, step: 0.01 }
+  ];
+
+  function getNestedValue(obj, path) {
+    var parts = path.split('.');
+    var v = obj;
+    for (var i = 0; i < parts.length; i++) {
+      if (v == null) return undefined;
+      v = v[parts[i]];
+    }
+    return v;
+  }
+
+  function setNestedValue(obj, path, value) {
+    var parts = path.split('.');
+    var cur = obj;
+    for (var i = 0; i < parts.length - 1; i++) {
+      if (!cur[parts[i]]) cur[parts[i]] = {};
+      cur = cur[parts[i]];
+    }
+    cur[parts[parts.length - 1]] = value;
+  }
+
+  function initTuner(config) {
+    baselineConfig = config;
+    var groups = {};
+    PARAM_DEFS.forEach(function(def) {
+      if (!groups[def.group]) groups[def.group] = [];
+      groups[def.group].push(def);
+    });
+
+    var html = '';
+    Object.keys(groups).forEach(function(groupName) {
+      html += '<details class="tuner-group" open>';
+      html += '<summary>' + groupName + '</summary>';
+      html += '<div class="tuner-group-body">';
+      groups[groupName].forEach(function(def) {
+        var val = getNestedValue(config, def.key);
+        if (def.type === 'bool') {
+          html += '<div class="tuner-bool-row" data-key="' + def.key + '">';
+          html += '<label>' + def.label + '</label>';
+          html += '<input type="checkbox"' + (val ? ' checked' : '') + ' data-param="' + def.key + '">';
+          html += '<button class="reset-btn" title="Reset" data-reset="' + def.key + '">\\u21BA</button>';
+          html += '</div>';
+        } else {
+          html += '<div class="tuner-row" data-key="' + def.key + '">';
+          html += '<label>' + def.label + '</label>';
+          html += '<input type="range" min="' + def.min + '" max="' + def.max + '" step="' + def.step + '" value="' + val + '" data-param="' + def.key + '">';
+          html += '<input type="number" min="' + def.min + '" max="' + def.max + '" step="' + def.step + '" value="' + val + '" data-num="' + def.key + '">';
+          html += '<button class="reset-btn" title="Reset" data-reset="' + def.key + '">\\u21BA</button>';
+          html += '</div>';
+        }
+      });
+      html += '</div></details>';
+    });
+    tunerGroupsDiv.innerHTML = html;
+
+    // Wire events
+    tunerGroupsDiv.addEventListener('input', function(e) {
+      var param = e.target.getAttribute('data-param');
+      var num = e.target.getAttribute('data-num');
+      if (param) {
+        // Slider or checkbox changed \u2014 sync number input
+        var row = e.target.closest('[data-key]');
+        if (row && e.target.type === 'range') {
+          var numInput = row.querySelector('[data-num]');
+          if (numInput) numInput.value = e.target.value;
+        }
+        updateModifiedState(param);
+        scheduleSearch();
+      } else if (num) {
+        // Number input changed \u2014 sync slider
+        var row = e.target.closest('[data-key]');
+        if (row) {
+          var rangeInput = row.querySelector('[data-param]');
+          if (rangeInput) rangeInput.value = e.target.value;
+        }
+        updateModifiedState(num);
+        scheduleSearch();
+      }
+    });
+
+    tunerGroupsDiv.addEventListener('change', function(e) {
+      var param = e.target.getAttribute('data-param');
+      if (param && e.target.type === 'checkbox') {
+        updateModifiedState(param);
+        scheduleSearch();
+      }
+    });
+
+    tunerGroupsDiv.addEventListener('click', function(e) {
+      var resetKey = e.target.getAttribute('data-reset');
+      if (resetKey) {
+        resetParam(resetKey);
+        scheduleSearch();
+      }
+    });
+  }
+
+  function updateModifiedState(key) {
+    var baseline = getNestedValue(baselineConfig, key);
+    var row = tunerGroupsDiv.querySelector('[data-key="' + key + '"]');
+    if (!row) return;
+    var input = row.querySelector('[data-param="' + key + '"]');
+    if (!input) return;
+    var current = input.type === 'checkbox' ? input.checked : parseFloat(input.value);
+    var isModified = current !== baseline;
+    var label = row.querySelector('label');
+    var resetBtn = row.querySelector('.reset-btn');
+    if (label) label.classList.toggle('modified', isModified);
+    if (resetBtn) resetBtn.classList.toggle('visible', isModified);
+  }
+
+  function resetParam(key) {
+    var baseline = getNestedValue(baselineConfig, key);
+    var row = tunerGroupsDiv.querySelector('[data-key="' + key + '"]');
+    if (!row) return;
+    var input = row.querySelector('[data-param="' + key + '"]');
+    if (!input) return;
+    if (input.type === 'checkbox') {
+      input.checked = baseline;
+    } else {
+      input.value = baseline;
+      var numInput = row.querySelector('[data-num]');
+      if (numInput) numInput.value = baseline;
+    }
+    updateModifiedState(key);
+  }
+
+  function resetAll() {
+    PARAM_DEFS.forEach(function(def) {
+      resetParam(def.key);
+    });
+    exportArea.classList.add('hidden');
+    scheduleSearch();
+  }
+
+  function collectOverrides() {
+    var overrides = {};
+    PARAM_DEFS.forEach(function(def) {
+      var row = tunerGroupsDiv.querySelector('[data-key="' + def.key + '"]');
+      if (!row) return;
+      var input = row.querySelector('[data-param="' + def.key + '"]');
+      if (!input) return;
+      var val = def.type === 'bool' ? input.checked : parseFloat(input.value);
+      setNestedValue(overrides, def.key, val);
+    });
+    return overrides;
+  }
+
+  function collectChangedOverrides() {
+    var overrides = {};
+    var hasChanges = false;
+    PARAM_DEFS.forEach(function(def) {
+      var row = tunerGroupsDiv.querySelector('[data-key="' + def.key + '"]');
+      if (!row) return;
+      var input = row.querySelector('[data-param="' + def.key + '"]');
+      if (!input) return;
+      var current = def.type === 'bool' ? input.checked : parseFloat(input.value);
+      var baseline = getNestedValue(baselineConfig, def.key);
+      if (current !== baseline) {
+        setNestedValue(overrides, def.key, current);
+        hasChanges = true;
+      }
+    });
+    return hasChanges ? overrides : null;
+  }
+
+  function exportConfig() {
+    var changed = collectChangedOverrides();
+    if (!changed) {
+      exportArea.classList.remove('hidden');
+      exportText.value = '// No parameters have been changed from defaults.';
+      return;
+    }
+
+    var lines = [];
+    if (changed.ranking) {
+      lines.push('ranking: {');
+      var r = changed.ranking;
+      var simpleKeys = ['enableIncomingLinkBoost', 'enableDepthBoost', 'aggregationCap', 'aggregationDecay', 'minChunkScoreRatio', 'minScoreRatio', 'scoreGapThreshold'];
+      simpleKeys.forEach(function(k) {
+        if (r[k] !== undefined) lines.push('  ' + k + ': ' + JSON.stringify(r[k]) + ',');
+      });
+      if (r.weights) {
+        lines.push('  weights: {');
+        Object.keys(r.weights).forEach(function(wk) {
+          lines.push('    ' + wk + ': ' + r.weights[wk] + ',');
+        });
+        lines.push('  },');
+      }
+      lines.push('},');
+    }
+    if (changed.search) {
+      lines.push('search: {');
+      Object.keys(changed.search).forEach(function(sk) {
+        lines.push('  ' + sk + ': ' + changed.search[sk] + ',');
+      });
+      lines.push('},');
+    }
+
+    exportArea.classList.remove('hidden');
+    exportText.value = lines.join('\\n');
+  }
+
+  // Read initial state from URL
+  var params = new URLSearchParams(window.location.search);
+  if (params.get('q')) qInput.value = params.get('q');
+  if (params.get('groupBy')) groupBySelect.value = params.get('groupBy');
+  if (params.get('topK')) topKSelect.value = params.get('topK');
+
+  function updateUrl() {
+    var p = new URLSearchParams();
+    if (qInput.value) p.set('q', qInput.value);
+    if (groupBySelect.value !== 'page') p.set('groupBy', groupBySelect.value);
+    if (topKSelect.value !== '10') p.set('topK', topKSelect.value);
+    var qs = p.toString();
+    history.replaceState(null, '', qs ? '?' + qs : window.location.pathname);
+  }
+
+  function doSearch() {
+    var query = qInput.value.trim();
+    updateUrl();
+    if (!query) {
+      resultsDiv.innerHTML = '<div class="empty">Enter a query to search</div>';
+      metaDiv.textContent = '';
+      return;
+    }
+
+    resultsDiv.innerHTML = '<div class="loading">Searching...</div>';
+
+    var thisRequestId = ++requestId;
+    var body = {
+      q: query,
+      topK: parseInt(topKSelect.value, 10),
+      groupBy: groupBySelect.value,
+      debug: true
+    };
+
+    if (baselineConfig) {
+      body.rankingOverrides = collectOverrides();
+    }
+
+    fetch('/_searchsocket/search', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    }).then(function(res) {
+      if (thisRequestId !== requestId) return;
+      if (!res.ok) {
+        return res.text().then(function(err) {
+          resultsDiv.innerHTML = '<div class="empty">Error: ' + escapeHtml(err) + '</div>';
+        });
+      }
+      return res.json().then(function(data) {
+        if (thisRequestId !== requestId) return;
+        renderResults(data);
+      });
+    }).catch(function(err) {
+      if (thisRequestId !== requestId) return;
+      resultsDiv.innerHTML = '<div class="empty">Network error: ' + escapeHtml(err.message) + '</div>';
+    });
+  }
+
+  function escapeHtml(str) {
+    var d = document.createElement('div');
+    d.textContent = str;
+    return d.innerHTML;
+  }
+
+  function renderResults(data) {
+    metaDiv.textContent = data.results.length + ' results in ' + data.meta.timingsMs.total + 'ms (search: ' + data.meta.timingsMs.search + 'ms) \\u2014 scope: ' + data.scope;
+
+    if (data.results.length === 0) {
+      resultsDiv.innerHTML = '<div class="empty">No results found</div>';
+      return;
+    }
+
+    resultsDiv.innerHTML = data.results.map(function(r, i) {
+      var html = '<div class="result">';
+      html += '<div class="result-header">';
+      html += '<div><div class="result-title">' + escapeHtml(r.title) + '</div>';
+      html += '<div class="result-url">' + escapeHtml(r.url) + '</div></div>';
+      html += '<div class="result-score">' + r.score.toFixed(4) + '</div>';
+      html += '</div>';
+
+      if (r.snippet) {
+        html += '<div class="result-snippet">' + escapeHtml(r.snippet) + '</div>';
+      }
+
+      html += '<div class="result-meta">';
+      html += '<span>route: ' + escapeHtml(r.routeFile) + '</span>';
+      if (r.sectionTitle) html += '<span>section: ' + escapeHtml(r.sectionTitle) + '</span>';
+      html += '</div>';
+
+      if (r.breakdown) {
+        html += '<div class="breakdown">';
+        html += '<div class="breakdown-row"><span class="breakdown-label">Base score</span><span class="breakdown-value">' + r.breakdown.baseScore.toFixed(6) + '</span></div>';
+        html += '<div class="breakdown-row"><span class="breakdown-label">Incoming link boost</span><span class="breakdown-value">' + r.breakdown.incomingLinkBoost.toFixed(6) + '</span></div>';
+        html += '<div class="breakdown-row"><span class="breakdown-label">Depth boost</span><span class="breakdown-value">' + r.breakdown.depthBoost.toFixed(6) + '</span></div>';
+        html += '<div class="breakdown-row"><span class="breakdown-label">Title match boost</span><span class="breakdown-value">' + r.breakdown.titleMatchBoost.toFixed(6) + '</span></div>';
+        html += '<div class="breakdown-row"><span class="breakdown-label">Anchor text boost</span><span class="breakdown-value">' + (r.breakdown.anchorTextMatchBoost || 0).toFixed(6) + '</span></div>';
+        html += '</div>';
+      }
+
+      if (r.chunks && r.chunks.length > 0) {
+        html += '<button class="chunks-toggle" data-idx="' + i + '">Show ' + r.chunks.length + ' chunks</button>';
+        html += '<div class="chunks hidden" id="chunks-' + i + '">';
+        r.chunks.forEach(function(c) {
+          html += '<div class="chunk">';
+          if (c.headingPath && c.headingPath.length > 0) {
+            html += '<div class="chunk-heading">' + escapeHtml(c.headingPath.join(' > ')) + '</div>';
+          }
+          if (c.sectionTitle) {
+            html += '<div class="chunk-heading">' + escapeHtml(c.sectionTitle) + '</div>';
+          }
+          html += '<div class="chunk-snippet">' + escapeHtml(c.snippet) + '</div>';
+          html += '<div class="chunk-score">score: ' + c.score.toFixed(4) + '</div>';
+          html += '</div>';
+        });
+        html += '</div>';
+      }
+
+      html += '</div>';
+      return html;
+    }).join('');
+  }
+
+  resultsDiv.addEventListener('click', function(e) {
+    if (e.target.classList.contains('chunks-toggle')) {
+      var idx = e.target.getAttribute('data-idx');
+      var chunksDiv = document.getElementById('chunks-' + idx);
+      if (chunksDiv) {
+        chunksDiv.classList.toggle('hidden');
+        e.target.textContent = chunksDiv.classList.contains('hidden')
+          ? 'Show ' + chunksDiv.children.length + ' chunks'
+          : 'Hide chunks';
+      }
+    }
+  });
+
+  function scheduleSearch() {
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(doSearch, 300);
+  }
+
+  qInput.addEventListener('input', scheduleSearch);
+  groupBySelect.addEventListener('change', scheduleSearch);
+  topKSelect.addEventListener('change', scheduleSearch);
+
+  document.getElementById('resetAll').addEventListener('click', resetAll);
+  document.getElementById('exportConfig').addEventListener('click', exportConfig);
+
+  // Fetch config and initialize tuner
+  fetch('/_searchsocket/config').then(function(res) {
+    if (res.ok) return res.json();
+    return null;
+  }).then(function(config) {
+    if (config) initTuner(config);
+  }).catch(function() {
+    // Config endpoint not available \u2014 tuner stays empty
+  });
+
+  // Trigger initial search if query is present
+  if (qInput.value.trim()) doSearch();
+})();
+</script>
+</body>
+</html>
+`;
+
+// src/playground/server.ts
+async function runPlaygroundServer(options) {
+  const config = options.config ?? await loadConfig({
+    cwd: options.cwd,
+    configPath: options.configPath
+  });
+  let enginePromise = null;
+  function getEngine() {
+    if (!enginePromise) {
+      enginePromise = SearchEngine.create({
+        cwd: options.cwd,
+        configPath: options.configPath,
+        config
+      });
+    }
+    return enginePromise;
+  }
+  const app = express();
+  app.use(express.json());
+  app.get("/_searchsocket", (_req, res) => {
+    res.type("html").send(playground_default);
+  });
+  app.get("/_searchsocket/config", (_req, res) => {
+    res.json({
+      ranking: {
+        enableIncomingLinkBoost: config.ranking.enableIncomingLinkBoost,
+        enableDepthBoost: config.ranking.enableDepthBoost,
+        aggregationCap: config.ranking.aggregationCap,
+        aggregationDecay: config.ranking.aggregationDecay,
+        minChunkScoreRatio: config.ranking.minChunkScoreRatio,
+        minScoreRatio: config.ranking.minScoreRatio,
+        scoreGapThreshold: config.ranking.scoreGapThreshold,
+        weights: { ...config.ranking.weights }
+      },
+      search: {
+        pageSearchWeight: config.search.pageSearchWeight
+      }
+    });
+  });
+  app.post("/_searchsocket/search", async (req, res) => {
+    try {
+      const searchEngine = await getEngine();
+      const body = req.body;
+      if (!body || typeof body.q !== "string" || body.q.trim().length === 0) {
+        res.status(400).json({ error: "Missing or empty 'q' field" });
+        return;
+      }
+      const result = await searchEngine.search({
+        q: body.q,
+        topK: typeof body.topK === "number" ? body.topK : void 0,
+        scope: typeof body.scope === "string" ? body.scope : void 0,
+        pathPrefix: typeof body.pathPrefix === "string" ? body.pathPrefix : void 0,
+        tags: Array.isArray(body.tags) ? body.tags : void 0,
+        groupBy: body.groupBy === "page" || body.groupBy === "chunk" ? body.groupBy : void 0,
+        debug: body.debug === true,
+        rankingOverrides: body.rankingOverrides && typeof body.rankingOverrides === "object" ? body.rankingOverrides : void 0
       });
+      res.json(result);
     } catch (error) {
-      if (!res.headersSent) {
-        res.status(500).json({
-          jsonrpc: "2.0",
-          error: {
-            code: -32603,
-            message: error instanceof Error ? error.message : "Internal server error"
-          },
-          id: null
-        });
-      }
+      const message = error instanceof Error ? error.message : "Internal server error";
+      const status = error.statusCode ?? 500;
+      res.status(status).json({ error: message });
     }
   });
-  app.get(endpointPath, (_req, res) => {
-    res.writeHead(405).end(
-      JSON.stringify({
-        jsonrpc: "2.0",
-        error: {
-          code: -32e3,
-          message: "Method not allowed"
-        },
-        id: null
-      })
-    );
-  });
-  app.delete(endpointPath, (_req, res) => {
-    res.writeHead(405).end(
-      JSON.stringify({
-        jsonrpc: "2.0",
-        error: {
-          code: -32e3,
-          message: "Method not allowed"
-        },
-        id: null
-      })
-    );
-  });
-  await new Promise((resolve, reject) => {
-    const instance = app.listen(port, "127.0.0.1", () => {
-      process.stderr.write(`SearchSocket MCP HTTP server listening on http://127.0.0.1:${port}${endpointPath}
-`);
-      resolve();
+  const preferredPort = options.port ?? 3337;
+  function startServer(port) {
+    return new Promise((resolve, reject) => {
+      let httpServer;
+      const onListening = () => {
+        const addr = httpServer.address();
+        resolve({
+          port: addr.port,
+          close: () => new Promise((r) => httpServer.close(() => r()))
+        });
+      };
+      httpServer = app.listen(port, "127.0.0.1", onListening);
+      httpServer.once("error", (err) => {
+        if (err.code === "EADDRINUSE" && port !== 0) {
+          startServer(0).then(resolve, reject);
+        } else {
+          reject(err);
+        }
+      });
     });
-    instance.once("error", reject);
-    process.on("SIGINT", async () => {
-      await new Promise((shutdownResolve) => instance.close(() => shutdownResolve()));
-      process.exit(0);
+  }
+  return startServer(preferredPort);
+}
+
+// src/search/quality-metrics.ts
+function reciprocalRank(results, relevant) {
+  const set = new Set(relevant);
+  for (let i = 0; i < results.length; i++) {
+    if (set.has(results[i].url)) {
+      return 1 / (i + 1);
+    }
+  }
+  return 0;
+}
+function mrr(queries) {
+  if (queries.length === 0) return 0;
+  const sum = queries.reduce((acc, q) => acc + reciprocalRank(q.results, q.relevant), 0);
+  return sum / queries.length;
+}
+
+// src/cli/test-schemas.ts
+import { z as z4 } from "zod";
+var testCaseSchema = z4.object({
+  query: z4.string().min(1),
+  expect: z4.object({
+    topResult: z4.string().optional(),
+    inTop5: z4.array(z4.string()).min(1).optional(),
+    maxResults: z4.number().int().nonnegative().optional()
+  }).refine(
+    (e) => e.topResult !== void 0 || e.inTop5 !== void 0 || e.maxResults !== void 0,
+    { message: "expect must contain at least one of topResult, inTop5, or maxResults" }
+  )
+});
+var testFileSchema = z4.array(testCaseSchema).min(1, "test file must contain at least one test case");
+
+// src/cli.ts
+import * as clack from "@clack/prompts";
+
+// src/init-helpers.ts
+import fs9 from "fs";
+import path13 from "path";
+import { parseModule, generateCode, builders } from "magicast";
+function ensureMcpJson(cwd) {
+  const mcpPath = path13.join(cwd, ".mcp.json");
+  const entry = {
+    command: "npx",
+    args: ["searchsocket", "mcp"],
+    env: {
+      UPSTASH_VECTOR_REST_URL: "${UPSTASH_VECTOR_REST_URL}",
+      UPSTASH_VECTOR_REST_TOKEN: "${UPSTASH_VECTOR_REST_TOKEN}"
+    }
+  };
+  let existing = {};
+  if (fs9.existsSync(mcpPath)) {
+    try {
+      const raw = fs9.readFileSync(mcpPath, "utf8");
+      existing = JSON.parse(raw);
+    } catch {
+      process.stderr.write("warning: .mcp.json exists but could not be parsed \u2014 skipping\n");
+      return;
+    }
+  }
+  const raw_servers = existing.mcpServers ?? {};
+  const servers = typeof raw_servers === "object" && !Array.isArray(raw_servers) ? raw_servers : {};
+  if (JSON.stringify(servers["searchsocket"]) === JSON.stringify(entry)) {
+    return;
+  }
+  existing.mcpServers = { ...servers, searchsocket: entry };
+  fs9.writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+}
+var HOOKS_SNIPPET = `import { searchsocketHandle } from "searchsocket/sveltekit";
+
+export const handle = searchsocketHandle();`;
+var VITE_PLUGIN_SNIPPET = `import { searchsocketVitePlugin } from "searchsocket/sveltekit";
+
+// Add to your Vite config plugins array:
+// plugins: [sveltekit(), searchsocketVitePlugin()]`;
+function injectHooksServerTs(cwd) {
+  const hooksDir = path13.join(cwd, "src");
+  const tsPath = path13.join(hooksDir, "hooks.server.ts");
+  const jsPath = path13.join(hooksDir, "hooks.server.js");
+  const hooksPath = fs9.existsSync(tsPath) ? tsPath : fs9.existsSync(jsPath) ? jsPath : null;
+  if (!hooksPath) {
+    fs9.mkdirSync(hooksDir, { recursive: true });
+    fs9.writeFileSync(tsPath, HOOKS_SNIPPET + "\n", "utf8");
+    return "created";
+  }
+  const original = fs9.readFileSync(hooksPath, "utf8");
+  if (original.includes("searchsocketHandle")) {
+    return "already-present";
+  }
+  try {
+    const mod = parseModule(original);
+    mod.imports.$append({
+      from: "searchsocket/sveltekit",
+      imported: "searchsocketHandle"
     });
-  });
+    if (mod.exports.handle) {
+      mod.imports.$append({
+        from: "@sveltejs/kit/hooks",
+        imported: "sequence"
+      });
+      const existingHandle = mod.exports.handle;
+      mod.exports.handle = builders.functionCall(
+        "sequence",
+        builders.functionCall("searchsocketHandle"),
+        existingHandle
+      );
+      const { code: code2 } = generateCode(mod);
+      fs9.writeFileSync(hooksPath, code2, "utf8");
+      return "composed";
+    }
+    mod.exports.handle = builders.functionCall("searchsocketHandle");
+    const { code } = generateCode(mod);
+    fs9.writeFileSync(hooksPath, code, "utf8");
+    return "injected";
+  } catch {
+    return "fallback";
+  }
 }
-async function runMcpServer(options = {}) {
-  const config = await loadConfig({
-    cwd: options.cwd,
-    configPath: options.configPath
-  });
-  const resolvedTransport = options.transport ?? config.mcp.transport;
-  if (resolvedTransport === "stdio") {
-    redirectConsoleToStderr();
+function injectViteConfig(cwd) {
+  const tsPath = path13.join(cwd, "vite.config.ts");
+  const jsPath = path13.join(cwd, "vite.config.js");
+  const configPath = fs9.existsSync(tsPath) ? tsPath : fs9.existsSync(jsPath) ? jsPath : null;
+  if (!configPath) {
+    return "no-config";
   }
-  const engine = await SearchEngine.create({
-    cwd: options.cwd,
-    configPath: options.configPath,
-    config
-  });
-  if (resolvedTransport === "http") {
-    await startHttpServer(() => createServer(engine), config, options);
+  const original = fs9.readFileSync(configPath, "utf8");
+  if (original.includes("searchsocketVitePlugin")) {
+    return "already-present";
+  }
+  try {
+    const mod = parseModule(original);
+    mod.imports.$append({
+      from: "searchsocket/sveltekit",
+      imported: "searchsocketVitePlugin"
+    });
+    let config = mod.exports.default;
+    if (!config) {
+      return "fallback";
+    }
+    if (config.$type === "function-call") {
+      config = config.$args[0];
+    }
+    if (!config.plugins) {
+      config.plugins = [builders.functionCall("searchsocketVitePlugin")];
+    } else {
+      config.plugins.push(builders.functionCall("searchsocketVitePlugin"));
+    }
+    const { code } = generateCode(mod);
+    fs9.writeFileSync(configPath, code, "utf8");
+    return "injected";
+  } catch {
+    return "fallback";
+  }
+}
+function writeEnvFile(cwd, url, token) {
+  const envPath = path13.join(cwd, ".env");
+  let content = "";
+  if (fs9.existsSync(envPath)) {
+    content = fs9.readFileSync(envPath, "utf8");
+  }
+  const lines = [];
+  if (!content.includes("UPSTASH_VECTOR_REST_URL=")) {
+    lines.push(`UPSTASH_VECTOR_REST_URL=${url}`);
+  }
+  if (!content.includes("UPSTASH_VECTOR_REST_TOKEN=")) {
+    lines.push(`UPSTASH_VECTOR_REST_TOKEN=${token}`);
+  }
+  if (lines.length > 0) {
+    const suffix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    fs9.writeFileSync(envPath, content + suffix + lines.join("\n") + "\n", "utf8");
+  }
+  ensureGitignoreEntry(cwd, ".env");
+}
+function ensureGitignoreEntry(cwd, entry) {
+  const gitignorePath = path13.join(cwd, ".gitignore");
+  let content = "";
+  if (fs9.existsSync(gitignorePath)) {
+    content = fs9.readFileSync(gitignorePath, "utf8");
+  }
+  const lines = content.split("\n");
+  if (lines.some((line) => line.trim() === entry)) {
     return;
   }
-  const server = createServer(engine);
-  const stdioTransport = new StdioServerTransport();
-  await server.connect(stdioTransport);
+  const suffix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  fs9.writeFileSync(gitignorePath, content + suffix + entry + "\n", "utf8");
+}
+
+// src/add-helpers.ts
+import fs10 from "fs";
+import fsp from "fs/promises";
+import path14 from "path";
+import { fileURLToPath } from "url";
+var __dirname = path14.dirname(fileURLToPath(import.meta.url));
+var AVAILABLE_COMPONENTS = ["search-dialog", "search-input", "search-results"];
+function resolveTemplateDir() {
+  return path14.resolve(__dirname, "templates");
+}
+function listAvailableComponents() {
+  return [...AVAILABLE_COMPONENTS];
+}
+function isValidComponent(name) {
+  return AVAILABLE_COMPONENTS.includes(name);
+}
+async function copyComponent(name, targetDir, options = {}) {
+  const templateDir = path14.join(resolveTemplateDir(), name);
+  if (!fs10.existsSync(templateDir)) {
+    throw new Error(
+      `Template directory not found: ${templateDir}. Run "pnpm run build" to generate templates.`
+    );
+  }
+  const entries = await fsp.readdir(templateDir);
+  const svelteFiles = entries.filter((f) => f.endsWith(".svelte"));
+  if (svelteFiles.length === 0) {
+    throw new Error(`No .svelte files found in template: ${name}`);
+  }
+  await fsp.mkdir(targetDir, { recursive: true });
+  const written = [];
+  const skipped = [];
+  for (const file of svelteFiles) {
+    const dest = path14.join(targetDir, file);
+    if (fs10.existsSync(dest) && !options.overwrite) {
+      skipped.push(dest);
+      continue;
+    }
+    await fsp.copyFile(path14.join(templateDir, file), dest);
+    written.push(dest);
+  }
+  return { written, skipped };
 }
 
 // src/cli.ts
@@ -3117,6 +5587,10 @@ function parseDurationMs(value) {
 }
 function printIndexSummary(stats) {
   process.stdout.write(`pages processed: ${stats.pagesProcessed}
+`);
+  process.stdout.write(`pages changed: ${stats.pagesChanged}
+`);
+  process.stdout.write(`pages deleted: ${stats.pagesDeleted}
 `);
   process.stdout.write(`chunks total: ${stats.chunksTotal}
 `);
@@ -3138,7 +5612,7 @@ function collectWatchPaths(config, cwd) {
   const paths = ["src/routes/**"];
   if (config.source.mode === "content-files" && config.source.contentFiles) {
     for (const pattern of config.source.contentFiles.globs) {
-      paths.push(path12.join(config.source.contentFiles.baseDir, pattern));
+      paths.push(path15.join(config.source.contentFiles.baseDir, pattern));
     }
   }
   if (config.source.mode === "static-output") {
@@ -3151,22 +5625,22 @@ function collectWatchPaths(config, cwd) {
     paths.push("searchsocket.config.ts");
     paths.push(config.source.build.outputDir);
   }
-  return paths.map((value) => path12.resolve(cwd, value));
+  return paths.map((value) => path15.resolve(cwd, value));
 }
 function ensureStateDir(cwd) {
-  const target = path12.join(cwd, ".searchsocket");
-  fs8.mkdirSync(target, { recursive: true });
+  const target = path15.join(cwd, ".searchsocket");
+  fs11.mkdirSync(target, { recursive: true });
   return target;
 }
 function ensureGitignore(cwd) {
-  const gitignorePath = path12.join(cwd, ".gitignore");
+  const gitignorePath = path15.join(cwd, ".gitignore");
   const entries = [
     ".searchsocket/manifest.json",
     ".searchsocket/registry.json"
   ];
   let content = "";
-  if (fs8.existsSync(gitignorePath)) {
-    content = fs8.readFileSync(gitignorePath, "utf8");
+  if (fs11.existsSync(gitignorePath)) {
+    content = fs11.readFileSync(gitignorePath, "utf8");
   }
   const lines = content.split("\n");
   const missing = entries.filter((entry) => !lines.some((line) => line.trim() === entry));
@@ -3177,10 +5651,10 @@ function ensureGitignore(cwd) {
 # SearchSocket local state
 ${missing.join("\n")}
 `;
-  fs8.writeFileSync(gitignorePath, content.trimEnd() + block, "utf8");
+  fs11.writeFileSync(gitignorePath, content.trimEnd() + block, "utf8");
 }
 function readScopesFromFile(filePath) {
-  const raw = fs8.readFileSync(filePath, "utf8");
+  const raw = fs11.readFileSync(filePath, "utf8");
   return new Set(
     raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
   );
@@ -3204,8 +5678,8 @@ function readRemoteGitBranches(cwd) {
   }
 }
 async function loadResolvedConfigForDev(cwd, configPath) {
-  const resolvedConfigPath = path12.resolve(cwd, configPath ?? "searchsocket.config.ts");
-  if (fs8.existsSync(resolvedConfigPath)) {
+  const resolvedConfigPath = path15.resolve(cwd, configPath ?? "searchsocket.config.ts");
+  if (fs11.existsSync(resolvedConfigPath)) {
     return loadConfig({ cwd, configPath });
   }
   return mergeConfig(cwd, {});
@@ -3248,31 +5722,157 @@ async function runIndexCommand(opts) {
     printIndexSummary(stats);
   }
 }
-var program = new Command();
-program.name("searchsocket").description("Semantic site search and MCP retrieval for SvelteKit").version(package_default.version).option("-C, --cwd <path>", "working directory", process.cwd()).option("--config <path>", "config path (defaults to searchsocket.config.ts)");
-program.command("init").description("Create searchsocket.config.ts and .searchsocket state directory").action(async (_opts, command) => {
-  const root = getRootOptions(command).cwd ?? process.cwd();
-  const cwd = path12.resolve(root);
+async function runInteractiveInit(cwd) {
+  clack.intro("searchsocket setup");
+  const s = clack.spinner();
+  s.start("Creating config files");
+  const configPath = writeMinimalConfig(cwd);
+  ensureStateDir(cwd);
+  ensureGitignore(cwd);
+  ensureMcpJson(cwd);
+  s.stop("Config files created");
+  const hasUrl = Boolean(process.env.UPSTASH_VECTOR_REST_URL);
+  const hasToken = Boolean(process.env.UPSTASH_VECTOR_REST_TOKEN);
+  if (!hasUrl || !hasToken) {
+    clack.log.warn("Upstash Search credentials not found in environment.");
+    const shouldConfigure = await clack.confirm({
+      message: "Would you like to configure Upstash credentials now?",
+      initialValue: true
+    });
+    if (clack.isCancel(shouldConfigure)) {
+      clack.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    if (shouldConfigure) {
+      const url = hasUrl ? process.env.UPSTASH_VECTOR_REST_URL : await clack.text({
+        message: "Upstash Search REST URL:",
+        placeholder: "https://your-index.upstash.io",
+        validate: (v) => !v ? "URL is required" : void 0
+      });
+      if (clack.isCancel(url)) {
+        clack.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+      const token = hasToken ? process.env.UPSTASH_VECTOR_REST_TOKEN : await clack.text({
+        message: "Upstash Search REST Token:",
+        placeholder: "AX...",
+        validate: (v) => !v ? "Token is required" : void 0
+      });
+      if (clack.isCancel(token)) {
+        clack.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+      writeEnvFile(cwd, url, token);
+      clack.log.success("Credentials written to .env");
+    }
+  } else {
+    clack.log.success("Upstash credentials found in environment.");
+  }
+  s.start("Configuring hooks.server.ts");
+  const hookResult = injectHooksServerTs(cwd);
+  s.stop("hooks.server.ts configured");
+  switch (hookResult) {
+    case "created":
+      clack.log.success("Created src/hooks.server.ts with searchsocketHandle.");
+      break;
+    case "injected":
+      clack.log.success("Added searchsocketHandle to src/hooks.server.ts.");
+      break;
+    case "composed":
+      clack.log.success("Composed searchsocketHandle with existing handle using sequence().");
+      break;
+    case "already-present":
+      clack.log.info("searchsocketHandle already configured in hooks.server.ts.");
+      break;
+    case "fallback":
+      clack.log.warn("Could not auto-inject hooks.server.ts. Add manually:");
+      clack.log.message(HOOKS_SNIPPET);
+      break;
+  }
+  s.start("Configuring Vite plugin");
+  const viteResult = injectViteConfig(cwd);
+  s.stop("Vite plugin configured");
+  switch (viteResult) {
+    case "injected":
+      clack.log.success("Added searchsocketVitePlugin to Vite config.");
+      break;
+    case "already-present":
+      clack.log.info("searchsocketVitePlugin already in Vite config.");
+      break;
+    case "no-config":
+      clack.log.warn("No vite.config.ts/js found. Add the plugin manually:");
+      clack.log.message(VITE_PLUGIN_SNIPPET);
+      break;
+    case "fallback":
+      clack.log.warn("Could not auto-inject Vite config. Add manually:");
+      clack.log.message(VITE_PLUGIN_SNIPPET);
+      break;
+  }
+  clack.log.info("Run `searchsocket doctor` to verify your setup.");
+  clack.outro("SearchSocket initialized! Run `searchsocket index` to index your site.");
+}
+async function runSilentInit(cwd) {
   const configPath = writeMinimalConfig(cwd);
   const stateDir = ensureStateDir(cwd);
   ensureGitignore(cwd);
+  ensureMcpJson(cwd);
   process.stdout.write(`created/verified config: ${configPath}
 `);
   process.stdout.write(`created/verified state dir: ${stateDir}
-
 `);
-  process.stdout.write("SvelteKit hook snippet:\n\n");
-  process.stdout.write('import { searchsocketHandle } from "searchsocket/sveltekit";\n\n');
-  process.stdout.write("export const handle = searchsocketHandle();\n\n");
-  process.stdout.write("Optional build-triggered indexing plugin:\n\n");
-  process.stdout.write('import { searchsocketVitePlugin } from "searchsocket/sveltekit";\n\n');
-  process.stdout.write("// svelte.config.js / vite plugins:\n");
-  process.stdout.write("// searchsocketVitePlugin({ enabled: true, changedOnly: true })\n");
-  process.stdout.write("// or env-driven: SEARCHSOCKET_AUTO_INDEX=1 pnpm build\n");
+  process.stdout.write("created/verified .mcp.json (MCP server config for Claude Code)\n\n");
+  const hookResult = injectHooksServerTs(cwd);
+  switch (hookResult) {
+    case "created":
+      process.stdout.write("created src/hooks.server.ts with searchsocketHandle\n");
+      break;
+    case "injected":
+      process.stdout.write("added searchsocketHandle to src/hooks.server.ts\n");
+      break;
+    case "composed":
+      process.stdout.write("composed searchsocketHandle with existing handle via sequence()\n");
+      break;
+    case "already-present":
+      process.stdout.write("searchsocketHandle already present in hooks.server.ts\n");
+      break;
+    case "fallback":
+      process.stdout.write("could not auto-inject hooks.server.ts \u2014 add manually:\n\n");
+      process.stdout.write(HOOKS_SNIPPET + "\n\n");
+      break;
+  }
+  const viteResult = injectViteConfig(cwd);
+  switch (viteResult) {
+    case "injected":
+      process.stdout.write("added searchsocketVitePlugin to Vite config\n");
+      break;
+    case "already-present":
+      process.stdout.write("searchsocketVitePlugin already in Vite config\n");
+      break;
+    case "no-config":
+      process.stdout.write("no vite.config.ts/js found \u2014 add plugin manually:\n\n");
+      process.stdout.write(VITE_PLUGIN_SNIPPET + "\n\n");
+      break;
+    case "fallback":
+      process.stdout.write("could not auto-inject Vite config \u2014 add manually:\n\n");
+      process.stdout.write(VITE_PLUGIN_SNIPPET + "\n\n");
+      break;
+  }
+}
+var program = new Command();
+program.name("searchsocket").description("Semantic site search and MCP retrieval for SvelteKit").version(package_default.version).option("-C, --cwd <path>", "working directory", process.cwd()).option("--config <path>", "config path (defaults to searchsocket.config.ts)");
+program.command("init").description("Initialize SearchSocket in a SvelteKit project").option("--non-interactive", "skip interactive prompts").action(async (opts, command) => {
+  const root = getRootOptions(command).cwd ?? process.cwd();
+  const cwd = path15.resolve(root);
+  const isInteractive = Boolean(process.stdout.isTTY) && !opts.nonInteractive;
+  if (isInteractive) {
+    await runInteractiveInit(cwd);
+  } else {
+    await runSilentInit(cwd);
+  }
 });
 program.command("index").description("Index site content into Upstash Search").option("--scope <name>", "scope override").option("--changed-only", "only process changed chunks", true).option("--no-changed-only", "re-index regardless of previous manifest").option("--force", "force full rebuild", false).option("--dry-run", "compute plan, no writes", false).option("--source <mode>", "source mode override: static-output|crawl|content-files|build").option("--max-pages <n>", "limit pages processed").option("--max-chunks <n>", "limit chunks processed").option("--quiet", "suppress all output except errors and warnings", false).option("--verbose", "verbose output", false).option("--json", "emit JSON logs and summary", false).action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   await runIndexCommand({
     cwd,
     configPath: rootOpts?.config,
@@ -3290,7 +5890,7 @@ program.command("index").description("Index site content into Upstash Search").o
 });
 program.command("status").description("Show scope, indexing state, and backend health").option("--scope <name>", "scope override").action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const config = await loadConfig({ cwd, configPath: rootOpts?.config });
   const scope = resolveScope(config, opts.scope);
   let store;
@@ -3329,7 +5929,7 @@ program.command("status").description("Show scope, indexing state, and backend h
 `);
   process.stdout.write(`resolved scope: ${scope.scopeName}
 `);
-  process.stdout.write(`backend: upstash-search
+  process.stdout.write(`backend: upstash-vector
 `);
   process.stdout.write(`backend health: ${health.ok ? "ok" : `error (${health.details ?? "n/a"})`}
 `);
@@ -3354,19 +5954,31 @@ program.command("status").description("Show scope, indexing state, and backend h
     }
   }
 });
-program.command("dev").description("Watch content files/routes and incrementally reindex on changes").option("--scope <name>", "scope override").option("--mcp", "start MCP server (http transport) alongside watcher", false).option("--mcp-port <n>", "MCP HTTP port", "3338").option("--mcp-path <path>", "MCP HTTP path", "/mcp").option("--verbose", "verbose logs", false).action(async (opts, command) => {
+program.command("dev").description("Watch content files/routes and incrementally reindex on changes").option("--scope <name>", "scope override").option("--playground", "serve playground UI at /_searchsocket (default: true)", true).option("--no-playground", "disable playground UI").option("--playground-port <n>", "playground HTTP port", "3337").option("--mcp", "start MCP server (http transport) alongside watcher", false).option("--mcp-port <n>", "MCP HTTP port", "3338").option("--mcp-path <path>", "MCP HTTP path", "/mcp").option("--verbose", "verbose logs", false).action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const config = await loadResolvedConfigForDev(cwd, rootOpts?.config);
   const watchPaths = collectWatchPaths(config, cwd);
   process.stdout.write("starting searchsocket dev watcher...\n");
   process.stdout.write(`watching:
 ${watchPaths.map((entry) => `  - ${entry}`).join("\n")}
 `);
+  const upstashUrl = config.upstash.url ?? process.env[config.upstash.urlEnv];
+  const upstashToken = config.upstash.token ?? process.env[config.upstash.tokenEnv];
+  const backendMissing = !upstashUrl || !upstashToken;
+  if (backendMissing) {
+    process.stdout.write(
+      `Search backend not configured \u2014 set ${config.upstash.urlEnv} and ${config.upstash.tokenEnv} to enable indexing. Watching for file changes only.
+`
+    );
+  }
   let running = false;
   let pending = false;
   let timer = null;
   const run = async () => {
+    if (backendMissing) {
+      return;
+    }
     if (running) {
       pending = true;
       return;
@@ -3417,18 +6029,40 @@ ${watchPaths.map((entry) => `  - ${entry}`).join("\n")}
       httpPath: opts.mcpPath
     });
   }
+  let closePlayground;
+  if (opts.playground) {
+    if (backendMissing) {
+      process.stdout.write("playground disabled: search backend not configured\n");
+    } else {
+      void runPlaygroundServer({
+        cwd,
+        configPath: rootOpts?.config,
+        config,
+        port: parsePositiveInt(opts.playgroundPort, "--playground-port")
+      }).then(({ port, close }) => {
+        closePlayground = close;
+        process.stdout.write(`playground available at http://127.0.0.1:${port}/_searchsocket
+`);
+      }).catch((err) => {
+        process.stderr.write(`playground error: ${err instanceof Error ? err.message : String(err)}
+`);
+      });
+    }
+  }
   await new Promise((resolve) => {
     process.on("SIGINT", () => {
-      void watcher.close().then(() => resolve());
+      const cleanups = [watcher.close()];
+      if (closePlayground) cleanups.push(closePlayground());
+      void Promise.all(cleanups).then(() => resolve());
     });
   });
 });
 program.command("clean").description("Delete local state and optionally delete remote indexes for a scope").option("--scope <name>", "scope override").option("--remote", "delete remote scope indexes", false).action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const config = await loadConfig({ cwd, configPath: rootOpts?.config });
-  const statePath = path12.join(cwd, config.state.dir);
-  await fsp.rm(statePath, { recursive: true, force: true });
+  const statePath = path15.join(cwd, config.state.dir);
+  await fsp2.rm(statePath, { recursive: true, force: true });
   process.stdout.write(`deleted local state directory: ${statePath}
 `);
   if (opts.remote) {
@@ -3440,7 +6074,7 @@ program.command("clean").description("Delete local state and optionally delete r
 });
 program.command("prune").description("List/delete stale scopes (dry-run by default)").option("--apply", "apply deletions", false).option("--scopes-file <path>", "file containing active scopes").option("--older-than <duration>", "ttl cutoff like 30d").action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const config = await loadConfig({ cwd, configPath: rootOpts?.config });
   const baseScope = resolveScope(config);
   let store;
@@ -3450,17 +6084,17 @@ program.command("prune").description("List/delete stale scopes (dry-run by defau
     scopes = await store.listScopes(config.project.id);
   } catch (error) {
     process.stderr.write(
-      `error: failed to access Upstash Search: ${error instanceof Error ? error.message : String(error)}
+      `error: failed to access Upstash Vector: ${error instanceof Error ? error.message : String(error)}
 `
     );
     process.exitCode = 1;
     return;
   }
-  process.stdout.write(`using Upstash Search
+  process.stdout.write(`using Upstash Vector
 `);
   let keepScopes = /* @__PURE__ */ new Set();
   if (opts.scopesFile) {
-    keepScopes = readScopesFromFile(path12.resolve(cwd, opts.scopesFile));
+    keepScopes = readScopesFromFile(path15.resolve(cwd, opts.scopesFile));
   } else {
     keepScopes = readRemoteGitBranches(cwd);
   }
@@ -3531,7 +6165,7 @@ program.command("prune").description("List/delete stale scopes (dry-run by defau
 });
 program.command("doctor").description("Validate config, env vars, provider connectivity, and local write access").action(async (_opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const checks = [];
   let config = null;
   try {
@@ -3558,8 +6192,8 @@ program.command("doctor").description("Validate config, env vars, provider conne
       details: upstashToken ? void 0 : "missing"
     });
     if (config.source.mode === "static-output") {
-      const outputDir = path12.resolve(cwd, config.source.staticOutputDir);
-      const exists = fs8.existsSync(outputDir);
+      const outputDir = path15.resolve(cwd, config.source.staticOutputDir);
+      const exists = fs11.existsSync(outputDir);
       checks.push({
         name: "source: static output dir",
         ok: exists,
@@ -3568,15 +6202,15 @@ program.command("doctor").description("Validate config, env vars, provider conne
     } else if (config.source.mode === "build") {
       const buildConfig = config.source.build;
       if (buildConfig) {
-        const manifestPath = path12.resolve(cwd, buildConfig.outputDir, "server", "manifest-full.js");
-        const manifestExists = fs8.existsSync(manifestPath);
+        const manifestPath = path15.resolve(cwd, buildConfig.outputDir, "server", "manifest-full.js");
+        const manifestExists = fs11.existsSync(manifestPath);
         checks.push({
           name: "source: build manifest",
           ok: manifestExists,
           details: manifestExists ? manifestPath : `${manifestPath} not found (run \`vite build\` first)`
         });
-        const viteBin = path12.resolve(cwd, "node_modules", ".bin", "vite");
-        const viteExists = fs8.existsSync(viteBin);
+        const viteBin = path15.resolve(cwd, "node_modules", ".bin", "vite");
+        const viteExists = fs11.existsSync(viteBin);
         checks.push({
           name: "source: vite binary",
           ok: viteExists,
@@ -3593,7 +6227,7 @@ program.command("doctor").description("Validate config, env vars, provider conne
       const contentConfig = config.source.contentFiles;
       if (contentConfig) {
         const fg4 = await import("fast-glob");
-        const baseDir = path12.resolve(cwd, contentConfig.baseDir);
+        const baseDir = path15.resolve(cwd, contentConfig.baseDir);
         const files = await fg4.default(contentConfig.globs, { cwd: baseDir, onlyFiles: true });
         checks.push({
           name: "source: content files",
@@ -3627,9 +6261,9 @@ program.command("doctor").description("Validate config, env vars, provider conne
     try {
       const scope = resolveScope(config);
       const { statePath } = ensureStateDirs(cwd, config.state.dir, scope);
-      const testPath = path12.join(statePath, ".write-test");
-      await fsp.writeFile(testPath, "ok\n", "utf8");
-      await fsp.rm(testPath, { force: true });
+      const testPath = path15.join(statePath, ".write-test");
+      await fsp2.writeFile(testPath, "ok\n", "utf8");
+      await fsp2.rm(testPath, { force: true });
       checks.push({ name: "state directory writable", ok: true });
     } catch (error) {
       checks.push({
@@ -3654,20 +6288,22 @@ program.command("doctor").description("Validate config, env vars, provider conne
     process.exitCode = 1;
   }
 });
-program.command("mcp").description("Run SearchSocket MCP server").option("--transport <transport>", "stdio|http", "stdio").option("--port <n>", "HTTP port", "3338").option("--path <path>", "HTTP path", "/mcp").action(async (opts, command) => {
+program.command("mcp").description("Run SearchSocket MCP server").option("--transport <transport>", "stdio|http", "stdio").option("--port <n>", "HTTP port", "3338").option("--path <path>", "HTTP path", "/mcp").addOption(new Option("--access <mode>", "access mode").choices(["public", "private"])).option("--api-key <key>", "API key for public access mode").action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   await runMcpServer({
     cwd,
     configPath: rootOpts?.config,
     transport: opts.transport,
     httpPort: parsePositiveInt(opts.port, "--port"),
-    httpPath: opts.path
+    httpPath: opts.path,
+    access: opts.access,
+    apiKey: opts.apiKey
   });
 });
 program.command("search").description("Quick CLI search against Upstash Search").requiredOption("--q <query>", "search query").option("--scope <name>", "scope override").option("--top-k <n>", "top K results", "10").option("--path-prefix <prefix>", "path prefix filter").action(async (opts, command) => {
   const rootOpts = getRootOptions(command);
-  const cwd = path12.resolve(rootOpts?.cwd ?? process.cwd());
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
   const engine = await SearchEngine.create({
     cwd,
     configPath: rootOpts?.config
@@ -3681,8 +6317,156 @@ program.command("search").description("Quick CLI search against Upstash Search")
   process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
 });
+program.command("test").description("Run search quality assertions against the live index").option("--file <path>", "path to test file", "searchsocket.test.json").option("--scope <name>", "scope override").option("--top-k <n>", "results per query", "10").action(async (opts, command) => {
+  const rootOpts = getRootOptions(command);
+  const cwd = path15.resolve(rootOpts?.cwd ?? process.cwd());
+  const topK = parsePositiveInt(opts.topK, "--top-k");
+  const filePath = path15.resolve(cwd, opts.file);
+  let rawContent;
+  try {
+    rawContent = await fsp2.readFile(filePath, "utf8");
+  } catch {
+    process.stderr.write(`error: test file not found: ${filePath}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  let rawJson;
+  try {
+    rawJson = JSON.parse(rawContent);
+  } catch {
+    process.stderr.write(`error: invalid JSON in ${filePath}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  const parsed = testFileSchema.safeParse(rawJson);
+  if (!parsed.success) {
+    process.stderr.write(`error: invalid test file: ${parsed.error.issues[0]?.message ?? "unknown error"}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  const testCases = parsed.data;
+  const engine = await SearchEngine.create({
+    cwd,
+    configPath: rootOpts?.config
+  });
+  let passed = 0;
+  let failed = 0;
+  const mrrData = [];
+  for (const tc of testCases) {
+    let results;
+    try {
+      const response = await engine.search({
+        q: tc.query,
+        topK,
+        scope: opts.scope
+      });
+      results = response.results;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      process.stdout.write(`FAIL "${tc.query}" \u2192 search error: ${msg}
+`);
+      failed++;
+      continue;
+    }
+    if (tc.expect.topResult !== void 0) {
+      const expectedUrl = tc.expect.topResult;
+      const rank = results.findIndex((r) => r.url === expectedUrl) + 1;
+      mrrData.push({ results, relevant: [expectedUrl] });
+      if (rank === 1) {
+        process.stdout.write(`PASS "${tc.query}" \u2192 ${expectedUrl} at rank 1
+`);
+        passed++;
+      } else {
+        const detail = rank === 0 ? "not found" : `got rank ${rank}`;
+        process.stdout.write(`FAIL "${tc.query}" \u2192 expected ${expectedUrl} at rank 1, ${detail}
+`);
+        failed++;
+      }
+    }
+    if (tc.expect.inTop5 !== void 0) {
+      const expectedUrls = tc.expect.inTop5;
+      const top5Urls = results.slice(0, 5).map((r) => r.url);
+      const missing = expectedUrls.filter((url) => !top5Urls.includes(url));
+      mrrData.push({ results, relevant: expectedUrls });
+      if (missing.length === 0) {
+        process.stdout.write(`PASS "${tc.query}" \u2192 all expected URLs in top 5
+`);
+        passed++;
+      } else {
+        const missingDetail = missing.map((url) => {
+          const rank = results.findIndex((r) => r.url === url) + 1;
+          return rank === 0 ? `${url} (not found)` : `${url} (rank ${rank})`;
+        }).join(", ");
+        process.stdout.write(`FAIL "${tc.query}" \u2192 missing from top 5: ${missingDetail}
+`);
+        failed++;
+      }
+    }
+    if (tc.expect.maxResults !== void 0) {
+      const max = tc.expect.maxResults;
+      const actual = results.length;
+      if (actual <= max) {
+        process.stdout.write(`PASS "${tc.query}" \u2192 ${actual} results (max ${max})
+`);
+        passed++;
+      } else {
+        process.stdout.write(`FAIL "${tc.query}" \u2192 expected at most ${max} results, got ${actual}
+`);
+        failed++;
+      }
+    }
+  }
+  const total = passed + failed;
+  process.stdout.write(`
+results: ${passed} passed, ${failed} failed of ${total} assertions
+`);
+  if (mrrData.length > 0) {
+    const mrrValue = mrr(mrrData);
+    process.stdout.write(`MRR: ${mrrValue.toFixed(4)}
+`);
+  }
+  process.stdout.write(`pass rate: ${total > 0 ? (passed / total * 100).toFixed(1) : "0.0"}%
+`);
+  if (failed > 0) {
+    process.exitCode = 1;
+  }
+});
+program.command("add <component>").description("Copy a Svelte 5 search component template into your project").option("--dir <path>", "output directory", "src/lib/components/search").option("--overwrite", "overwrite existing files", false).action(async (component, opts, command) => {
+  const root = getRootOptions(command).cwd ?? process.cwd();
+  const cwd = path15.resolve(root);
+  if (!isValidComponent(component)) {
+    const available = listAvailableComponents();
+    process.stderr.write(`unknown component: ${component}
+`);
+    process.stderr.write(`available components: ${available.join(", ")}
+`);
+    process.exit(1);
+  }
+  const targetDir = path15.resolve(cwd, opts.dir);
+  const result = await copyComponent(component, targetDir, { overwrite: opts.overwrite });
+  for (const filePath of result.written) {
+    process.stdout.write(`created: ${path15.relative(cwd, filePath)}
+`);
+  }
+  for (const filePath of result.skipped) {
+    process.stdout.write(`skipped (exists): ${path15.relative(cwd, filePath)}
+`);
+  }
+  const firstWritten = result.written[0];
+  if (firstWritten) {
+    process.stdout.write(`
+Usage:
+`);
+    const fileName = path15.basename(firstWritten, ".svelte");
+    process.stdout.write(`  import ${fileName} from "${path15.relative(cwd, firstWritten).replace(/\\/g, "/")}";
+`);
+  }
+});
 async function main() {
-  dotenvConfig({ path: path12.resolve(process.cwd(), ".env") });
+  dotenvConfig({ path: path15.resolve(process.cwd(), ".env") });
   await program.parseAsync(process.argv);
 }
 main().catch((error) => {