@gmickel/gno 0.5.0 → 0.6.0

package/assets/skill/cli-reference.md

@@ -130,6 +130,14 @@ Hybrid search with expansion and reranking.
 gno query <query> [options]
 ```
 
+**Search modes** (pick one):
+
+| Flag | Time | Description |
+|------|------|-------------|
+| `--fast` | ~0.7s | Skip expansion and reranking |
+| (default) | ~2-3s | Skip expansion, with reranking |
+| `--thorough` | ~5-8s | Full pipeline with expansion |
+
 Additional options:
 
 | Option | Description |
@@ -148,6 +156,8 @@ gno ask <question> [options]
 
 | Option | Description |
 |--------|-------------|
+| `--fast` | Skip expansion and reranking (fastest) |
+| `--thorough` | Enable query expansion (better recall) |
 | `--answer` | Generate grounded answer |
 | `--no-answer` | Retrieval only |
 | `--max-answer-tokens <n>` | Cap answer length |

package/assets/skill/examples.md

@@ -193,13 +193,19 @@ gno models pull
 
 ## Tips
 
-### Speed vs Quality
-
-| Command | Speed | Quality | Use When |
-|---------|-------|---------|----------|
-| `gno search` | Fast | Good for keywords | Exact phrase matching |
-| `gno vsearch` | Medium | Good for concepts | Finding similar meaning |
-| `gno query` | Slower | Best | Important queries |
+### Search Modes
+
+| Command | Time | Use When |
+|---------|------|----------|
+| `gno search` | instant | Exact keyword matching |
+| `gno vsearch` | ~0.5s | Finding similar concepts |
+| `gno query --fast` | ~0.7s | Quick lookups |
+| `gno query` | ~2-3s | Default, balanced |
+| `gno query --thorough` | ~5-8s | Best recall, complex queries |
+
+**Agent retry strategy**: Use default mode first. If no results:
+1. Rephrase the query (free, often helps)
+2. Try `--thorough` for better recall
 
 ### Output formats
 

package/assets/skill/mcp-reference.md

@@ -60,12 +60,24 @@ Hybrid search (best quality).
 {
   "query": "search terms",
   "collection": "optional-collection",
-  "limit": 5,
-  "expand": true,
-  "rerank": true
+  "limit": 5
 }
 ```
 
+**Search modes** (via parameters):
+
+| Mode | Parameters | Time |
+|------|------------|------|
+| Fast | `fast: true` | ~0.7s |
+| Default | (none) | ~2-3s |
+| Thorough | `thorough: true` | ~5-8s |
+
+Default skips expansion, with reranking. Use `thorough: true` for best recall.
+
+**Agent retry strategy**: Use default mode first. If no relevant results:
+1. Rephrase the query (free, often effective)
+2. Then try `thorough: true` for better recall
+
 ### gno.get
 
 Retrieve document by reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "search",
@@ -29,7 +29,8 @@
   },
   "files": [
     "src",
-    "assets"
+    "assets",
+    "vendor"
   ],
   "engines": {
     "bun": ">=1.0.0"
@@ -98,7 +99,7 @@
     "streamdown": "^1.6.10",
     "tailwind-merge": "^3.4.0",
     "use-stick-to-bottom": "^1.1.1",
-    "zod": "^4.2.1"
+    "zod": "^4.3.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.10",
@@ -111,12 +112,12 @@
     "docx": "^9.5.1",
     "evalite": "^1.0.0-beta.15",
     "exceljs": "^4.4.0",
-    "lefthook": "^2.0.12",
+    "lefthook": "^2.0.13",
     "oxlint-tsgolint": "^0.10.0",
     "pdf-lib": "^1.17.1",
     "pptxgenjs": "^4.0.1",
     "tailwindcss": "^4.1.18",
-    "ultracite": "^6.5.0"
+    "ultracite": "6.5.0"
   },
   "peerDependencies": {
     "typescript": "^5"

package/src/cli/commands/ask.ts

@@ -89,18 +89,24 @@ export async function ask(
       embedPort = embedResult.value;
     }
 
-    // Create generation port (for expansion and answer)
-    const genUri = options.genModel ?? preset.gen;
-    const genResult = await llm.createGenerationPort(genUri);
-    if (genResult.ok) {
-      genPort = genResult.value;
+    // Create generation port (for expansion and/or answer)
+    // Need genPort if: expansion enabled (!noExpand) OR answer requested
+    const needsGen = !options.noExpand || options.answer;
+    if (needsGen) {
+      const genUri = options.genModel ?? preset.gen;
+      const genResult = await llm.createGenerationPort(genUri);
+      if (genResult.ok) {
+        genPort = genResult.value;
+      }
     }
 
-    // Create rerank port
-    const rerankUri = options.rerankModel ?? preset.rerank;
-    const rerankResult = await llm.createRerankPort(rerankUri);
-    if (rerankResult.ok) {
-      rerankPort = rerankResult.value;
+    // Create rerank port (unless --fast or --no-rerank)
+    if (!options.noRerank) {
+      const rerankUri = options.rerankModel ?? preset.rerank;
+      const rerankResult = await llm.createRerankPort(rerankUri);
+      if (rerankResult.ok) {
+        rerankPort = rerankResult.value;
+      }
     }
 
     // Create vector index
@@ -147,6 +153,8 @@ export async function ask(
       limit,
       collection: options.collection,
       lang: options.lang,
+      noExpand: options.noExpand,
+      noRerank: options.noRerank,
     });
 
     if (!searchResult.ok) {

package/src/cli/program.ts

@@ -312,6 +312,8 @@ function wireSearchCommands(program: Command): void {
     .option('--lang <code>', 'language hint (BCP-47)')
     .option('--full', 'include full content')
     .option('--line-numbers', 'include line numbers in output')
+    .option('--fast', 'skip expansion and reranking (fastest, ~0.7s)')
+    .option('--thorough', 'enable query expansion (slower, ~5-8s)')
     .option('--no-expand', 'disable query expansion')
     .option('--no-rerank', 'disable reranking')
     .option('--explain', 'include scoring explanation')
@@ -339,6 +341,30 @@ function wireSearchCommands(program: Command): void {
         ? parsePositiveInt('limit', cmdOpts.limit)
         : getDefaultLimit(format);
 
+      // Determine expansion/rerank settings based on flags
+      // Priority: --fast > --thorough > --no-expand/--no-rerank > default
+      // Default: skip expansion (balanced mode ~2-3s)
+      let noExpand = true; // Default: skip expansion
+      let noRerank = false; // Default: with reranking
+
+      if (cmdOpts.fast) {
+        // --fast: skip both (~0.7s)
+        noExpand = true;
+        noRerank = true;
+      } else if (cmdOpts.thorough) {
+        // --thorough: full pipeline (~5-8s)
+        noExpand = false;
+        noRerank = false;
+      } else {
+        // Check individual flags (override defaults)
+        if (cmdOpts.expand === false) {
+          noExpand = true;
+        }
+        if (cmdOpts.rerank === false) {
+          noRerank = true;
+        }
+      }
+
       const { query, formatQuery } = await import('./commands/query');
       const result = await query(queryText, {
         limit,
@@ -347,8 +373,8 @@ function wireSearchCommands(program: Command): void {
         lang: cmdOpts.lang as string | undefined,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
-        noExpand: cmdOpts.expand === false,
-        noRerank: cmdOpts.rerank === false,
+        noExpand,
+        noRerank,
         explain: Boolean(cmdOpts.explain),
         json: format === 'json',
         md: format === 'md',
@@ -376,6 +402,8 @@ function wireSearchCommands(program: Command): void {
     .option('-n, --limit <num>', 'max source results')
     .option('-c, --collection <name>', 'filter by collection')
     .option('--lang <code>', 'language hint (BCP-47)')
+    .option('--fast', 'skip expansion and reranking (fastest)')
+    .option('--thorough', 'enable query expansion (slower)')
     .option('--answer', 'generate short grounded answer')
     .option('--no-answer', 'force retrieval-only output')
     .option('--max-answer-tokens <num>', 'max answer tokens')
@@ -400,12 +428,27 @@ function wireSearchCommands(program: Command): void {
         ? parsePositiveInt('max-answer-tokens', cmdOpts.maxAnswerTokens)
         : undefined;
 
+      // Determine expansion/rerank settings based on flags
+      // Default: skip expansion (balanced mode)
+      let noExpand = true;
+      let noRerank = false;
+
+      if (cmdOpts.fast) {
+        noExpand = true;
+        noRerank = true;
+      } else if (cmdOpts.thorough) {
+        noExpand = false;
+        noRerank = false;
+      }
+
       const { ask, formatAsk } = await import('./commands/ask');
       const showSources = Boolean(cmdOpts.showSources);
       const result = await ask(queryText, {
         limit,
         collection: cmdOpts.collection as string | undefined,
         lang: cmdOpts.lang as string | undefined,
+        noExpand,
+        noRerank,
         // Per spec: --answer defaults to false, --no-answer forces retrieval-only
         // Commander creates separate cmdOpts.noAnswer for --no-answer flag
         answer: Boolean(cmdOpts.answer),

package/src/index.ts

@@ -7,21 +7,35 @@
  */
 
 import { runCli } from './cli/run';
+import { resetModelManager } from './llm/nodeLlamaCpp/lifecycle';
+
+/**
+ * Cleanup models and exit.
+ * Without this, llama.cpp native threads can keep the process alive.
+ */
+async function cleanupAndExit(code: number): Promise<never> {
+  await resetModelManager().catch(() => {
+    // Ignore cleanup errors on exit
+  });
+  process.exit(code);
+}
 
 // SIGINT handler for graceful shutdown
 process.on('SIGINT', () => {
   process.stderr.write('\nInterrupted\n');
-  process.exit(130);
+  cleanupAndExit(130).catch(() => {
+    // Ignore cleanup errors on exit
+  });
 });
 
 // Run CLI and exit
 runCli(process.argv)
-  .then((code) => {
-    process.exit(code);
-  })
+  .then((code) => cleanupAndExit(code))
   .catch((err) => {
     process.stderr.write(
       `Fatal error: ${err instanceof Error ? err.message : String(err)}\n`
     );
-    process.exit(1);
+    cleanupAndExit(1).catch(() => {
+      // Ignore cleanup errors on exit
+    });
   });

package/src/mcp/tools/index.ts

@@ -40,7 +40,9 @@ const queryInputSchema = z.object({
   limit: z.number().int().min(1).max(100).default(5),
   minScore: z.number().min(0).max(1).optional(),
   lang: z.string().optional(),
-  expand: z.boolean().default(true),
+  fast: z.boolean().default(false),
+  thorough: z.boolean().default(false),
+  expand: z.boolean().default(false), // Default: skip expansion
   rerank: z.boolean().default(true),
 });
 

package/src/mcp/tools/query.ts

@@ -28,6 +28,8 @@ interface QueryInput {
   limit?: number;
   minScore?: number;
   lang?: string;
+  fast?: boolean;
+  thorough?: boolean;
   expand?: boolean;
   rerank?: boolean;
 }
@@ -138,9 +140,30 @@ export function handleQuery(
           embedPort = embedResult.value;
         }
 
+        // Determine noExpand/noRerank based on mode flags
+        // Priority: fast > thorough > expand/rerank params > defaults
+        // Default: noExpand=true (skip expansion), noRerank=false (with reranking)
+        let noExpand = true;
+        let noRerank = false;
+
+        if (args.fast) {
+          noExpand = true;
+          noRerank = true;
+        } else if (args.thorough) {
+          noExpand = false;
+          noRerank = false;
+        } else {
+          // Use explicit expand/rerank params if provided
+          if (args.expand === true) {
+            noExpand = false;
+          }
+          if (args.rerank === false) {
+            noRerank = true;
+          }
+        }
+
         // Create generation port (for expansion) - optional
-        // expand defaults to true per spec
-        if (args.expand !== false) {
+        if (!noExpand) {
           const genResult = await llm.createGenerationPort(preset.gen);
           if (genResult.ok) {
             genPort = genResult.value;
@@ -148,8 +171,7 @@ export function handleQuery(
         }
 
         // Create rerank port - optional
-        // rerank defaults to true per spec
-        if (args.rerank !== false) {
+        if (!noRerank) {
           const rerankResult = await llm.createRerankPort(preset.rerank);
           if (rerankResult.ok) {
             rerankPort = rerankResult.value;
@@ -189,8 +211,8 @@ export function handleQuery(
           minScore: args.minScore,
           collection: args.collection,
           queryLanguageHint: args.lang, // Affects expansion prompt, not retrieval
-          noExpand: args.expand === false,
-          noRerank: args.rerank === false,
+          noExpand,
+          noRerank,
         });
 
         if (!result.ok) {

package/src/pipeline/rerank.ts

@@ -66,6 +66,75 @@ function blend(
   return fusionWeight * fusionScore + rerankWeight * rerankScore;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Chunk Text Extraction
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MAX_CHUNK_CHARS = 4000;
+
+interface BestChunkInfo {
+  candidate: FusionCandidate;
+  seq: number;
+}
+
+/**
+ * Extract best chunk per document for efficient reranking.
+ */
+function selectBestChunks(
+  toRerank: FusionCandidate[]
+): Map<string, BestChunkInfo> {
+  const bestChunkPerDoc = new Map<string, BestChunkInfo>();
+  for (const c of toRerank) {
+    const existing = bestChunkPerDoc.get(c.mirrorHash);
+    if (!existing || c.fusionScore > existing.candidate.fusionScore) {
+      bestChunkPerDoc.set(c.mirrorHash, { candidate: c, seq: c.seq });
+    }
+  }
+  return bestChunkPerDoc;
+}
+
+/**
+ * Fetch chunk texts for reranking.
+ */
+async function fetchChunkTexts(
+  store: StorePort,
+  bestChunkPerDoc: Map<string, BestChunkInfo>
+): Promise<{ texts: string[]; hashToIndex: Map<string, number> }> {
+  const uniqueHashes = [...bestChunkPerDoc.keys()];
+  const chunkResults = await Promise.all(
+    uniqueHashes.map((hash) => store.getChunks(hash))
+  );
+
+  const chunkTexts = new Map<string, string>();
+  for (let i = 0; i < uniqueHashes.length; i++) {
+    const hash = uniqueHashes[i] as string;
+    const result = chunkResults[i];
+    const bestInfo = bestChunkPerDoc.get(hash);
+
+    if (result?.ok && result.value && bestInfo) {
+      const chunk = result.value.find((c) => c.seq === bestInfo.seq);
+      const text = chunk?.text ?? '';
+      chunkTexts.set(
+        hash,
+        text.length > MAX_CHUNK_CHARS
+          ? `${text.slice(0, MAX_CHUNK_CHARS)}...`
+          : text
+      );
+    } else {
+      chunkTexts.set(hash, '');
+    }
+  }
+
+  const hashToIndex = new Map<string, number>();
+  const texts: string[] = [];
+  for (const hash of uniqueHashes) {
+    hashToIndex.set(hash, texts.length);
+    texts.push(chunkTexts.get(hash) ?? '');
+  }
+
+  return { texts, hashToIndex };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Rerank Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -80,7 +149,6 @@ export async function rerankCandidates(
   candidates: FusionCandidate[],
   options: RerankOptions = {}
 ): Promise<RerankResult> {
-  // Early return for empty candidates
   if (candidates.length === 0) {
     return { candidates: [], reranked: false };
   }
@@ -90,21 +158,20 @@ export async function rerankCandidates(
   const schedule = options.blendingSchedule ?? DEFAULT_BLENDING_SCHEDULE;
 
   // Normalize fusion scores to 0-1 range across ALL candidates for stability.
-  // This ensures blendedScore is always in [0,1] regardless of reranker availability.
   const fusionScoresAll = candidates.map((c) => c.fusionScore);
   const minFusionAll = Math.min(...fusionScoresAll);
   const maxFusionAll = Math.max(...fusionScoresAll);
   const fusionRangeAll = maxFusionAll - minFusionAll;
 
-  function normalizeFusionScore(score: number): number {
+  const normalizeFusionScore = (score: number): number => {
     if (fusionRangeAll < 1e-9) {
-      return 1; // tie for best
+      return 1;
     }
     const v = (score - minFusionAll) / fusionRangeAll;
     return Math.max(0, Math.min(1, v));
-  }
+  };
 
-  // If no reranker, return candidates with normalized fusion scores
+  // No reranker: return candidates with normalized fusion scores
   if (!rerankPort) {
     return {
       candidates: candidates.map((c) => ({
@@ -116,52 +183,17 @@ export async function rerankCandidates(
     };
   }
 
-  // Limit candidates for reranking
   const toRerank = candidates.slice(0, maxCandidates);
   const remaining = candidates.slice(maxCandidates);
 
-  // Dedupe by document - multiple chunks from same doc use single full-doc rerank
-  const uniqueHashes = [...new Set(toRerank.map((c) => c.mirrorHash))];
-
-  // Fetch full document content for each unique document (parallel)
-  // Max 128K chars per doc to fit in reranker context
-  const MAX_DOC_CHARS = 128_000;
-  const contentResults = await Promise.all(
-    uniqueHashes.map((hash) => store.getContent(hash))
-  );
-  const docContents = new Map<string, string>();
-  for (let i = 0; i < uniqueHashes.length; i++) {
-    const hash = uniqueHashes[i] as string;
-    const result = contentResults[i] as Awaited<
-      ReturnType<typeof store.getContent>
-    >;
-    if (result.ok && result.value) {
-      const content = result.value;
-      docContents.set(
-        hash,
-        content.length > MAX_DOC_CHARS
-          ? `${content.slice(0, MAX_DOC_CHARS)}...`
-          : content
-      );
-    } else {
-      // Fallback to empty string if content not available
-      docContents.set(hash, '');
-    }
-  }
-
-  // Build texts array for reranking (one per unique document)
-  const hashToIndex = new Map<string, number>();
-  const texts: string[] = [];
-  for (const hash of uniqueHashes) {
-    hashToIndex.set(hash, texts.length);
-    texts.push(docContents.get(hash) ?? '');
-  }
+  // Extract best chunk per document for efficient reranking
+  const bestChunkPerDoc = selectBestChunks(toRerank);
+  const { texts, hashToIndex } = await fetchChunkTexts(store, bestChunkPerDoc);
 
-  // Run reranking on full documents
+  // Run reranking on best chunks (much faster than full docs)
   const rerankResult = await rerankPort.rerank(query, texts);
 
   if (!rerankResult.ok) {
-    // Graceful degradation - return normalized fusion scores
     return {
       candidates: candidates.map((c) => ({
         ...c,
@@ -172,37 +204,29 @@ export async function rerankCandidates(
     };
   }
 
-  // Map rerank scores to candidates
-  // Note: We use normalizeFusionScore defined above (across ALL candidates)
-  // Build doc index->score map for O(1) lookup
-  // All chunks from same document share the same rerank score
+  // Normalize rerank scores using min-max
   const scoreByDocIndex = new Map(
     rerankResult.value.map((s) => [s.index, s.score])
   );
-
-  // Normalize rerank scores using min-max (models return varying scales)
   const rerankScores = rerankResult.value.map((s) => s.score);
   const minRerank = Math.min(...rerankScores);
   const maxRerank = Math.max(...rerankScores);
   const rerankRange = maxRerank - minRerank;
 
-  function normalizeRerankScore(score: number): number {
+  const normalizeRerankScore = (score: number): number => {
     if (rerankRange < 1e-9) {
-      return 1; // All tied for best
+      return 1;
     }
     return (score - minRerank) / rerankRange;
-  }
+  };
 
+  // Build reranked candidates with blended scores
   const rerankedCandidates: RerankedCandidate[] = toRerank.map((c, i) => {
-    // Get document-level rerank score (shared by all chunks from same doc)
     const docIndex = hashToIndex.get(c.mirrorHash) ?? -1;
     const rerankScore = scoreByDocIndex.get(docIndex) ?? null;
-
-    // Normalize rerank score to 0-1 range using min-max
     const normalizedRerankScore =
       rerankScore !== null ? normalizeRerankScore(rerankScore) : null;
 
-    // Calculate blended score using normalized fusion score
     const position = i + 1;
     const normalizedFusion = normalizeFusionScore(c.fusionScore);
     const blendedScore =
@@ -210,42 +234,30 @@ export async function rerankCandidates(
         ? blend(normalizedFusion, normalizedRerankScore, position, schedule)
         : normalizedFusion;
 
-    return {
-      ...c,
-      rerankScore: normalizedRerankScore,
-      blendedScore,
-    };
+    return { ...c, rerankScore: normalizedRerankScore, blendedScore };
   });
 
-  // Add remaining candidates (not reranked)
-  // These get normalized fusion scores with penalty but clamped to [0,1]
+  // Add remaining candidates with penalty
   const allCandidates: RerankedCandidate[] = [
     ...rerankedCandidates,
-    ...remaining.map((c) => {
-      const base = normalizeFusionScore(c.fusionScore);
-      return {
-        ...c,
-        rerankScore: null,
-        // Apply 0.5x penalty and clamp to [0,1]
-        blendedScore: Math.max(0, Math.min(1, base * 0.5)),
-      };
-    }),
+    ...remaining.map((c) => ({
+      ...c,
+      rerankScore: null,
+      blendedScore: Math.max(
+        0,
+        Math.min(1, normalizeFusionScore(c.fusionScore) * 0.5)
+      ),
+    })),
   ];
 
-  // Sort by blended score
+  // Sort by blended score with deterministic tie-breaking
   allCandidates.sort((a, b) => {
     const scoreDiff = b.blendedScore - a.blendedScore;
     if (Math.abs(scoreDiff) > 1e-9) {
       return scoreDiff;
     }
-    // Deterministic tie-breaking
-    const aKey = `${a.mirrorHash}:${a.seq}`;
-    const bKey = `${b.mirrorHash}:${b.seq}`;
-    return aKey.localeCompare(bKey);
+    return `${a.mirrorHash}:${a.seq}`.localeCompare(`${b.mirrorHash}:${b.seq}`);
   });
 
-  return {
-    candidates: allCandidates,
-    reranked: true,
-  };
+  return { candidates: allCandidates, reranked: true };
 }

package/vendor/fts5-snowball/LICENSE

@@ -0,0 +1,67 @@
+fts5-snowball - Snowball tokenizer for SQLite FTS5
+==================================================
+
+Copyright (c) 2016 Abilio Marques
+https://github.com/abiliojr/fts5-snowball
+
+BSD 3-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+================================================================================
+
+Snowball Stemmer Library
+========================
+
+Copyright (c) 2001-2025, Dr Martin Porter and Richard Boulton
+https://github.com/snowballstem/snowball
+
+BSD 3-Clause License
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the Snowball project nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/vendor/fts5-snowball/README.md

@@ -0,0 +1,38 @@
+# fts5-snowball Vendored Binaries
+
+Prebuilt [fts5-snowball](https://github.com/abiliojr/fts5-snowball) SQLite extension for multilingual FTS5 stemming.
+
+## Supported Platforms
+
+| Platform | File | Architecture |
+|----------|------|--------------|
+| Linux | `linux-x64/fts5stemmer.so` | x86_64 |
+| macOS | `darwin-arm64/fts5stemmer.dylib` | ARM64 (Apple Silicon) |
+| macOS | `darwin-x64/fts5stemmer.dylib` | x86_64 (Intel) |
+| Windows | `windows-x64/fts5stemmer.dll` | x86_64 |
+
+## Build Provenance
+
+Built via GitHub Actions: `.github/workflows/build-fts5-snowball.yml`
+
+Source: https://github.com/abiliojr/fts5-snowball (commit from main branch)
+
+## Supported Languages
+
+The Snowball stemmer supports: Arabic, Basque, Catalan, Danish, Dutch, English, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Irish, Italian, Lithuanian, Nepali, Norwegian, Porter, Portuguese, Romanian, Russian, Serbian, Spanish, Swedish, Tamil, Turkish, Yiddish.
+
+## Usage
+
+```typescript
+import { Database } from 'bun:sqlite';
+
+// Load extension
+db.loadExtension('vendor/fts5-snowball/darwin-arm64/fts5stemmer.dylib');
+
+// Create FTS table with snowball tokenizer
+db.exec(`CREATE VIRTUAL TABLE docs USING fts5(content, tokenize='snowball english')`);
+```
+
+## License
+
+BSD-3-Clause. See LICENSE file.