@hiai-gg/docsmint 0.7.5 → 0.8.1

package/README.md

@@ -6,9 +6,9 @@ applications, and AI agents.**
 DocsMint stores documents in a structured JSON editor model first. Markdown is
 the convenient second format for editing, importing, and exporting content.
 Automatic chunking, 1024-dimensional embeddings, multilingual hybrid search,
-and GraphRAG make the same knowledge base useful to people, applications, and
-agents through the web application, REST API, TypeScript SDK, CLI, and MCP
-server.
+GraphRAG, and cross-encoder rerank make the same knowledge base useful to
+people, applications, and agents through the web application, REST API,
+TypeScript SDK, CLI, and MCP server.
 
 [![Apache-2.0 License](https://img.shields.io/badge/License-Apache--2.0-green.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/hiai-gg/docsmint?sort=semver)](https://github.com/hiai-gg/docsmint/releases)
@@ -36,7 +36,8 @@ server.
 
 - **Write naturally** in a rich visual editor or raw Markdown.
 - **Find meaning, not only keywords** with exact, lexical, fuzzy, vector,
-  multilingual expansion, and graph retrieval fused through RRF.
+  multilingual expansion, and graph retrieval fused through RRF, then
+  reranked with a cross-encoder (Voyage rerank-2.5 in the reference profile).
 - **Keep retrieval current** with automatic, incremental chunking and
   re-embedding after document or metadata changes.
 - **Connect agents directly** through REST, a typed SDK, CLI, or MCP.
@@ -45,8 +46,50 @@ server.
 - **Own the full stack**: application data, vectors, graph, queue, and files run
   on infrastructure you control.
 
+## What's new in 0.8.1?
+
+- **GraphRAG expansion is connection-safe.** AGE reads pin `ag_catalog` on the
+  same pooled connection as `cypher()`, so scoped search keeps graph neighbors
+  even when the connection did not already have AGE first in `search_path`.
+
+## What's new in 0.7.9?
+
+- **GraphRAG on category/share search keeps inherited-folder neighbors.** The
+  allowed document list is the ACL; category is not applied a second time.
+
+## What's new in 0.7.8?
+
+- **GraphRAG still contributes after rerank.** Neighbors already in the fused
+  prefix keep the graph channel, so scoped search does not lose graph evidence.
+- **Public API identity is DocsMint.** Health reports `service: "docsmint"`;
+  startup and SDK errors no longer say `hiai-docs`.
+
+## What's new in 0.7.7?
+
+- **Cross-encoder rerank is on by default.** After RRF, search reranks the
+  original query against the fused prefix with Voyage `rerank-2.5` (Cohere
+  and NVIDIA fallbacks). Provider failures keep RRF order. Set
+  `SEARCH_RERANK_ENABLED=false` to turn it off.
+- **Live retrieval improved first-hit ranking.** On a 24-document labeled
+  corpus, RRF+rerank moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986.
+  Recall@10 stayed 1.0. The paraphrase query “operator API key header”
+  moved the API-key document from rank 2 to rank 1 (MRR 0.50 → 1.00).
+- **Three-model fallbacks** for embeddings, extraction, expansion, and
+  rerank so a single provider outage does not drop the channel.
+
+## What's new in 0.7.6?
+
+- **Better Auth 1.6 rollback remains possible** after the issuer migration by
+  deriving the legacy account issuer in a database trigger.
+
 ## What's new in 0.7.5?
 
+- **Runtime and dependency graph** to Bun 1.4, TypeScript 6, Better Auth 1.7,
+  and current compatible editor/queue packages, with fail-closed issuer
+  identity.
+
+## What's new in 0.7.4?
+
 - **MCP Registry description fits the 100-character limit**, so official
   catalog publication can complete after 0.7.3 reached npm.
 
@@ -137,7 +180,7 @@ docker pull vgalibov/docsmint:web-latest
 docker pull vgalibov/docsmint:caddy-latest
 ```
 
-Use versioned tags such as `api-v0.7.5` for reproducible deploys. The
+Use versioned tags such as `api-v0.8.1` for reproducible deploys. The
 quickstart still builds the Compose stack from this repository so PostgreSQL,
 Redis, and SeaweedFS start together with the application.
 
@@ -279,19 +322,19 @@ resources, skill, and API routes.
 ### Prompts (2)
 
 - `organize_workspace`: Plan safe document organization using DocsMint categories and folders.
-- `research_workspace`: Research a question with hybrid search and GraphRAG citing document IDs.
+- `research_workspace`: Research a question with hybrid search, GraphRAG, and rerank citing document IDs.
 
 ### Resources (3)
 
 - `docsmint://guide/editor`: Editor usage guide.
-- `docsmint://guide/search`: Search and GraphRAG guide.
+- `docsmint://guide/search`: Search, GraphRAG, and rerank guide.
 - `docsmint://workspace/catalog`: Live scoped workspace catalog.
 
 ### Skills (1)
 
 - [`docsmint-document-manager`](skills/docsmint-document-manager/SKILL.md):
   create, organize, edit, and research DocsMint documents through the 17 MCP
-  tools, including hybrid search, GraphRAG, and index refresh.
+  tools, including hybrid search, GraphRAG, rerank, and index refresh.
 
 The same Skill ships in the npm package under `skills/docsmint-document-manager/SKILL.md`.
 
@@ -382,8 +425,12 @@ previous valid generation remains searchable if a provider call fails.
 Search combines exact title matches, multilingual lexical search, typo-tolerant
 fuzzy matching, semantic vectors, adaptive query expansion, and Apache AGE
 graph neighbors. Reciprocal rank fusion combines the channels without allowing
-one weak provider result to dominate. Authorization is applied before retrieval
-and again before results are returned.
+one weak provider result to dominate. A cross-encoder then reranks the fused
+prefix against the original query (Voyage rerank-2.5 by default). On a labeled
+24-document corpus that moved MRR 0.969 → 1.000 and nDCG@10 0.958 → 0.986
+versus RRF-only. Rerank, expansion, embeddings, and AGE failures keep the
+remaining channels. Authorization is applied before retrieval and again before
+results are returned.
 
 GraphRAG is part of the normal search path in the reference configuration. It
 extracts entities after embeddings are ready and finds related documents beyond

package/dist/backend/index.js

@@ -79815,10 +79815,26 @@ var init_kysely_adapter = __esm(() => {
   init_dist3();
 });
 
+// ../../backend/src/lib/openrouter-public-matrix.ts
+var OPENROUTER_PUBLIC_BASE_URL = "https://openrouter.ai/api/v1", OPENROUTER_PUBLIC_EXPANSION_MODELS, OPENROUTER_PUBLIC_RERANK_MODELS;
+var init_openrouter_public_matrix = __esm(() => {
+  OPENROUTER_PUBLIC_EXPANSION_MODELS = {
+    primary: "poolside/laguna-xs-2.1",
+    fallback: "openai/gpt-5.6-luna",
+    fallback_2: "google/gemini-3.5-flash-lite"
+  };
+  OPENROUTER_PUBLIC_RERANK_MODELS = {
+    primary: "voyageai/rerank-2.5",
+    fallback: "cohere/rerank-v3.5",
+    fallback_2: "nvidia/llama-nemotron-rerank-vl-1b-v2:free"
+  };
+});
+
 // ../../backend/src/lib/config-schema.ts
 var adminApiKeyPlaceholder, envSchema;
 var init_config_schema = __esm(() => {
   init_zod();
+  init_openrouter_public_matrix();
   adminApiKeyPlaceholder = /^(?:change[-_ ]?me|changeme|your[-_ ]?api[-_ ]?key)(?:\b|[-_ ])/i;
   envSchema = exports_external2.object({
     DATABASE_URL: exports_external2.string().default("postgresql://hiai_app:changeme@localhost:5437/hiai_docs"),
@@ -79875,6 +79891,9 @@ var init_config_schema = __esm(() => {
     EMBEDDING_FALLBACK_BASE_URL: exports_external2.string().optional(),
     EMBEDDING_FALLBACK_API_KEY: exports_external2.string().optional(),
     EMBEDDING_FALLBACK_MODEL: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_BASE_URL: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    EMBEDDING_FALLBACK_2_MODEL: exports_external2.string().optional(),
     API_PORT: exports_external2.coerce.number().default(50700),
     NODE_ENV: exports_external2.enum(["development", "production", "test"]).default("development"),
     LOG_LEVEL: exports_external2.enum(["trace", "debug", "info", "warn", "error", "fatal"]).default("info"),
@@ -79901,14 +79920,34 @@ var init_config_schema = __esm(() => {
     GRAPH_EXTRACT_FALLBACK_BASE_URL: exports_external2.string().optional(),
     GRAPH_EXTRACT_FALLBACK_API_KEY: exports_external2.string().optional(),
     GRAPH_EXTRACT_FALLBACK_MODEL: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_BASE_URL: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    GRAPH_EXTRACT_FALLBACK_2_MODEL: exports_external2.string().optional(),
     GRAPH_EXTRACT_MIN_CONFIDENCE: exports_external2.coerce.number().min(0).max(1).default(0.5),
     SEARCH_EXPANSION_ENABLED: exports_external2.string().optional().default("true").transform((v2) => v2 === "true"),
-    SEARCH_EXPANSION_BASE_URL: exports_external2.string().default("https://openrouter.ai/api/v1"),
+    SEARCH_EXPANSION_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
     SEARCH_EXPANSION_API_KEY: exports_external2.string().optional(),
-    SEARCH_EXPANSION_MODEL: exports_external2.string().default("mistralai/ministral-14b-2512"),
-    SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external2.string().default("https://openrouter.ai/api/v1"),
+    SEARCH_EXPANSION_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.primary),
+    SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
     SEARCH_EXPANSION_FALLBACK_API_KEY: exports_external2.string().optional(),
-    SEARCH_EXPANSION_FALLBACK_MODEL: exports_external2.string().default("google/gemma-4-31b-it"),
+    SEARCH_EXPANSION_FALLBACK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback),
+    SEARCH_EXPANSION_FALLBACK_2_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_EXPANSION_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    SEARCH_EXPANSION_FALLBACK_2_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback_2),
+    SEARCH_RERANK_ENABLED: exports_external2.string().optional().default("true").transform((v2) => v2 === "true"),
+    SEARCH_RERANK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.primary),
+    SEARCH_RERANK_FALLBACK_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_FALLBACK_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_FALLBACK_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback),
+    SEARCH_RERANK_FALLBACK_2_BASE_URL: exports_external2.string().default(OPENROUTER_PUBLIC_BASE_URL),
+    SEARCH_RERANK_FALLBACK_2_API_KEY: exports_external2.string().optional(),
+    SEARCH_RERANK_FALLBACK_2_MODEL: exports_external2.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback_2),
+    SEARCH_RERANK_TIMEOUT_MS: exports_external2.coerce.number().int().min(250).max(30000).default(3000),
+    SEARCH_RERANK_TOP_N: exports_external2.coerce.number().int().min(1).max(100).default(20),
+    SEARCH_RERANK_MAX_CHARS: exports_external2.coerce.number().int().min(120).max(8000).default(1500),
+    SEARCH_RERANK_GRAPH_POSITION: exports_external2.enum(["before", "after"]).default("after"),
     SEARCH_EXPANSION_TIMEOUT_MS: exports_external2.coerce.number().int().min(1000).max(300000).default(6000),
     SEARCH_VECTOR_PROVIDER_TIMEOUT_MS: exports_external2.coerce.number().int().min(250).max(30000).default(2500),
     SEARCH_EXPANSION_CACHE_TTL_SECONDS: exports_external2.coerce.number().int().min(0).max(2592000).default(86400),
@@ -195670,6 +195709,10 @@ var METRIC_NAMES = {
   SEARCH_EXPANSION_LOW_VECTOR_SIMILARITY_TOTAL: "search_expansion_reason_low_vector_similarity_total",
   SEARCH_EXPANSION_LANGUAGE_MISMATCH_TOTAL: "search_expansion_reason_language_mismatch_total",
   SEARCH_EXPANSION_EMPTY_CANDIDATES_TOTAL: "search_expansion_reason_empty_candidates_total",
+  SEARCH_RERANK_DURATION_MS: "search_rerank_duration_ms",
+  SEARCH_RERANK_SUCCESS_TOTAL: "search_rerank_success_total",
+  SEARCH_RERANK_FALLBACK_TOTAL: "search_rerank_fallback_total",
+  SEARCH_RERANK_CANDIDATES_TOTAL: "search_rerank_candidates_total",
   SEARCH_EXACT_DURATION_MS: "search_exact_duration_ms",
   SEARCH_EXACT_ERRORS_TOTAL: "search_exact_errors_total",
   SEARCH_EXACT_CANDIDATES_TOTAL: "search_exact_candidates_total",
@@ -195841,7 +195884,7 @@ function recordSearchExpansionMetrics(input) {
         break;
     }
   }
-  if (input.used !== false && input.model && input.model === input.fallbackModel) {
+  if (input.used !== false && input.model && (input.model === input.fallbackModel || input.model === input.fallback2Model)) {
     incrementCounter(METRIC_NAMES.SEARCH_EXPANSION_FALLBACK_TOTAL);
   } else if (input.used !== false && input.model) {
     incrementCounter(METRIC_NAMES.SEARCH_EXPANSION_PRIMARY_TOTAL);
@@ -196176,31 +196219,52 @@ async function getEmbedding(text3) {
     recordDuration(METRIC_NAMES.EMBEDDING_DURATION_MS, Date.now() - start);
   }
 }
-async function getEmbeddingInner(text3) {
-  const providers = [];
-  if (config3.EMBEDDING_BASE_URL && config3.EMBEDDING_MODEL) {
-    providers.push({
+function configuredEmbeddingProviders() {
+  const slots = [
+    {
       baseUrl: config3.EMBEDDING_BASE_URL,
       apiKey: config3.EMBEDDING_API_KEY,
       model: config3.EMBEDDING_MODEL,
       provider: "primary"
-    });
-  }
-  if (config3.EMBEDDING_FALLBACK_BASE_URL && config3.EMBEDDING_FALLBACK_MODEL) {
-    providers.push({
+    },
+    {
       baseUrl: config3.EMBEDDING_FALLBACK_BASE_URL,
       apiKey: config3.EMBEDDING_FALLBACK_API_KEY,
       model: config3.EMBEDDING_FALLBACK_MODEL,
       provider: "fallback"
-    });
-  }
+    },
+    {
+      baseUrl: config3.EMBEDDING_FALLBACK_2_BASE_URL,
+      apiKey: config3.EMBEDDING_FALLBACK_2_API_KEY,
+      model: config3.EMBEDDING_FALLBACK_2_MODEL,
+      provider: "fallback_2"
+    }
+  ];
+  return slots.flatMap((slot) => slot.baseUrl && slot.model ? [
+    {
+      baseUrl: slot.baseUrl,
+      apiKey: slot.apiKey,
+      model: slot.model,
+      provider: slot.provider
+    }
+  ] : []);
+}
+function assignProviderError(provider, message2, errors6) {
+  if (provider === "primary")
+    errors6.primaryError = message2;
+  else if (provider === "fallback")
+    errors6.fallbackError = message2;
+  else
+    errors6.fallback2Error = message2;
+}
+async function getEmbeddingInner(text3) {
+  const providers = configuredEmbeddingProviders();
   if (providers.length === 0) {
     logger3.warn("No embedding provider configured (primary or fallback); embedding result is unavailable");
     incrementCounter(METRIC_NAMES.EMBEDDING_ZERO);
     return { ok: false, code: "not_configured" };
   }
-  let primaryError;
-  let fallbackError;
+  const errors6 = {};
   let finalCode = "provider_error";
   for (const provider of providers) {
     try {
@@ -196208,11 +196272,7 @@ async function getEmbeddingInner(text3) {
       const validation = validateEmbeddingVector(vector5);
       if (!validation.ok) {
         finalCode = validation.code;
-        const message2 = `provider returned ${validation.code}`;
-        if (provider.provider === "primary")
-          primaryError = message2;
-        else
-          fallbackError = message2;
+        assignProviderError(provider.provider, `provider returned ${validation.code}`, errors6);
         logger3.warn({
           model: provider.model,
           provider: provider.provider,
@@ -196235,11 +196295,7 @@ async function getEmbeddingInner(text3) {
       };
     } catch (err) {
       finalCode = failureCodeFromError(err);
-      const message2 = safeErrorMessage(err);
-      if (provider.provider === "primary")
-        primaryError = message2;
-      else
-        fallbackError = message2;
+      assignProviderError(provider.provider, safeErrorMessage(err), errors6);
       logger3.warn({ err, model: provider.model, provider: provider.provider }, "Embedding provider failed, trying next configured provider");
     }
   }
@@ -196247,8 +196303,7 @@ async function getEmbeddingInner(text3) {
   return {
     ok: false,
     code: finalCode,
-    ...primaryError ? { primaryError } : {},
-    ...fallbackError ? { fallbackError } : {}
+    ...errors6
   };
 }
 function safeErrorMessage(error53) {
@@ -231076,8 +231131,9 @@ async function expandFromQueryPlan(plan, limit = 20) {
   const boundedLimit = Math.max(1, Math.min(Math.floor(limit), 100));
   try {
     const cypher = buildQuerySeedCypher(terms, boundedLimit);
-    const queryString = buildCypherSql(cypher, "neighbor_id agtype, generation_id agtype, relation agtype, hops agtype");
-    const rows = await sql6.unsafe(queryString);
+    const rows = await runCypher(sql6, cypher, {
+      columns: "neighbor_id agtype, generation_id agtype, relation agtype, hops agtype"
+    });
     const seen = new Set;
     const out = [];
     for (const row of rows) {
@@ -231112,8 +231168,9 @@ async function expandResults(docIds, maxHops = DEFAULT_MAX_HOPS) {
   const sql6 = await getGraphDbRequired();
   try {
     const cypher = buildTraversalCypher(seeds, clampedHops);
-    const queryString = buildCypherSql(cypher, "seed_id agtype, seed_generation_id agtype, neighbor_id agtype, generation_id agtype, relation agtype, hops agtype");
-    const rows = await sql6.unsafe(queryString);
+    const rows = await runCypher(sql6, cypher, {
+      columns: "seed_id agtype, seed_generation_id agtype, neighbor_id agtype, generation_id agtype, relation agtype, hops agtype"
+    });
     for (const row of rows) {
       const seedId = stripQuotes(String(row.seed_id ?? ""));
       const neighborId = stripQuotes(String(row.neighbor_id ?? ""));
@@ -231185,6 +231242,13 @@ function buildCypherSql(cypher, columns2) {
   const quoted = `$${tag2}$ ${cypher} $${tag2}$`;
   return `SELECT * FROM cypher('docs_graph', ${quoted}) AS (${columns2})`;
 }
+async function runCypher(sql6, cypher, options) {
+  const queryString = buildCypherSql(cypher, options.columns);
+  return sql6.begin(async (tx) => {
+    await tx.unsafe("SET LOCAL search_path = ag_catalog, public");
+    return await tx.unsafe(queryString);
+  });
+}
 function stripQuotes(value) {
   const trimmed = value.trim();
   if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
@@ -231571,7 +231635,7 @@ function createHealthRoutes(dependencies) {
       set2.status = 503;
     return {
       status: readiness.status === "unhealthy" ? "unhealthy" : "ok",
-      service: "hiai-docs",
+      service: "docsmint",
       timestamp: new Date().toISOString(),
       database: databaseAvailable ? "ok" : "error",
       redis: redisAvailable ? "ok" : "error",
@@ -231876,9 +231940,10 @@ async function retrieveGraphCandidates(ctx, request, adapters = {}) {
   const requestedSeeds = dedupe2(request.documentSeeds).slice(0, config3.SEARCH_GRAPH_SEED_LIMIT);
   const visibilityScope = request.visibilityScope ?? _buildGraphVisibilityScope(ctx);
   const tenantTransaction = adapters.withTenant ?? withTenant;
-  const authorizedSeeds = requestedSeeds.length === 0 ? new Set : await resolveVisibleIds(ctx, requestedSeeds, adapters.visibleDocumentIds, visibilityScope, request.categoryId, tenantTransaction);
+  const categoryId = visibilityScope.kind === "share" ? undefined : request.categoryId;
+  const authorizedSeeds = requestedSeeds.length === 0 ? new Set : await resolveVisibleIds(ctx, requestedSeeds, adapters.visibleDocumentIds, visibilityScope, categoryId, tenantTransaction);
   const seeds = requestedSeeds.filter((id3) => authorizedSeeds.has(id3));
-  const activeSeedGenerations = await resolveActiveGenerations(ctx, seeds, adapters.visibleDocumentGenerations, visibilityScope, request.categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
+  const activeSeedGenerations = await resolveActiveGenerations(ctx, seeds, adapters.visibleDocumentGenerations, visibilityScope, categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
   const expand2 = adapters.expandResults ?? expandResults;
   const expandQuery = adapters.expandFromQueryPlan ?? expandFromQueryPlan;
   let related = [];
@@ -231902,8 +231967,8 @@ async function retrieveGraphCandidates(ctx, request, adapters = {}) {
     });
   });
   const allIds = dedupe2(relatedWithCurrentSeed.map((candidate) => candidate.docId));
-  const visible = await resolveVisibleIds(ctx, allIds, adapters.visibleDocumentIds, visibilityScope, request.categoryId, tenantTransaction);
-  const activeGenerations = await resolveActiveGenerations(ctx, allIds, adapters.visibleDocumentGenerations, visibilityScope, request.categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
+  const visible = await resolveVisibleIds(ctx, allIds, adapters.visibleDocumentIds, visibilityScope, categoryId, tenantTransaction);
+  const activeGenerations = await resolveActiveGenerations(ctx, allIds, adapters.visibleDocumentGenerations, visibilityScope, categoryId, Boolean(adapters.visibleDocumentIds), tenantTransaction);
   const unique = new Map;
   for (const candidate of relatedWithCurrentSeed) {
     if (!visible.has(candidate.docId))
@@ -232168,8 +232233,30 @@ function resolveChatProviderKey(baseUrl, explicitKey, sharedOpenRouterKey) {
     return "";
   return sharedOpenRouterKey?.trim() ?? "";
 }
+function uniqueChatProviders(providers) {
+  const seen = new Set;
+  const unique = [];
+  for (const provider of providers) {
+    if (!provider?.baseUrl || !provider.model)
+      continue;
+    const identity = [
+      provider.baseUrl,
+      provider.model,
+      provider.apiKey ?? ""
+    ].join("|");
+    if (seen.has(identity))
+      continue;
+    seen.add(identity);
+    unique.push(provider);
+  }
+  return unique;
+}
 async function requestStructuredChat(options) {
-  const providers = [options.primary, options.fallback].filter((provider) => Boolean(provider?.baseUrl));
+  const providers = uniqueChatProviders([
+    options.primary,
+    options.fallback,
+    ...options.fallbacks ?? []
+  ]);
   for (const provider of providers) {
     try {
       const raw = await requestChatContent(provider, options);
@@ -232241,13 +232328,18 @@ async function expandQuery(plan, scope) {
   const tenantScope = typeof scope === "string" ? scope.trim() : (scope.tenantScope ?? scope.tenantId ?? scope.ownerId ?? "").trim();
   if (!tenantScope || !plan.normalized.trim())
     return null;
-  const primary = providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL);
-  const fallback = providerConfig(config3.SEARCH_EXPANSION_FALLBACK_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_MODEL);
-  const providerCount = fallback.baseUrl ? 2 : 1;
-  const providerTimeoutMs = Math.max(250, Math.floor(config3.SEARCH_EXPANSION_TIMEOUT_MS / providerCount));
-  primary.timeoutMs = providerTimeoutMs;
-  fallback.timeoutMs = providerTimeoutMs;
-  const key = await expansionCacheKey(tenantScope, plan.normalized, primary, fallback);
+  const chain3 = uniqueChatProviders([
+    providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL),
+    providerConfig(config3.SEARCH_EXPANSION_FALLBACK_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_MODEL),
+    providerConfig(config3.SEARCH_EXPANSION_FALLBACK_2_BASE_URL, config3.SEARCH_EXPANSION_FALLBACK_2_API_KEY, config3.SEARCH_EXPANSION_FALLBACK_2_MODEL)
+  ]);
+  const providerTimeoutMs = Math.max(250, Math.floor(config3.SEARCH_EXPANSION_TIMEOUT_MS / Math.max(1, chain3.length)));
+  for (const provider of chain3)
+    provider.timeoutMs = providerTimeoutMs;
+  const [primary, ...fallbacks] = chain3;
+  if (!primary)
+    return null;
+  const key = await expansionCacheKey(tenantScope, plan.normalized, primary, fallbacks);
   const ttl = config3.SEARCH_EXPANSION_CACHE_TTL_SECONDS;
   if (ttl > 0) {
     try {
@@ -232272,7 +232364,7 @@ async function expandQuery(plan, scope) {
   }
   const result = await requestStructuredChat({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       {
         role: "system",
@@ -232352,12 +232444,15 @@ var cachedResultSchema = exports_external2.object({
   }),
   model: exports_external2.string()
 });
-async function expansionCacheKey(tenantScope, normalizedQuery, primary = providerConfig(config3.SEARCH_EXPANSION_BASE_URL, config3.SEARCH_EXPANSION_API_KEY, config3.SEARCH_EXPANSION_MODEL), fallback = undefined) {
+async function expansionCacheKey(tenantScope, normalizedQuery, primary = {
+  baseUrl: config3.SEARCH_EXPANSION_BASE_URL,
+  model: config3.SEARCH_EXPANSION_MODEL,
+  timeoutMs: config3.SEARCH_EXPANSION_TIMEOUT_MS
+}, fallbacks = []) {
   const modelProfile = [
     primary.baseUrl,
     primary.model,
-    fallback?.baseUrl ?? "",
-    fallback?.model ?? ""
+    ...fallbacks.flatMap((provider) => [provider.baseUrl, provider.model])
   ].join("|");
   const input = [
     tenantScope,
@@ -232369,6 +232464,8 @@ async function expansionCacheKey(tenantScope, normalizedQuery, primary = provide
   return `hiai-docs:search:expansion:${digest4}`;
 }
 function providerConfig(baseUrl, explicitKey, model) {
+  if (!baseUrl || !model)
+    return;
   return {
     baseUrl,
     model,
@@ -232396,6 +232493,174 @@ function normalizeVariant(value) {
   return value.normalize("NFKC").trim().replace(/\s+/g, " ").toLocaleLowerCase();
 }
 
+// ../../backend/src/search/rerank.ts
+var DEFAULT_RERANK_MAX_CHARS = 1500;
+function normalizeRerankText(title, content50, maxChars = DEFAULT_RERANK_MAX_CHARS) {
+  const cleaned = `${title.trim()}
+${content50}`.replace(/data:[^\s)>]+/gi, " ").replace(/\s+/g, " ").trim();
+  if (cleaned.length <= maxChars)
+    return cleaned;
+  return cleaned.slice(0, maxChars);
+}
+function applyRerankOrder(ranked, hits, topN) {
+  if (ranked.length === 0 || hits.length === 0 || topN < 1)
+    return ranked;
+  const window2 = ranked.slice(0, Math.min(topN, ranked.length));
+  const rest = ranked.slice(window2.length);
+  const byId = new Map(window2.map((item) => [item.documentId, item]));
+  const seen = new Set;
+  const reordered = [];
+  const sortedHits = [...hits].sort((left, right) => {
+    if (right.score !== left.score)
+      return right.score - left.score;
+    return left.rank - right.rank;
+  });
+  for (const hit of sortedHits) {
+    const item = byId.get(hit.id);
+    if (!item || seen.has(hit.id))
+      continue;
+    seen.add(hit.id);
+    reordered.push(item);
+  }
+  for (const item of window2) {
+    if (seen.has(item.documentId))
+      continue;
+    reordered.push(item);
+  }
+  return [...reordered, ...rest];
+}
+
+// ../../backend/src/search/rerank-provider.ts
+init_config();
+init_logger3();
+function configuredSlots() {
+  const slots = [
+    {
+      baseUrl: config3.SEARCH_RERANK_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_API_KEY,
+      model: config3.SEARCH_RERANK_MODEL
+    },
+    {
+      baseUrl: config3.SEARCH_RERANK_FALLBACK_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_FALLBACK_API_KEY,
+      model: config3.SEARCH_RERANK_FALLBACK_MODEL
+    },
+    {
+      baseUrl: config3.SEARCH_RERANK_FALLBACK_2_BASE_URL,
+      apiKey: config3.SEARCH_RERANK_FALLBACK_2_API_KEY,
+      model: config3.SEARCH_RERANK_FALLBACK_2_MODEL
+    }
+  ];
+  const seen = new Set;
+  const unique = [];
+  for (const slot of slots) {
+    if (!slot.baseUrl || !slot.model)
+      continue;
+    const identity = `${slot.baseUrl}|${slot.model}`;
+    if (seen.has(identity))
+      continue;
+    seen.add(identity);
+    unique.push({
+      baseUrl: slot.baseUrl,
+      model: slot.model,
+      apiKey: resolveChatProviderKey(slot.baseUrl, slot.apiKey, config3.OPENROUTER_API_KEY)
+    });
+  }
+  return unique;
+}
+function rerankUrl(baseUrl) {
+  const normalized = baseUrl.replace(/\/$/, "");
+  return normalized.endsWith("/rerank") ? normalized : `${normalized}/rerank`;
+}
+async function requestRerank(input) {
+  const documents2 = input.candidates.map((candidate) => candidate.text.trim()).filter((text4) => text4.length > 0);
+  if (documents2.length === 0)
+    return null;
+  const ids = input.candidates.map((candidate) => candidate.id);
+  const topN = Math.min(input.topN ?? config3.SEARCH_RERANK_TOP_N, documents2.length);
+  const timeoutMs = config3.SEARCH_RERANK_TIMEOUT_MS;
+  const started = performance.now();
+  incrementCounterBy(METRIC_NAMES.SEARCH_RERANK_CANDIDATES_TOTAL, documents2.length);
+  try {
+    for (const slot of configuredSlots()) {
+      try {
+        const hits = await callRerankSlot(slot, input.query, documents2, ids, {
+          topN,
+          timeoutMs
+        });
+        if (hits.length === 0)
+          continue;
+        incrementCounter(METRIC_NAMES.SEARCH_RERANK_SUCCESS_TOTAL);
+        return { hits, model: slot.model };
+      } catch (error53) {
+        logger3.warn({ err: error53, model: slot.model }, "Rerank provider failed, trying next configured provider");
+      }
+    }
+    incrementCounter(METRIC_NAMES.SEARCH_RERANK_FALLBACK_TOTAL);
+    return null;
+  } finally {
+    recordDuration(METRIC_NAMES.SEARCH_RERANK_DURATION_MS, performance.now() - started);
+  }
+}
+async function callRerankSlot(slot, query, documents2, ids, options) {
+  const controller = new AbortController;
+  const timer2 = setTimeout(() => controller.abort(), options.timeoutMs);
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (slot.apiKey)
+    headers.Authorization = `Bearer ${slot.apiKey}`;
+  try {
+    const response = await fetch(rerankUrl(slot.baseUrl), {
+      method: "POST",
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify({
+        model: slot.model,
+        query,
+        documents: documents2,
+        top_n: options.topN
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`rerank provider returned ${response.status}`);
+    }
+    const body = await response.json();
+    const hits = [];
+    for (const [rank, row] of (body.results ?? []).entries()) {
+      if (typeof row.index !== "number" || row.index < 0)
+        continue;
+      const id3 = ids[row.index];
+      if (!id3)
+        continue;
+      const score = typeof row.relevance_score === "number" && Number.isFinite(row.relevance_score) ? row.relevance_score : 0;
+      hits.push({ id: id3, score, rank: rank + 1 });
+    }
+    return hits;
+  } finally {
+    clearTimeout(timer2);
+  }
+}
+
+// ../../backend/src/search/rerank-texts.ts
+init_schema2();
+init_drizzle_orm();
+init_config();
+async function loadRerankTexts(ctx, documentIds, maxChars = config3.SEARCH_RERANK_MAX_CHARS) {
+  const texts = new Map;
+  if (documentIds.length === 0)
+    return texts;
+  const rows = await withTenant(ctx, async (tx) => tx.select({
+    id: documents.id,
+    title: documents.title,
+    content: documents.content
+  }).from(documents).where(and(isNull(documents.deletedAt), inArray(documents.id, documentIds))));
+  for (const row of rows) {
+    texts.set(row.id, normalizeRerankText(row.title, row.content ?? "", maxChars));
+  }
+  return texts;
+}
+
 // ../../backend/src/search/retrievers.ts
 init_drizzle_orm();
 init_config();
@@ -232714,6 +232979,8 @@ async function searchDocuments(ctx, request, adapters = {}) {
   const embeddingProvider = adapters.getEmbedding ?? getEmbedding;
   const expand2 = adapters.expand ?? expandQuery;
   const retrieveGraph = adapters.retrieveGraph ?? retrieveGraphCandidates;
+  const rerankDocuments = adapters.rerank ?? requestRerank;
+  const loadTexts = adapters.loadRerankTexts ?? loadRerankTexts;
   const filterRanked = adapters.filterRanked ?? applySearchFilters;
   const channelErrors = {};
   const embeddingCache = new Map;
@@ -232807,27 +233074,36 @@ async function searchDocuments(ctx, request, adapters = {}) {
       model: expansionModel,
       primaryModel: config3.SEARCH_EXPANSION_MODEL,
       fallbackModel: config3.SEARCH_EXPANSION_FALLBACK_MODEL,
+      fallback2Model: config3.SEARCH_EXPANSION_FALLBACK_2_MODEL,
       estimatedCostMicrounits: expansionUsed ? config3.SEARCH_EXPANSION_ESTIMATED_COST_MICROUNITS : 0
     });
     recordDuration(METRIC_NAMES.SEARCH_EXPANDED_DURATION_MS, performance.now() - expandedStarted);
   }
-  const direct = fuseCandidates([...fast, ...expanded].flatMap((result) => result.candidates), {
+  const rrfOptions = {
     rrfK: config3.SEARCH_RRF_K,
     exactBoost: config3.SEARCH_EXACT_BOOST,
     channelAgreementBoost: config3.SEARCH_CHANNEL_AGREEMENT_BOOST,
     graphMaxContribution: config3.SEARCH_GRAPH_MAX_CONTRIBUTION,
     vectorMinSimilarity: config3.SEARCH_VECTOR_MIN_SIMILARITY
-  });
+  };
+  const direct = fuseCandidates([...fast, ...expanded].flatMap((result) => result.candidates), rrfOptions);
   const graphPlan = expandedPlan ?? plan;
-  const graphSeeds = direct.slice(0, config3.SEARCH_GRAPH_SEED_LIMIT).map((result) => result.documentId);
+  const graphAttempted = request.graphEnabled !== false;
+  const rerankEnabled = request.rerankEnabled ?? config3.SEARCH_RERANK_ENABLED;
+  const graphPosition = request.rerankGraphPosition ?? config3.SEARCH_RERANK_GRAPH_POSITION;
   let graph = [];
   let graphFailed = false;
-  const graphAttempted = request.graphEnabled !== false;
-  if (graphAttempted) {
+  let ranked;
+  let rerankAttempted = false;
+  let rerankUsed = false;
+  let rerankFallback = false;
+  let rerankModel;
+  const runGraph = async (seeds) => {
     const graphStarted = performance.now();
+    let next = [];
     try {
-      graph = await retrieveGraph(ctx, {
-        documentSeeds: graphSeeds,
+      next = await retrieveGraph(ctx, {
+        documentSeeds: seeds,
         queryPlan: graphPlan,
         limit: Math.min(limit * 2, config3.SEARCH_GRAPH_RESULT_LIMIT),
         maxHops: request.maxGraphHops ?? config3.SEARCH_GRAPH_MAX_HOPS,
@@ -232837,25 +233113,82 @@ async function searchDocuments(ctx, request, adapters = {}) {
     } catch {
       graphFailed = true;
     }
-    graph = restrictCandidates(graph, request.documentIds);
+    next = restrictCandidates(next, request.documentIds);
     recordSearchChannelMetrics({
       channel: "graph",
       durationMs: performance.now() - graphStarted,
-      candidateCount: graph.length,
+      candidateCount: next.length,
       errorCode: graphFailed ? "query_failed" : undefined
     });
+    return next;
+  };
+  const seedIds = (items2) => items2.slice(0, config3.SEARCH_GRAPH_SEED_LIMIT).map((item) => item.documentId);
+  const applyOptionalRerank = async (items2) => {
+    if (!rerankEnabled || items2.length === 0)
+      return items2;
+    rerankAttempted = true;
+    try {
+      const topN = Math.min(config3.SEARCH_RERANK_TOP_N, items2.length);
+      const window2 = items2.slice(0, topN);
+      const texts = await loadTexts(ctx, window2.map((item) => item.documentId));
+      const candidates = window2.map((item, index2) => ({
+        id: item.documentId,
+        text: texts.get(item.documentId) ?? "",
+        sourceRank: index2 + 1,
+        rrfScore: item.score
+      }));
+      if (candidates.every((candidate) => candidate.text.length === 0)) {
+        rerankFallback = true;
+        return items2;
+      }
+      const result = await rerankDocuments({
+        query: plan.original,
+        candidates,
+        topN
+      });
+      if (!result || result.hits.length === 0) {
+        rerankFallback = true;
+        return items2;
+      }
+      rerankUsed = true;
+      rerankModel = result.model;
+      return applyRerankOrder(items2, result.hits, topN);
+    } catch {
+      rerankFallback = true;
+      return items2;
+    }
+  };
+  if (!rerankEnabled) {
+    if (graphAttempted)
+      graph = await runGraph(seedIds(direct));
+    ranked = fuseCandidates([
+      ...fast.flatMap((result) => result.candidates),
+      ...expanded.flatMap((result) => result.candidates),
+      ...graph
+    ], rrfOptions);
+  } else if (graphPosition === "before") {
+    if (graphAttempted)
+      graph = await runGraph(seedIds(direct));
+    ranked = fuseCandidates([
+      ...fast.flatMap((result) => result.candidates),
+      ...expanded.flatMap((result) => result.candidates),
+      ...graph
+    ], rrfOptions);
+    ranked = await applyOptionalRerank(ranked);
+  } else {
+    ranked = await applyOptionalRerank(direct);
+    if (graphAttempted)
+      graph = await runGraph(seedIds(ranked));
+    ranked = annotateGraphChannels(ranked, graph);
+    const present = new Set(ranked.map((item) => item.documentId));
+    const extra = graph.filter((candidate) => !present.has(candidate.documentId));
+    if (extra.length > 0) {
+      ranked = [
+        ...ranked,
+        ...fuseCandidates(extra, rrfOptions).filter((item) => !present.has(item.documentId))
+      ];
+    }
   }
-  const ranked = fuseCandidates([
-    ...fast.flatMap((result) => result.candidates),
-    ...expanded.flatMap((result) => result.candidates),
-    ...graph
-  ], {
-    rrfK: config3.SEARCH_RRF_K,
-    exactBoost: config3.SEARCH_EXACT_BOOST,
-    channelAgreementBoost: config3.SEARCH_CHANNEL_AGREEMENT_BOOST,
-    graphMaxContribution: config3.SEARCH_GRAPH_MAX_CONTRIBUTION,
-    vectorMinSimilarity: config3.SEARCH_VECTOR_MIN_SIMILARITY
-  });
   const filters = request.filters;
   const hasFilters = Boolean(filters && Object.values(filters).some((value) => Array.isArray(value) ? value.length > 0 : value !== undefined));
   const filtered = hasFilters || request.visibilityScope !== undefined ? await filterRanked(ctx, ranked, filters ?? {}, request.visibilityScope) : ranked;
@@ -232881,7 +233214,11 @@ async function searchDocuments(ctx, request, adapters = {}) {
     graphAttempted,
     graphFailed,
     graphContribution,
-    confidenceReasons: confidence.reasons
+    confidenceReasons: confidence.reasons,
+    rerankAttempted,
+    rerankUsed,
+    rerankFallback,
+    ...rerankModel ? { rerankModel } : {}
   };
   return {
     items,
@@ -233049,6 +233386,24 @@ function clampPage(value) {
     return 1;
   return Math.max(1, Math.floor(value));
 }
+function annotateGraphChannels(items, graphCandidates) {
+  if (graphCandidates.length === 0)
+    return items;
+  const graphIds = new Set(graphCandidates.map((candidate) => candidate.documentId));
+  return items.map((item) => {
+    if (!graphIds.has(item.documentId) || item.channels.includes("graph")) {
+      return item;
+    }
+    return {
+      ...item,
+      channels: [...item.channels, "graph"],
+      explanations: [
+        ...item.explanations,
+        { channel: "graph", label: "Related document" }
+      ]
+    };
+  });
+}
 
 // ../../backend/src/api/routes/search.ts
 var BENCHMARK_SEARCH_PROFILE_HEADER = "x-docsmint-search-profile";
@@ -235564,7 +235919,42 @@ async function extractEntities(chunkText2, documentId, options = {}) {
   return { status: "ready", entities };
 }
 function hasConfiguredGraphProvider(options) {
-  return Boolean(options.llmBaseUrl || config3.GRAPH_EXTRACT_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_BASE_URL);
+  return Boolean(options.llmBaseUrl || config3.GRAPH_EXTRACT_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_BASE_URL || config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL);
+}
+function graphExtractProviders(options) {
+  const timeoutMs = config3.GRAPH_EXTRACT_TIMEOUT_MS;
+  const primaryModel = options.llmModel ?? config3.GRAPH_EXTRACT_MODEL ?? "gpt-4o-mini";
+  const slots = [
+    {
+      baseUrl: options.llmBaseUrl ?? config3.GRAPH_EXTRACT_BASE_URL,
+      explicitKey: options.llmApiKey ?? config3.GRAPH_EXTRACT_API_KEY,
+      model: primaryModel,
+      reasoningEffort: options.reasoningEffort ?? config3.GRAPH_EXTRACT_REASONING_EFFORT
+    },
+    {
+      baseUrl: config3.GRAPH_EXTRACT_FALLBACK_BASE_URL,
+      explicitKey: config3.GRAPH_EXTRACT_FALLBACK_API_KEY,
+      model: config3.GRAPH_EXTRACT_FALLBACK_MODEL ?? primaryModel,
+      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
+    },
+    {
+      baseUrl: config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL,
+      explicitKey: config3.GRAPH_EXTRACT_FALLBACK_2_API_KEY,
+      model: config3.GRAPH_EXTRACT_FALLBACK_2_MODEL,
+      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
+    }
+  ];
+  return uniqueChatProviders(slots.map((slot) => {
+    if (!slot.baseUrl || !slot.model)
+      return;
+    return {
+      baseUrl: slot.baseUrl,
+      apiKey: resolveGraphProviderKey(slot.baseUrl, slot.explicitKey),
+      model: slot.model,
+      timeoutMs,
+      reasoningEffort: slot.reasoningEffort
+    };
+  }));
 }
 var SYSTEM_PROMPT = [
   "You are an entity-extraction assistant for a knowledge-base system.",
@@ -235600,39 +235990,13 @@ var extractionOutputSchema = exports_external2.object({
   entities: exports_external2.array(exports_external2.unknown())
 });
 async function callEntityExtractionLLM(text4, options) {
-  const primaryBase = options.llmBaseUrl ?? config3.GRAPH_EXTRACT_BASE_URL;
-  const primaryExplicitKey = options.llmApiKey ?? config3.GRAPH_EXTRACT_API_KEY;
-  const primaryModel = options.llmModel ?? config3.GRAPH_EXTRACT_MODEL ?? "gpt-4o-mini";
-  const primaryKey2 = primaryBase ? resolveGraphProviderKey(primaryBase, primaryExplicitKey) : "";
-  const fallbackBase = config3.GRAPH_EXTRACT_FALLBACK_BASE_URL;
-  const fallbackExplicitKey = config3.GRAPH_EXTRACT_FALLBACK_API_KEY;
-  const fallbackModel = config3.GRAPH_EXTRACT_FALLBACK_MODEL ?? primaryModel;
-  const fallbackKey = fallbackBase ? resolveGraphProviderKey(fallbackBase, fallbackExplicitKey) : "";
-  const providers = [];
-  if (primaryBase) {
-    providers.push({
-      baseUrl: primaryBase,
-      apiKey: primaryKey2,
-      model: primaryModel,
-      timeoutMs: config3.GRAPH_EXTRACT_TIMEOUT_MS,
-      reasoningEffort: options.reasoningEffort ?? config3.GRAPH_EXTRACT_REASONING_EFFORT
-    });
-  }
-  if (fallbackBase && (fallbackBase !== primaryBase || fallbackKey !== primaryKey2 || fallbackModel !== primaryModel)) {
-    providers.push({
-      baseUrl: fallbackBase,
-      apiKey: fallbackKey,
-      model: fallbackModel,
-      timeoutMs: config3.GRAPH_EXTRACT_TIMEOUT_MS,
-      reasoningEffort: config3.GRAPH_EXTRACT_REASONING_EFFORT
-    });
-  }
-  const [primary, fallback] = providers;
+  const providers = graphExtractProviders(options);
+  const [primary, ...fallbacks] = providers;
   if (!primary)
     return null;
   const result = await requestStructuredChat({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       { role: "system", content: SYSTEM_PROMPT },
       { role: "user", content: text4 }
@@ -235890,10 +236254,13 @@ async function requestKnowledgeSummary(document2) {
   const primary = provider(config3.GRAPH_EXTRACT_BASE_URL, config3.GRAPH_EXTRACT_API_KEY, config3.GRAPH_EXTRACT_MODEL);
   if (!primary)
     return null;
-  const fallback = provider(config3.GRAPH_EXTRACT_FALLBACK_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_MODEL);
+  const fallbacks = [
+    provider(config3.GRAPH_EXTRACT_FALLBACK_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_MODEL),
+    provider(config3.GRAPH_EXTRACT_FALLBACK_2_BASE_URL, config3.GRAPH_EXTRACT_FALLBACK_2_API_KEY, config3.GRAPH_EXTRACT_FALLBACK_2_MODEL)
+  ].filter((item) => Boolean(item));
   const result = await requestStructuredChat({
     primary,
-    fallback,
+    fallbacks,
     messages: [
       { role: "system", content: systemPrompt },
       {
@@ -236328,7 +236695,7 @@ function providerProfile(name) {
   };
 }
 function configuredEmbeddingProvider() {
-  const model = config3.EMBEDDING_MODEL ?? config3.EMBEDDING_FALLBACK_MODEL ?? "";
+  const model = config3.EMBEDDING_MODEL ?? config3.EMBEDDING_FALLBACK_MODEL ?? config3.EMBEDDING_FALLBACK_2_MODEL ?? "";
   return {
     model,
     profile: embeddingProfileId(model, EMBEDDING_DIMENSIONS, "v1"),
@@ -236339,6 +236706,10 @@ function configuredEmbeddingProvider() {
         config3.EMBEDDING_FALLBACK_BASE_URL ?? "",
         config3.EMBEDDING_FALLBACK_MODEL ?? ""
       ],
+      fallback_2: [
+        config3.EMBEDDING_FALLBACK_2_BASE_URL ?? "",
+        config3.EMBEDDING_FALLBACK_2_MODEL ?? ""
+      ],
       dimensions: EMBEDDING_DIMENSIONS,
       profileVersion: "v1"
     })
@@ -237571,7 +237942,7 @@ var swaggerConfig = {
     },
     info: {
       title: "DocsMint API",
-      version: "0.7.5",
+      version: "0.8.1",
       description: "Self-hosted AI-native knowledge workspace and installable PWA with hybrid search, GraphRAG, REST, SDK, CLI, and MCP access for people and AI agents.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {
@@ -237632,7 +238003,7 @@ app.listen({
   idleTimeout: 30,
   maxRequestBodySize: MAX_BODY_SIZE_BYTES
 });
-logger3.info({ port: config3.API_PORT }, "hiai-docs API started");
+logger3.info({ port: config3.API_PORT }, "DocsMint API started");
 var stopDocsMintApi = async () => {
   logger3.info("Shutting down...");
   attachmentUploadCleanup.stop();

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * hiai-docs REST API client.
+ * DocsMint REST API client.
  *
  * Bun-native `fetch` wrapper. All authenticated requests send
  * `Authorization: Bearer <apiKey>`. Non-OK responses throw
@@ -9,7 +9,7 @@
  */
 import type { DocsApiKeyCreated, DocsApiKeyListResponse, DocsAttachment, DocsAttachmentConfirmInput, DocsAttachmentListResponse, DocsAttachmentPresignInput, DocsAttachmentPresignResponse, DocsCategory, DocsCategoryInput, DocsCategoryUpdate, DocsDocument, DocsDocumentCreateInput, DocsDocumentCursorPage, DocsDocumentIndexRefresh, DocsDocumentIndexStatus, DocsDocumentKnowledgeSummary, DocsDocumentListResponse, DocsDocumentPipeline, DocsDocumentUpdateInput, DocsFolder, DocsFolderCreateInput, DocsFolderUpdateInput, DocsGraphEntitiesResponse, DocsGraphRelatedResponse, DocsGraphSearchResponse, DocsHealthResponse, DocsRequestContext, DocsSearchOptions, DocsSearchResponse, DocsSearchSuggestItem, DocsSharedContent, DocsShareLink, DocsShareListResponse, DocsShareRole, DocsTag, DocsVersion, DocsVersionDiff } from "./types.js";
 export interface DocsClientConfig {
-    /** Base URL of the hiai-docs API, e.g. `http://localhost:50700`. */
+    /** Base URL of the DocsMint API, e.g. `http://localhost:50700`. */
     baseUrl: string;
     /** Bearer token used as `Authorization: Bearer <apiKey>`. */
     apiKey?: string;

package/dist/client.js

@@ -1,5 +1,5 @@
 /**
- * hiai-docs REST API client.
+ * DocsMint REST API client.
  *
  * Bun-native `fetch` wrapper. All authenticated requests send
  * `Authorization: Bearer <apiKey>`. Non-OK responses throw
@@ -18,7 +18,7 @@ export class DocsApiError extends Error {
     url;
     requestId;
     constructor(status, body, message, metadata, code) {
-        super(message ?? `hiai-docs API error ${status}`);
+        super(message ?? `DocsMint API error ${status}`);
         this.name = "DocsApiError";
         this.status = status;
         this.code = code ?? DocsApiError.codeFromBody(status, body);
@@ -65,7 +65,7 @@ export class DocsNetworkError extends Error {
 export class DocsTimeoutError extends DocsNetworkError {
     timeout;
     constructor(timeout, options) {
-        super(`hiai-docs request timed out after ${timeout}ms`, options);
+        super(`DocsMint request timed out after ${timeout}ms`, options);
         this.name = "DocsTimeoutError";
         this.timeout = timeout;
     }
@@ -587,7 +587,7 @@ export class DocsClient {
                 "message" in body &&
                 typeof body.message === "string"
                 ? body.message
-                : `hiai-docs API error ${res.status}`;
+                : `DocsMint API error ${res.status}`;
         return new DocsApiError(res.status, body, message, {
             url: res.url || undefined,
             requestId: res.headers.get("x-request-id") ?? undefined,
@@ -595,12 +595,12 @@ export class DocsClient {
     }
     wrapNetworkError(err, requestId) {
         if (err instanceof Error) {
-            return new DocsNetworkError(`hiai-docs network error: ${err.message}`, {
+            return new DocsNetworkError(`DocsMint network error: ${err.message}`, {
                 cause: err,
                 requestId,
             });
         }
-        return new DocsNetworkError(`hiai-docs network error: ${String(err)}`, {
+        return new DocsNetworkError(`DocsMint network error: ${String(err)}`, {
             requestId,
         });
     }

package/dist/lifecycle-runtime.js

@@ -54571,6 +54571,19 @@ function date4(params) {
 
 // ../../node_modules/.bun/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
+// ../../backend/src/lib/openrouter-public-matrix.ts
+var OPENROUTER_PUBLIC_BASE_URL = "https://openrouter.ai/api/v1";
+var OPENROUTER_PUBLIC_EXPANSION_MODELS = {
+  primary: "poolside/laguna-xs-2.1",
+  fallback: "openai/gpt-5.6-luna",
+  fallback_2: "google/gemini-3.5-flash-lite"
+};
+var OPENROUTER_PUBLIC_RERANK_MODELS = {
+  primary: "voyageai/rerank-2.5",
+  fallback: "cohere/rerank-v3.5",
+  fallback_2: "nvidia/llama-nemotron-rerank-vl-1b-v2:free"
+};
+
 // ../../backend/src/lib/config-schema.ts
 var envSchema = exports_external.object({
   DATABASE_URL: exports_external.string().default("postgresql://hiai_app:changeme@localhost:5437/hiai_docs"),
@@ -54627,6 +54640,9 @@ var envSchema = exports_external.object({
   EMBEDDING_FALLBACK_BASE_URL: exports_external.string().optional(),
   EMBEDDING_FALLBACK_API_KEY: exports_external.string().optional(),
   EMBEDDING_FALLBACK_MODEL: exports_external.string().optional(),
+  EMBEDDING_FALLBACK_2_BASE_URL: exports_external.string().optional(),
+  EMBEDDING_FALLBACK_2_API_KEY: exports_external.string().optional(),
+  EMBEDDING_FALLBACK_2_MODEL: exports_external.string().optional(),
   API_PORT: exports_external.coerce.number().default(50700),
   NODE_ENV: exports_external.enum(["development", "production", "test"]).default("development"),
   LOG_LEVEL: exports_external.enum(["trace", "debug", "info", "warn", "error", "fatal"]).default("info"),
@@ -54653,14 +54669,34 @@ var envSchema = exports_external.object({
   GRAPH_EXTRACT_FALLBACK_BASE_URL: exports_external.string().optional(),
   GRAPH_EXTRACT_FALLBACK_API_KEY: exports_external.string().optional(),
   GRAPH_EXTRACT_FALLBACK_MODEL: exports_external.string().optional(),
+  GRAPH_EXTRACT_FALLBACK_2_BASE_URL: exports_external.string().optional(),
+  GRAPH_EXTRACT_FALLBACK_2_API_KEY: exports_external.string().optional(),
+  GRAPH_EXTRACT_FALLBACK_2_MODEL: exports_external.string().optional(),
   GRAPH_EXTRACT_MIN_CONFIDENCE: exports_external.coerce.number().min(0).max(1).default(0.5),
   SEARCH_EXPANSION_ENABLED: exports_external.string().optional().default("true").transform((v2) => v2 === "true"),
-  SEARCH_EXPANSION_BASE_URL: exports_external.string().default("https://openrouter.ai/api/v1"),
+  SEARCH_EXPANSION_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
   SEARCH_EXPANSION_API_KEY: exports_external.string().optional(),
-  SEARCH_EXPANSION_MODEL: exports_external.string().default("mistralai/ministral-14b-2512"),
-  SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external.string().default("https://openrouter.ai/api/v1"),
+  SEARCH_EXPANSION_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.primary),
+  SEARCH_EXPANSION_FALLBACK_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
   SEARCH_EXPANSION_FALLBACK_API_KEY: exports_external.string().optional(),
-  SEARCH_EXPANSION_FALLBACK_MODEL: exports_external.string().default("google/gemma-4-31b-it"),
+  SEARCH_EXPANSION_FALLBACK_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback),
+  SEARCH_EXPANSION_FALLBACK_2_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
+  SEARCH_EXPANSION_FALLBACK_2_API_KEY: exports_external.string().optional(),
+  SEARCH_EXPANSION_FALLBACK_2_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_EXPANSION_MODELS.fallback_2),
+  SEARCH_RERANK_ENABLED: exports_external.string().optional().default("true").transform((v2) => v2 === "true"),
+  SEARCH_RERANK_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
+  SEARCH_RERANK_API_KEY: exports_external.string().optional(),
+  SEARCH_RERANK_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.primary),
+  SEARCH_RERANK_FALLBACK_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
+  SEARCH_RERANK_FALLBACK_API_KEY: exports_external.string().optional(),
+  SEARCH_RERANK_FALLBACK_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback),
+  SEARCH_RERANK_FALLBACK_2_BASE_URL: exports_external.string().default(OPENROUTER_PUBLIC_BASE_URL),
+  SEARCH_RERANK_FALLBACK_2_API_KEY: exports_external.string().optional(),
+  SEARCH_RERANK_FALLBACK_2_MODEL: exports_external.string().default(OPENROUTER_PUBLIC_RERANK_MODELS.fallback_2),
+  SEARCH_RERANK_TIMEOUT_MS: exports_external.coerce.number().int().min(250).max(30000).default(3000),
+  SEARCH_RERANK_TOP_N: exports_external.coerce.number().int().min(1).max(100).default(20),
+  SEARCH_RERANK_MAX_CHARS: exports_external.coerce.number().int().min(120).max(8000).default(1500),
+  SEARCH_RERANK_GRAPH_POSITION: exports_external.enum(["before", "after"]).default("after"),
   SEARCH_EXPANSION_TIMEOUT_MS: exports_external.coerce.number().int().min(1000).max(300000).default(6000),
   SEARCH_VECTOR_PROVIDER_TIMEOUT_MS: exports_external.coerce.number().int().min(250).max(30000).default(2500),
   SEARCH_EXPANSION_CACHE_TTL_SECONDS: exports_external.coerce.number().int().min(0).max(2592000).default(86400),

package/dist/mcp-cli.js

@@ -32,7 +32,7 @@ class DocsApiError extends Error {
   url;
   requestId;
   constructor(status, body, message, metadata, code) {
-    super(message ?? `hiai-docs API error ${status}`);
+    super(message ?? `DocsMint API error ${status}`);
     this.name = "DocsApiError";
     this.status = status;
     this.code = code ?? DocsApiError.codeFromBody(status, body);
@@ -64,7 +64,7 @@ class DocsNetworkError extends Error {
 class DocsTimeoutError extends DocsNetworkError {
   timeout;
   constructor(timeout, options) {
-    super(`hiai-docs request timed out after ${timeout}ms`, options);
+    super(`DocsMint request timed out after ${timeout}ms`, options);
     this.name = "DocsTimeoutError";
     this.timeout = timeout;
   }
@@ -501,7 +501,7 @@ class DocsClient {
     } catch {
       body = null;
     }
-    const message = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : body && typeof body === "object" && ("message" in body) && typeof body.message === "string" ? body.message : `hiai-docs API error ${res.status}`;
+    const message = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : body && typeof body === "object" && ("message" in body) && typeof body.message === "string" ? body.message : `DocsMint API error ${res.status}`;
     return new DocsApiError(res.status, body, message, {
       url: res.url || undefined,
       requestId: res.headers.get("x-request-id") ?? undefined
@@ -509,12 +509,12 @@ class DocsClient {
   }
   wrapNetworkError(err, requestId) {
     if (err instanceof Error) {
-      return new DocsNetworkError(`hiai-docs network error: ${err.message}`, {
+      return new DocsNetworkError(`DocsMint network error: ${err.message}`, {
         cause: err,
         requestId
       });
     }
-    return new DocsNetworkError(`hiai-docs network error: ${String(err)}`, {
+    return new DocsNetworkError(`DocsMint network error: ${String(err)}`, {
       requestId
     });
   }
@@ -1046,7 +1046,7 @@ function registerDocsmintMcpCapabilities(server, client2) {
   registerExtendedCapabilities(server, client2, (handler11) => wrapHandler("extended", handler11));
 }
 function createDocsmintMcpServer(options = {}) {
-  const server = new McpServer({ name: "docsmint", version: "0.7.5" });
+  const server = new McpServer({ name: "docsmint", version: "0.8.1" });
   const client2 = options.docsClient ? createMcpDocsClient(options.docsClient, options.requestContext) : options.client ?? createMcpDocsClient(createDefaultDocsClient(), options.requestContext);
   registerDocsmintMcpCapabilities(server, client2);
   return server;

package/dist/mcp-server.js

@@ -28,7 +28,7 @@ class DocsApiError extends Error {
   url;
   requestId;
   constructor(status, body, message, metadata, code) {
-    super(message ?? `hiai-docs API error ${status}`);
+    super(message ?? `DocsMint API error ${status}`);
     this.name = "DocsApiError";
     this.status = status;
     this.code = code ?? DocsApiError.codeFromBody(status, body);
@@ -60,7 +60,7 @@ class DocsNetworkError extends Error {
 class DocsTimeoutError extends DocsNetworkError {
   timeout;
   constructor(timeout, options) {
-    super(`hiai-docs request timed out after ${timeout}ms`, options);
+    super(`DocsMint request timed out after ${timeout}ms`, options);
     this.name = "DocsTimeoutError";
     this.timeout = timeout;
   }
@@ -497,7 +497,7 @@ class DocsClient {
     } catch {
       body = null;
     }
-    const message = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : body && typeof body === "object" && ("message" in body) && typeof body.message === "string" ? body.message : `hiai-docs API error ${res.status}`;
+    const message = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : body && typeof body === "object" && ("message" in body) && typeof body.message === "string" ? body.message : `DocsMint API error ${res.status}`;
     return new DocsApiError(res.status, body, message, {
       url: res.url || undefined,
       requestId: res.headers.get("x-request-id") ?? undefined
@@ -505,12 +505,12 @@ class DocsClient {
   }
   wrapNetworkError(err, requestId) {
     if (err instanceof Error) {
-      return new DocsNetworkError(`hiai-docs network error: ${err.message}`, {
+      return new DocsNetworkError(`DocsMint network error: ${err.message}`, {
         cause: err,
         requestId
       });
     }
-    return new DocsNetworkError(`hiai-docs network error: ${String(err)}`, {
+    return new DocsNetworkError(`DocsMint network error: ${String(err)}`, {
       requestId
     });
   }
@@ -1042,7 +1042,7 @@ function registerDocsmintMcpCapabilities(server, client2) {
   registerExtendedCapabilities(server, client2, (handler11) => wrapHandler("extended", handler11));
 }
 function createDocsmintMcpServer(options = {}) {
-  const server = new McpServer({ name: "docsmint", version: "0.7.5" });
+  const server = new McpServer({ name: "docsmint", version: "0.8.1" });
   const client2 = options.docsClient ? createMcpDocsClient(options.docsClient, options.requestContext) : options.client ?? createMcpDocsClient(createDefaultDocsClient(), options.requestContext);
   registerDocsmintMcpCapabilities(server, client2);
   return server;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hiai-gg/docsmint",
   "mcpName": "io.github.HiAi-gg/docsmint",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "type": "module",
   "browser": {
     "./dist/backend-launcher.js": false,

package/packages/cli/src/index.ts

@@ -25,7 +25,7 @@ import { registerSearch } from './commands/search.js';
 import { registerSnapshot } from './commands/snapshot.js';
 import { registerUpdate } from './commands/update.js';
 
-const VERSION = '0.7.5';
+const VERSION = '0.8.1';
 
 const program = new Command();
 program.name('docsmint').description('CLI for the DocsMint knowledge workspace').version(VERSION);

package/server.json

@@ -10,7 +10,7 @@
     "id": "1249550690",
     "subfolder": "packages/mcp-server"
   },
-  "version": "0.7.5",
+  "version": "0.8.1",
   "icons": [
     {
       "src": "https://raw.githubusercontent.com/HiAi-gg/docsmint/main/frontend/static/logo-dark.png",
@@ -30,7 +30,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@hiai-gg/docsmint",
-      "version": "0.7.5",
+      "version": "0.8.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/skills/docsmint-document-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docsmint-document-manager
-description: Manage and research DocsMint documents through its scoped MCP tools, including categories, folders, hybrid search, GraphRAG, and index refresh.
+description: Manage and research DocsMint documents through its scoped MCP tools, including categories, folders, hybrid search, GraphRAG, rerank, and index refresh.
 ---
 
 # DocsMint Document Manager
@@ -30,4 +30,4 @@ Use this skill when an agent must create, organize, edit, or research documents
 4. After an update, inspect `get_document_index_status`; use `refresh_document_index` only when indexing is stale or failed.
 5. Use snapshots before a substantial rewrite when version history is important.
 
-DocsMint owns chunking, embeddings, multilingual hybrid retrieval, entity extraction, and GraphRAG indexing. Agents must use the MCP tools and never write those persistence layers directly.
+DocsMint owns chunking, embeddings, multilingual hybrid retrieval, cross-encoder rerank, entity extraction, and GraphRAG indexing. Agents must use the MCP tools and never write those persistence layers directly.