@mario-gc/pi-context7 0.1.1 → 0.2.0

package/extensions/cache.test.ts

@@ -0,0 +1,268 @@
+/**
+ * Unit tests for BM25 scoring and cache timing.
+ *
+ * Covers:
+ * - BM25 cache hit for semantically equivalent reordered queries (same tokens, different order)
+ * - BM25 cache miss for queries sharing only stopwords or insufficient term overlap
+ * - cache.set writes file + updates manifest before returning (timing guarantee)
+ * - cache.get returns BM25 hit after an awaited set completes
+ *
+ * @module extensions/cache.test
+ */
+
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { rm, mkdir, readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  bm25Find,
+  tokenize,
+  tokenizeForScoring,
+  type ManifestEntry,
+} from "./cache.ts";
+import { createCache } from "./cache.ts";
+
+// ---------------------------------------------------------------------------
+// Test fixtures — a temp cache root that doesn't touch the real cache
+// ---------------------------------------------------------------------------
+
+const TEST_CACHE_ROOT = join(tmpdir(), `context7-cache-test-${Date.now()}`);
+
+before(async () => {
+  process.env.CONTEXT7_CACHE_ROOT = TEST_CACHE_ROOT;
+  await mkdir(TEST_CACHE_ROOT, { recursive: true });
+});
+
+after(async () => {
+  delete process.env.CONTEXT7_CACHE_ROOT;
+  try {
+    await rm(TEST_CACHE_ROOT, { recursive: true, force: true });
+  } catch {
+    // best effort
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Helper: build a minimal manifest entry
+// ---------------------------------------------------------------------------
+
+function makeEntry(query: string, hash: string, scope: Record<string, string> = {}): ManifestEntry {
+  return {
+    scope,
+    query,
+    hash,
+    cachedAt: 0,
+    ttl: 300,
+    size: 100,
+  };
+}
+
+// ===========================================================================
+// BM25 Scoring Tests
+// ===========================================================================
+
+describe("BM25 scoring", () => {
+  describe("tokenizeForScoring", () => {
+    it("removes English stopwords", () => {
+      const tokens = tokenizeForScoring("how to set up express");
+      // "how", "to", "set", "up" are stopwords; only "express" remains
+      assert.deepEqual(tokens, ["express"]);
+    });
+
+    it("keeps domain-specific terms", () => {
+      const tokens = tokenizeForScoring("useState hook patterns in react");
+      // "in" is a stopword; the rest are domain terms
+      assert.deepEqual(tokens, ["usestate", "hook", "patterns", "react"]);
+    });
+
+    it("returns same tokens for reordered queries", () => {
+      const a = tokenizeForScoring("best practices for layout and content");
+      const b = tokenizeForScoring("best practices for content and layout");
+      // "for" and "and" are stopwords; both produce [best, practices, layout, content]
+      assert.deepEqual(a.sort(), b.sort());
+      assert.deepEqual(a.sort(), ["best", "content", "layout", "practices"]);
+    });
+  });
+
+  describe("bm25Find — cache hit for reordered equivalent queries", () => {
+    it("matches same tokens in different order", () => {
+      // Criterion 1 & 4: two queries with same tokens, different order
+      const entries = [
+        makeEntry("best practices for layout and content", "h1", { libraryId: "/test/lib" }),
+      ];
+
+      const result = bm25Find("best practices for content and layout", entries, 0.5);
+
+      assert.notEqual(result, null, "Should match reordered query");
+      assert.equal(result!.hash, "h1");
+    });
+
+    it("matches regardless of which query is cached vs looked up", () => {
+      const entries = [
+        makeEntry("best practices for content and layout", "h2", { libraryId: "/test/lib" }),
+      ];
+
+      const result = bm25Find("best practices for layout and content", entries, 0.5);
+
+      assert.notEqual(result, null);
+      assert.equal(result!.hash, "h2");
+    });
+  });
+
+  describe("bm25Find — cache miss for stopword-only overlap", () => {
+    it("rejects queries sharing only stopwords", () => {
+      // Criterion 5: queries sharing only stopwords after filtering
+      // "how to configure nextjs" → tokens: [configure, nextjs] (how, to are stopwords)
+      // "how to set up express" → tokens: [express] (how, to, set, up are stopwords)
+      // Overlap: 0 matching terms → miss
+      const entries = [
+        makeEntry("how to set up express", "h1", { libraryId: "/test/lib" }),
+      ];
+
+      const result = bm25Find("how to configure nextjs", entries, 0.5);
+
+      assert.equal(result, null, "Should not match on stopword-only overlap");
+    });
+  });
+
+  describe("bm25Find — cache miss for insufficient overlap", () => {
+    it("rejects queries with < 50% term overlap", () => {
+      // Criterion 5: "useState hook patterns" vs "useEffect hook cleanup"
+      // shares only "hook" (1 of 3, 33%) — below the 50% threshold
+      const entries = [
+        makeEntry("useState hook patterns", "h1", { libraryId: "/test/lib" }),
+      ];
+
+      const result = bm25Find("useEffect hook cleanup", entries, 0.5);
+
+      assert.equal(result, null, "Should not match with <50% term overlap");
+    });
+
+    it("rejects single shared term even if it's domain-specific", () => {
+      // "hook" is a domain term, but sharing only 1 of 3 terms (33%) is insufficient
+      const entries = [
+        makeEntry("react hook forms validation", "h1", { libraryId: "/test/lib" }),
+      ];
+
+      // "hook" matches, but 1/3 = 33% < 50%
+      const result = bm25Find("custom hook rendering", entries, 0.5);
+
+      assert.equal(result, null, "Should not match with single shared term");
+    });
+  });
+
+  describe("bm25Find — edge cases", () => {
+    it("returns null for empty query", () => {
+      const entries = [makeEntry("some cached query", "h1")];
+      assert.equal(bm25Find("", entries, 0.5), null);
+    });
+
+    it("returns null for all-stopword query", () => {
+      const entries = [makeEntry("how to use express", "h1")];
+      // "how to use" are all stopwords → queryTokens is empty after filtering
+      assert.equal(bm25Find("how to for", entries, 0.5), null);
+    });
+
+    it("returns null when no entries provided", () => {
+      assert.equal(bm25Find("some query", [], 0.5), null);
+    });
+  });
+});
+
+// ===========================================================================
+// Cache Timing Tests
+// ===========================================================================
+
+describe("cache timing", () => {
+  describe("cache.set writes file and updates manifest before returning", () => {
+    it("file exists on disk after awaited set()", async () => {
+      // Criterion 6: cache.set completes (file written + manifest updated) before returning
+      const cache = createCache();
+      await cache.init();
+
+      const scope = { libraryId: "/timing/file-test" };
+      const params = { libraryId: "/timing/file-test", query: "file existence check" };
+      const data = { results: [{ id: 1, text: "test data" }] };
+
+      await cache.set("context", scope, params, data);
+
+      // The cache file should exist on disk immediately after set() returns
+      // We verify via cache.get() which reads from disk — if the file wasn't
+      // written, this would return a cache miss.
+      const result = await cache.get("context", scope, params);
+      assert.equal(result.source, "exact", "File should be readable immediately after awaited set");
+      assert.deepEqual(result.data, data);
+    });
+
+    it("manifest entry is visible to subsequent get() after awaited set()", async () => {
+      // This directly tests the fire-and-forget fix: with await, the manifest
+      // is updated before set() returns, so a subsequent BM25 lookup sees it.
+      const cache = createCache();
+      await cache.init();
+
+      const scope = { libraryId: "/timing/manifest-test" };
+      const paramsA = { libraryId: "/timing/manifest-test", query: "best practices for layout and content" };
+      const paramsB = { libraryId: "/timing/manifest-test", query: "best practices for content and layout" };
+      const data = { snippets: [{ text: "cached response" }] };
+
+      // 1. Write entry A
+      await cache.set("context", scope, paramsA, data);
+
+      // 2. Look up with query B (same tokens, different order) — should BM25 hit
+      const result = await cache.get("context", scope, paramsB);
+      assert.equal(result.source, "bm25", "BM25 should find the entry written by awaited set()");
+      assert.deepEqual(result.data, data);
+    });
+
+    it("awaited set() makes entry visible for exact match too", async () => {
+      const cache = createCache();
+      await cache.init();
+
+      const scope = { libraryName: "timing-lib" };
+      const params = { libraryName: "timing-lib", query: "exact match timing" };
+      const data = { results: [{ id: "timing", title: "Timing Test" }] };
+
+      await cache.set("search", scope, params, data);
+
+      const result = await cache.get("search", scope, params);
+      assert.equal(result.source, "exact");
+      assert.deepEqual(result.data, data);
+    });
+  });
+
+  describe("sequential cache writes produce BM25 hits", () => {
+    it("simulates two sequential tool calls: second hits cache from first", async () => {
+      // This simulates the real-world scenario from the spec:
+      // two context7_get_context calls with reordered query terms
+      // in the same LLM response, executed sequentially.
+      const cache = createCache();
+      await cache.init();
+
+      const scope = { libraryId: "/sequential/sim" };
+      const queryA = "best practices for layout and content";
+      const queryB = "best practices for content and layout";
+
+      const paramsA = { libraryId: "/sequential/sim", query: queryA, type: "json" };
+      const paramsB = { libraryId: "/sequential/sim", query: queryB, type: "json" };
+
+      const apiData = { codeSnippets: [{ codeTitle: "Example", code: "console.log(1)" }] };
+
+      // --- First tool call (simulated) ---
+      // Cache miss → fetch from API → await cache.set
+      let result = await cache.get("context", scope, paramsA);
+      assert.equal(result.source, null, "First call should be a cache miss");
+
+      // Simulate the awaited cache.set (as the tool now does)
+      await cache.set("context", scope, paramsA, apiData);
+
+      // --- Second tool call (simulated) ---
+      // With sequential execution + awaited set, the manifest is updated.
+      // queryB has the same tokens as queryA → BM25 hit.
+      result = await cache.get("context", scope, paramsB);
+      assert.equal(result.source, "bm25", "Second call should BM25 hit the first call's cache");
+      assert.deepEqual(result.data, apiData);
+    });
+  });
+});

package/extensions/cache.ts

@@ -24,7 +24,17 @@ import { homedir } from "node:os";
 // Constants
 // ---------------------------------------------------------------------------
 
-const CACHE_ROOT = join(homedir(), ".pi", "agent", "cache", "context7");
+/**
+ * Resolve the cache root directory.
+ *
+ * Reads `CONTEXT7_CACHE_ROOT` at call time (not import time) so that tests
+ * can set the env var before creating a cache instance.
+ */
+function getCacheRoot(): string {
+  return process.env.CONTEXT7_CACHE_ROOT
+    ? join(process.env.CONTEXT7_CACHE_ROOT, "context7")
+    : join(homedir(), ".pi", "agent", "cache", "context7");
+}
 
 /** Subdirectory name for each endpoint. */
 const DIR_NAMES: Record<string, string> = {
@@ -42,10 +52,67 @@ const MAX_CACHE_SIZE = 52_428_800; // 50 MB in bytes
 
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
-const BM25_CONSTANT_IDF = 1.5;
 
-const BM25_THRESHOLD_ONLINE = 0.7;
-const BM25_THRESHOLD_OFFLINE = 0.5;
+/**
+ * Minimum IDF floor to prevent small-corpus artifacts.
+ *
+ * With very few documents (N=1-3), the IDF smoothing formula can produce
+ * artificially low values for shared terms vs unique terms, distorting
+ * the self-match normalization. This floor ensures no term's IDF drops
+ * below a reasonable minimum.
+ */
+const BM25_IDF_MIN = 0.5;
+
+/**
+ * Minimum fraction of query terms that must appear in a document for it
+ * to be considered a valid match (prevents single-shared-term false positives).
+ * Must be strictly greater than this threshold to pass.
+ */
+const BM25_MIN_OVERLAP = 0.5;
+
+/**
+ * Minimum number of matching terms required regardless of overlap ratio.
+ * Prevents false matches when query has very few terms (2-3) and one happens
+ * to match by coincidence (e.g., "useState hook" vs "useEffect hook" sharing "hook").
+ */
+const BM25_MIN_MATCHING_TERMS = 2;
+
+/**
+ * BM25 score thresholds for cache hits.
+ *
+ * Combined with the IDF floor (0.5) and minimum overlap check (50%),
+ * these thresholds ensure meaningful term matches while rejecting
+ * false positives from stopwords alone.
+ *
+ * With IDF floor=0.5 and k1=1.2, each matching term contributes
+ * roughly 0.3-0.7 to the score. A threshold of 0.5 requires at
+ * least one solid term match; 0.3 is more permissive for offline mode.
+ */
+const BM25_THRESHOLD_ONLINE = 0.5;
+const BM25_THRESHOLD_OFFLINE = 0.3;
+
+/**
+ * English stopword set applied before BM25 scoring.
+ *
+ * Contains only structural English words and very generic verbs
+ * ("how", "to", "for", "use", "set", etc.). Domain-specific terms
+ * ("hook", "middleware", "auth", "router", "component", "state") are
+ * intentionally NOT included — they carry the semantic meaning BM25
+ * must discriminate on.
+ */
+const STOPWORDS = new Set([
+  "a", "an", "the", "and", "or", "but", "is", "are", "was", "were",
+  "be", "been", "being", "have", "has", "had", "do", "does", "did",
+  "will", "would", "could", "should", "may", "might", "must", "can",
+  "how", "to", "for", "in", "on", "at", "by", "with", "from", "of",
+  "as", "into", "about", "than", "then", "so", "if", "because",
+  "what", "which", "who", "when", "where", "why", "this", "that",
+  "these", "those", "i", "you", "he", "she", "it", "we", "they",
+  "my", "your", "his", "her", "its", "our", "their",
+  "use", "using", "used", "get", "getting", "set", "setting",
+  "up", "down", "out", "over", "under", "again",
+  "not", "no", "nor", "too", "very", "just", "also", "only",
+]);
 
 // ---------------------------------------------------------------------------
 // Types
@@ -63,7 +130,7 @@ export interface CacheResult {
   entry?: CacheEntry;
 }
 
-interface ManifestEntry {
+export interface ManifestEntry {
   scope: Record<string, string>;
   query: string;
   hash: string;
@@ -154,8 +221,9 @@ function extractQueryText(params: Record<string, string | boolean | undefined>):
  * Tokenize text for BM25 scoring.
  *
  * Lowercases, splits on non-alphanumeric characters, filters empty tokens.
+ * The raw token list is used as the basis for stopword-aware scoring.
  */
-function tokenize(text: string): string[] {
+export function tokenize(text: string): string[] {
   return text
     .toLowerCase()
     .split(/[^a-z0-9]+/)
@@ -163,11 +231,61 @@ function tokenize(text: string): string[] {
 }
 
 /**
- * Compute BM25 score for a single query/document pair.
+ * Tokenize text and remove English stopwords before BM25 scoring.
  *
- * Implements the simplified BM25 formula described in the spec.
+ * Stopwords contribute no discriminating signal — with a proper
+ * corpus-frequency IDF they would score near zero anyway, but filtering
+ * them up front keeps the token lists short and the self-match
+ * normalization meaningful (the self-score reflects only terms that
+ * actually carry semantic weight).
  */
-function bm25Score(queryTokens: string[], docTokens: string[], avgDocLen: number): number {
+export function tokenizeForScoring(text: string): string[] {
+  return tokenize(text).filter((t) => !STOPWORDS.has(t));
+}
+
+/**
+ * Compute the BM25+ smoothed inverse document frequency for a term.
+ *
+ *   IDF = ln(1 + (N - n + 0.5) / (n + 0.5))
+ *
+ * where N = total candidate documents and n = documents whose token list
+ * contains the term. The `+1` smoothing prevents negative IDF values for
+ * terms that appear in every document, which would otherwise subtract
+ * from the score and destabilize the self-match normalization.
+ */
+export function computeIdf(term: string, docTokenLists: string[][]): number {
+  const N = docTokenLists.length;
+  const n = docTokenLists.filter((tokens) => tokens.includes(term)).length;
+  const raw = Math.log(1 + (N - n + 0.5) / (n + 0.5));
+  return Math.max(raw, BM25_IDF_MIN);
+}
+
+/**
+ * Build an IDF map for the (de-duplicated) query terms against a corpus.
+ */
+export function buildIdfMap(queryTokens: string[], docTokenLists: string[][]): Map<string, number> {
+  const idf = new Map<string, number>();
+  for (const term of new Set(queryTokens)) {
+    idf.set(term, computeIdf(term, docTokenLists));
+  }
+  return idf;
+}
+
+/**
+ * Compute the raw (unnormalized) BM25 score for a single query/document pair.
+ *
+ *   score += tf * idf
+ *
+ * where tf = (freq * (k1 + 1)) / (freq + k1 * (1 - b + b * (docLen / avgDocLen)))
+ * and idf is looked up from the precomputed `idfMap`. Terms missing from the
+ * map are treated as having zero IDF.
+ */
+export function bm25Score(
+  queryTokens: string[],
+  docTokens: string[],
+  avgDocLen: number,
+  idfMap: Map<string, number>,
+): number {
   const docLen = docTokens.length;
   const avgLen = avgDocLen > 0 ? avgDocLen : 1;
 
@@ -178,7 +296,7 @@ function bm25Score(queryTokens: string[], docTokens: string[], avgDocLen: number
       const tf =
         (freq * (BM25_K1 + 1)) /
         (freq + BM25_K1 * (1 - BM25_B + BM25_B * (docLen / avgLen)));
-      score += tf * BM25_CONSTANT_IDF;
+      score += tf * (idfMap.get(term) ?? 0);
     }
   }
   return score;
@@ -187,27 +305,52 @@ function bm25Score(queryTokens: string[], docTokens: string[], avgDocLen: number
 /**
  * Run BM25 against a list of manifest entries and return the best match.
  *
+ * Scoring pipeline:
+ * 1. Tokenize the query and each candidate query with stopword filtering.
+ * 2. Filter out documents with insufficient term overlap (< 50% of query terms).
+ * 3. Compute a corpus-frequency IDF for each query term (with floor).
+ * 4. Score every remaining candidate and keep the highest.
+ * 5. Return the best entry only if its raw score meets `threshold`.
+ *
+ * The combination of overlap check + IDF floor + raw score threshold
+ * prevents false positives from stopwords while correctly matching
+ * queries that share meaningful domain terms.
+ *
  * @returns The best matching entry, or null if none reach the threshold.
  */
-function bm25Find(query: string, entries: ManifestEntry[], threshold: number): ManifestEntry | null {
-  const queryTokens = tokenize(query);
+export function bm25Find(query: string, entries: ManifestEntry[], threshold: number): ManifestEntry | null {
+  const queryTokens = tokenizeForScoring(query);
   if (queryTokens.length === 0) return null;
 
-  const docTokenLists = entries.map((e) => tokenize(e.query));
+  const docTokenLists = entries.map((e) => tokenizeForScoring(e.query));
   const avgDocLen =
     docTokenLists.reduce((sum, t) => sum + t.length, 0) / Math.max(entries.length, 1);
 
+  const idfMap = buildIdfMap(queryTokens, docTokenLists);
+
   let bestScore = 0;
   let bestEntry: ManifestEntry | null = null;
 
   for (let i = 0; i < entries.length; i++) {
-    const score = bm25Score(queryTokens, docTokenLists[i], avgDocLen);
+    const docTokens = docTokenLists[i];
+
+    // Check term overlap: must have both sufficient ratio AND minimum count.
+    // This prevents single-shared-term false positives (e.g., "useState hook"
+    // vs "useEffect hook" sharing only "hook").
+    const matchingTerms = queryTokens.filter((t) => docTokens.includes(t)).length;
+    const overlapRatio = matchingTerms / queryTokens.length;
+    if (overlapRatio <= BM25_MIN_OVERLAP || matchingTerms < BM25_MIN_MATCHING_TERMS) continue;
+
+    const score = bm25Score(queryTokens, docTokens, avgDocLen, idfMap);
     if (score > bestScore) {
       bestScore = score;
       bestEntry = entries[i];
     }
   }
 
+  // Edge case: if bestScore is zero, no terms matched.
+  if (bestScore <= 0) return null;
+
   return bestScore >= threshold ? bestEntry : null;
 }
 
@@ -216,15 +359,15 @@ function bm25Find(query: string, entries: ManifestEntry[], threshold: number): M
 // ---------------------------------------------------------------------------
 
 function getEndpointDir(endpoint: "search" | "context"): string {
-  return join(CACHE_ROOT, DIR_NAMES[endpoint]);
+  return join(getCacheRoot(), DIR_NAMES[endpoint]);
 }
 
 function getManifestPath(endpoint: "search" | "context"): string {
-  return join(CACHE_ROOT, `${DIR_NAMES[endpoint]}.json`);
+  return join(getCacheRoot(), `${DIR_NAMES[endpoint]}.json`);
 }
 
 function getManifestTempPath(endpoint: "search" | "context"): string {
-  return join(CACHE_ROOT, `${DIR_NAMES[endpoint]}.json.tmp`);
+  return join(getCacheRoot(), `${DIR_NAMES[endpoint]}.json.tmp`);
 }
 
 function getEntryPath(endpoint: "search" | "context", hash: string): string {
@@ -321,8 +464,8 @@ async function init(): Promise<void> {
   if (initialized) return;
 
   // 1. Ensure directories exist
-  await mkdir(join(CACHE_ROOT, "libraries"), { recursive: true });
-  await mkdir(join(CACHE_ROOT, "contexts"), { recursive: true });
+  await mkdir(join(getCacheRoot(), "libraries"), { recursive: true });
+  await mkdir(join(getCacheRoot(), "contexts"), { recursive: true });
 
   // 2. Load manifests
   for (const endpoint of ["search", "context"] as const) {
@@ -359,11 +502,11 @@ async function init(): Promise<void> {
 
   // Also clean manifest .tmp files from the root cache dir
   try {
-    const rootFiles = await readdir(CACHE_ROOT);
+    const rootFiles = await readdir(getCacheRoot());
     for (const file of rootFiles) {
       if (file.endsWith(".tmp")) {
         try {
-          await unlink(join(CACHE_ROOT, file));
+          await unlink(join(getCacheRoot(), file));
         } catch {
           // ignore
         }

package/extensions/context7.ts

@@ -15,6 +15,10 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createCache, type CacheModule } from "./cache.js";
+import {
+  computeQualityScore,
+  getStars,
+} from "./ranking.js";
 
 export default function (pi: ExtensionAPI) {
   let cache: CacheModule;
@@ -210,6 +214,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "context7_search_library",
     label: "Context7 Search Library",
+    executionMode: "sequential",
     description:
       "Search Context7 for libraries by name. Returns matching libraries with IDs, descriptions, " +
       "trust scores, and available versions. Use this first to resolve a library name to a " +
@@ -273,8 +278,12 @@ export default function (pi: ExtensionAPI) {
             signal,
           );
           results = raw.results ?? [];
-          // Store in cache (fire-and-forget)
-          cache.set("search", { libraryName: params.libraryName }, fetchParams, raw).catch(() => {});
+          // Store in cache (await to guarantee manifest is updated before returning)
+          await cache
+            .set("search", { libraryName: params.libraryName }, fetchParams, raw)
+            .catch((err) => {
+              console.error("[context7] cache write failed:", err);
+            });
           cacheNote = "\n[fetched from API]";
         }
 
@@ -290,37 +299,96 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
-        // Format output
-        const lines: string[] = [
-          `Found ${results.length} libraries for "${params.libraryName}":`,
-        ];
+        // -----------------------------------------------------------------------
+        // Library auto-ranking: filter non-finalized, compute composite quality
+        // score, sort, and show top 3 with a Recommended marker.
+        // Weights and scoring logic live in ranking.ts (imported at module top).
+        // -----------------------------------------------------------------------
+
+        // Step 1 — Filter non-finalized libraries
+        const finalized = results.filter((lib) => {
+          const state = (lib as Record<string, unknown>).state;
+          return state === "finalized" || state === undefined; // keep if finalized or field missing
+        });
+
+        if (finalized.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `Found ${results.length} libraries for "${params.libraryName}" but none are finalized yet. ` +
+                  "Try again later or use a different search term.",
+              },
+            ],
+            details: { results },
+          };
+        }
+
+        // Step 2 — Compute maxStars across the finalized results
+        const maxStars = Math.max(
+          ...finalized.map(
+            (lib) => getStars(lib as Record<string, unknown>),
+          ),
+          0,
+        );
+
+        // Step 3 — Score, sort, and slice top 3
+        const scored = finalized
+          .map((lib) => ({
+            lib,
+            score: computeQualityScore(lib as Record<string, unknown>, maxStars),
+          }))
+          .sort((a, b) => b.score - a.score)
+          .slice(0, 3);
+
+        // Step 4 — Format output
+        const lines: string[] = [];
+
+        if (results.length > 3) {
+          lines.push(
+            `Found ${results.length} libraries for "${params.libraryName}" — showing top ${scored.length} by quality:`,
+          );
+        } else {
+          lines.push(
+            `Found ${results.length} ${results.length === 1 ? "library" : "libraries"} for "${params.libraryName}":`,
+          );
+        }
+        lines.push("");
 
-        for (let i = 0; i < results.length; i++) {
-          const lib = results[i] as Record<string, unknown>;
+        for (let i = 0; i < scored.length; i++) {
+          const lib = scored[i].lib as Record<string, unknown>;
           const idx = i + 1;
-          const id = lib.id ?? "";
-          const title = lib.title ?? lib.name ?? "Unknown";
-          const description = lib.description ?? "";
+          const id = (lib.id ?? "") as string;
+          const title = (lib.title ?? lib.name ?? "Unknown") as string;
+          const description = (lib.description ?? "") as string;
           const versions = Array.isArray(lib.versions)
             ? (lib.versions as string[]).join(", ")
             : "";
           const trust = lib.trustScore ?? lib.trust_score ?? "?";
           const bench = lib.benchmarkScore ?? lib.benchmark_score ?? "?";
-          const stars = lib.stars ?? lib.githubStars ?? lib.github_stars ?? "?";
+          const stars = ((lib.stars ?? lib.githubStars ?? lib.github_stars ?? 0) as number) | 0;
 
-          lines.push("");
-          lines.push(`${idx}. ${title} — ${id}`);
+          const marker = i === 0 ? "⭐ Recommended: " : `${idx}. `;
+          lines.push(`${marker}${title} — ${id}`);
           lines.push(`   ${description}`);
           if (versions) lines.push(`   Versions: ${versions}`);
-          lines.push(`   Trust: ${trust}/10 · Benchmark: ${bench}/100 · ⭐ ${stars}`);
+          lines.push(
+            `   Stars: ${stars.toLocaleString()} · Trust: ${trust}/10 · Benchmark: ${bench}/100`,
+          );
+          if (i === 0) {
+            lines.push(`   → Use this ID with context7_get_context`);
+          }
+          lines.push("");
         }
 
-        lines.push("");
-        lines.push(
-          "Use the library ID (e.g., " +
-            (results[0] as Record<string, unknown>)?.id +
-            ") with context7_get_context.",
-        );
+        // Always suggest the top result's ID
+        const topId = (scored[0]?.lib as Record<string, unknown>)?.id as
+          | string
+          | undefined;
+        if (topId) {
+          lines.push(`Use ${topId} with context7_get_context.`);
+        }
         if (cacheNote) lines.push(cacheNote);
 
         return {
@@ -344,6 +412,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "context7_get_context",
     label: "Context7 Get Context",
+    executionMode: "sequential",
     description:
       "Get up-to-date documentation context and code examples for a library from Context7. " +
       "Requires a libraryId from context7_search_library (format: /owner/repo or /owner/repo@version). " +
@@ -351,7 +420,6 @@ export default function (pi: ExtensionAPI) {
     promptSnippet: "Retrieve documentation and code examples for a Context7 library ID",
     promptGuidelines: [
       "Use context7_get_context for library documentation instead of relying on training data. Training data may be outdated.",
-      "When context7_get_context returns insufficient results, retry with researchMode: true for a deeper search.",
       "Always run context7_search_library first to resolve library names to Context7 IDs before calling context7_get_context.",
     ],
     parameters: Type.Object({
@@ -372,14 +440,6 @@ export default function (pi: ExtensionAPI) {
           default: "json",
         }),
       ),
-      researchMode: Type.Optional(
-        Type.Boolean({
-          description:
-            "When true, use deeper agentic research (sandboxed agents, live web search). " +
-            "Slower but higher quality. Use as retry if default results are insufficient.",
-          default: false,
-        }),
-      ),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
       try {
@@ -405,7 +465,7 @@ export default function (pi: ExtensionAPI) {
           query: params.query,
           type: responseType,
         };
-        if (params.researchMode) fetchParams.researchMode = true;
+
 
         // Try cache
         const cached = await cache.get(
@@ -435,10 +495,12 @@ export default function (pi: ExtensionAPI) {
             currentApiKey,
             signal,
           );
-          // Store in cache (fire-and-forget)
-          cache
+          // Store in cache (await to guarantee manifest is updated before returning)
+          await cache
             .set("context", { libraryId: params.libraryId }, fetchParams, data)
-            .catch(() => {});
+            .catch((err) => {
+              console.error("[context7] cache write failed:", err);
+            });
           cacheNote = "\n[fetched from API]";
         }
 
@@ -520,21 +582,35 @@ export default function (pi: ExtensionAPI) {
             outputLines.push("");
 
             for (const snippet of infoSnippets) {
-              const title = snippet.title ?? "Info";
-              const snippetText =
-                (snippet.content as string) ??
-                (snippet.text as string) ??
-                (snippet.description as string) ??
-                "";
-              outputLines.push(`**${title}** — ${snippetText}`);
+              const breadcrumb = (snippet.breadcrumb as string) ?? "Documentation";
+              const snippetContent = (snippet.content as string) ?? "";
+              const pageId = snippet.pageId as string | undefined;
+
+              outputLines.push(`**${breadcrumb}**`);
+              if (snippetContent) outputLines.push(snippetContent);
+              if (pageId) outputLines.push(`Source: ${pageId}`);
               outputLines.push("");
             }
           }
 
-          // Research mode note
-          if (params.researchMode) {
-            outputLines.push("[Research mode — deeper analysis]");
-            outputLines.push("");
+          // Library rules (global, libraryOwn, libraryTeam)
+          const rules = data?.rules as
+            | Record<string, string[]>
+            | undefined;
+          if (rules) {
+            const allRules: string[] = [];
+            if (Array.isArray(rules.global)) allRules.push(...rules.global);
+            if (Array.isArray(rules.libraryOwn)) allRules.push(...rules.libraryOwn);
+            if (Array.isArray(rules.libraryTeam)) allRules.push(...rules.libraryTeam);
+
+            if (allRules.length > 0) {
+              outputLines.push("### Library Rules");
+              outputLines.push("");
+              for (const rule of allRules) {
+                outputLines.push(`- ${rule}`);
+              }
+              outputLines.push("");
+            }
           }
         }
 

package/extensions/ranking.test.ts

@@ -0,0 +1,394 @@
+/**
+ * Unit tests for library ranking logic (extensions/ranking.ts).
+ *
+ * Verifies:
+ *   - Weight constants sum to exactly 1.0
+ *   - Individual weight values are correct (0.6, 0.25, 0.15)
+ *   - React (220k stars) outranks Preact (36k stars) with the new weights
+ *   - Log normalization works correctly (no NaN, no division by zero)
+ *   - Edge cases: stars=0, single result, all same stars, missing fields
+ *
+ * Run with: npm test
+ *
+ * @module extensions/ranking.test
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  WEIGHT_STARS,
+  WEIGHT_TRUST,
+  WEIGHT_BENCHMARK,
+  computeQualityScore,
+  getStars,
+  getTrust,
+  getBenchmark,
+} from "./ranking.ts";
+
+// ---------------------------------------------------------------------------
+// Helper: score a set of libraries and return them sorted by composite score
+// (descending), mirroring the ranking logic in context7.ts.
+// ---------------------------------------------------------------------------
+
+function rankLibraries(libs: Record<string, unknown>[]): Array<{
+  lib: Record<string, unknown>;
+  score: number;
+}> {
+  const finalized = libs.filter(
+    (lib) => lib.state === "finalized" || lib.state === undefined,
+  );
+
+  const maxStars = Math.max(...finalized.map((lib) => getStars(lib)), 0);
+
+  return finalized
+    .map((lib) => ({ lib, score: computeQualityScore(lib, maxStars) }))
+    .sort((a, b) => b.score - a.score);
+}
+
+// ===========================================================================
+// Weight Constants
+// ===========================================================================
+
+describe("Weight constants", () => {
+  test("WEIGHT_STARS is 0.6", () => {
+    assert.equal(WEIGHT_STARS, 0.6);
+  });
+
+  test("WEIGHT_TRUST is 0.25", () => {
+    assert.equal(WEIGHT_TRUST, 0.25);
+  });
+
+  test("WEIGHT_BENCHMARK is 0.15", () => {
+    assert.equal(WEIGHT_BENCHMARK, 0.15);
+  });
+
+  test("weights sum to exactly 1.0", () => {
+    const sum = WEIGHT_STARS + WEIGHT_TRUST + WEIGHT_BENCHMARK;
+    assert.equal(sum, 1.0);
+  });
+
+  test("no weight is zero or negative", () => {
+    assert.ok(WEIGHT_STARS > 0, "WEIGHT_STARS must be positive");
+    assert.ok(WEIGHT_TRUST > 0, "WEIGHT_TRUST must be positive");
+    assert.ok(WEIGHT_BENCHMARK > 0, "WEIGHT_BENCHMARK must be positive");
+  });
+});
+
+// ===========================================================================
+// React vs Preact — the motivating example from the spec
+// ===========================================================================
+
+describe("React outranks Preact (stars=220000 vs 36000)", () => {
+  const react = {
+    id: "/facebook/react",
+    title: "React",
+    stars: 220000,
+    trustScore: 10,
+    benchmarkScore: 95.5,
+    state: "finalized",
+  };
+  const preact = {
+    id: "/preactjs/preact",
+    title: "Preact",
+    stars: 36000,
+    trustScore: 9,
+    benchmarkScore: 88.0,
+    state: "finalized",
+  };
+
+  test("React composite score is greater than Preact", () => {
+    const ranked = rankLibraries([preact, react]); // preact first to verify sorting
+    assert.equal(ranked[0].lib.id, "/facebook/react");
+    assert.equal(ranked[1].lib.id, "/preactjs/preact");
+    assert.ok(
+      ranked[0].score > ranked[1].score,
+      `React (${ranked[0].score}) should outrank Preact (${ranked[1].score})`,
+    );
+  });
+
+  test("React composite score is close to 1.0 (max)", () => {
+    const maxStars = 220000;
+    const score = computeQualityScore(react, maxStars);
+    // React has the highest stars (starsNorm=1.0), max trust (1.0), high benchmark (0.955)
+    // Expected: 0.6*1 + 0.25*1 + 0.15*0.955 = 0.99325
+    assert.ok(
+      score > 0.99,
+      `React score should be ~0.993, got ${score}`,
+    );
+  });
+
+  test("Preact composite score is meaningfully below React", () => {
+    const maxStars = 220000;
+    const reactScore = computeQualityScore(react, maxStars);
+    const preactScore = computeQualityScore(preact, maxStars);
+    const gap = reactScore - preactScore;
+    // The gap should be at least 0.1 (significant margin)
+    assert.ok(
+      gap > 0.1,
+      `React-Preact gap should be > 0.1, got ${gap}`,
+    );
+  });
+
+  test("ranking works regardless of input order", () => {
+    const order1 = rankLibraries([react, preact]);
+    const order2 = rankLibraries([preact, react]);
+    assert.equal(order1[0].lib.id, order2[0].lib.id);
+  });
+});
+
+// ===========================================================================
+// Log Normalization
+// ===========================================================================
+
+describe("Log normalization", () => {
+  test("library with max stars gets starsNorm = 1.0", () => {
+    const lib = { stars: 100000, trustScore: 0, benchmarkScore: 0 };
+    const score = computeQualityScore(lib, 100000);
+    // starsNorm = log(100001)/log(100001) = 1.0
+    // composite = 0.6 * 1.0 + 0.25 * 0 + 0.15 * 0 = 0.6
+    assert.equal(score, 0.6);
+  });
+
+  test("library with 0 stars gets starsNorm = 0 (no NaN)", () => {
+    const lib = { stars: 0, trustScore: 5, benchmarkScore: 50 };
+    const score = computeQualityScore(lib, 100000);
+    // starsNorm = log(1)/log(100001) = 0/11.51 = 0
+    // composite = 0.6*0 + 0.25*0.5 + 0.15*0.5 = 0.125 + 0.075 = 0.2
+    assert.ok(!Number.isNaN(score), "score must not be NaN");
+    assert.equal(score, 0.2);
+  });
+
+  test("log scale compresses extreme range (1k vs 220k stars)", () => {
+    const maxStars = 220000;
+    const smallLib = { stars: 1000, trustScore: 0, benchmarkScore: 0 };
+    const bigLib = { stars: 220000, trustScore: 0, benchmarkScore: 0 };
+    const smallScore = computeQualityScore(smallLib, maxStars);
+    const bigScore = computeQualityScore(bigLib, maxStars);
+
+    // Small library should still score meaningfully (not near zero)
+    // log(1001)/log(220001) ≈ 6.91/12.30 ≈ 0.562
+    // composite = 0.6 * 0.562 ≈ 0.337
+    assert.ok(
+      smallScore > 0.3,
+      `1k-star lib should score > 0.3 with log norm, got ${smallScore}`,
+    );
+    // Big library gets full stars weight
+    assert.equal(bigScore, 0.6);
+    // But not 220x higher (which linear would give)
+    assert.ok(
+      bigScore / smallScore < 3,
+      "log scale should compress the range significantly",
+    );
+  });
+
+  test("starsNorm increases monotonically with star count", () => {
+    const maxStars = 100000;
+    const starCounts = [0, 10, 100, 1000, 10000, 100000];
+    const scores = starCounts.map((s) =>
+      computeQualityScore({ stars: s, trustScore: 0, benchmarkScore: 0 }, maxStars),
+    );
+    for (let i = 1; i < scores.length; i++) {
+      assert.ok(
+        scores[i] > scores[i - 1],
+        `score should increase from ${starCounts[i - 1]} to ${starCounts[i]} stars`,
+      );
+    }
+  });
+});
+
+// ===========================================================================
+// Edge Cases
+// ===========================================================================
+
+describe("Edge cases", () => {
+  test("stars=0 does not cause NaN or Infinity", () => {
+    const lib = { stars: 0, trustScore: 10, benchmarkScore: 100 };
+    const score = computeQualityScore(lib, 50000);
+    assert.ok(Number.isFinite(score), "score must be finite");
+    // starsNorm = log(1)/log(50001) = 0
+    // composite = 0.6*0 + 0.25*1 + 0.15*1 = 0.4
+    assert.equal(score, 0.4);
+  });
+
+  test("maxStars=0 (all libraries have 0 stars) does not crash", () => {
+    const lib = { stars: 0, trustScore: 10, benchmarkScore: 100 };
+    const score = computeQualityScore(lib, 0);
+    // maxStars=0 → starsNorm=0 (guard clause)
+    // composite = 0.6*0 + 0.25*1 + 0.15*1 = 0.4
+    assert.ok(Number.isFinite(score), "score must be finite");
+    assert.equal(score, 0.4);
+  });
+
+  test("single result is always ranked first (Recommended)", () => {
+    const lib = {
+      id: "/some/lib",
+      title: "SomeLib",
+      stars: 50,
+      trustScore: 3,
+      benchmarkScore: 40,
+      state: "finalized",
+    };
+    const ranked = rankLibraries([lib]);
+    assert.equal(ranked.length, 1);
+    assert.equal(ranked[0].lib.id, "/some/lib");
+    assert.ok(ranked[0].score > 0, "single result should have a positive score");
+  });
+
+  test("all same stars — ranking falls to trust and benchmark", () => {
+    // When all libraries have the same stars, starsNorm = 1.0 for all,
+    // so the composite is determined by trust and benchmark.
+    const libA = {
+      id: "/a",
+      title: "A",
+      stars: 5000,
+      trustScore: 10,
+      benchmarkScore: 90,
+      state: "finalized",
+    };
+    const libB = {
+      id: "/b",
+      title: "B",
+      stars: 5000,
+      trustScore: 5,
+      benchmarkScore: 50,
+      state: "finalized",
+    };
+    const libC = {
+      id: "/c",
+      title: "C",
+      stars: 5000,
+      trustScore: 7,
+      benchmarkScore: 70,
+      state: "finalized",
+    };
+
+    const ranked = rankLibraries([libB, libC, libA]);
+    assert.equal(ranked[0].lib.id, "/a"); // highest trust + benchmark
+    assert.equal(ranked[1].lib.id, "/c");
+    assert.equal(ranked[2].lib.id, "/b"); // lowest trust + benchmark
+  });
+
+  test("missing trustScore and benchmarkScore treated as 0", () => {
+    const lib = { stars: 10000, state: "finalized" }; // no trustScore, no benchmarkScore
+    const score = computeQualityScore(lib, 10000);
+    // starsNorm = 1.0, trustNorm = 0, benchmarkNorm = 0
+    // composite = 0.6 * 1.0 + 0.25 * 0 + 0.15 * 0 = 0.6
+    assert.ok(Number.isFinite(score));
+    assert.equal(score, 0.6);
+  });
+
+  test("missing stars field treated as 0", () => {
+    const lib = { trustScore: 10, benchmarkScore: 100, state: "finalized" };
+    const score = computeQualityScore(lib, 50000);
+    assert.ok(Number.isFinite(score));
+    // stars=0 → starsNorm=0, trustNorm=1, benchmarkNorm=1
+    // composite = 0 + 0.25 + 0.15 = 0.4
+    assert.equal(score, 0.4);
+  });
+
+  test("non-finalized libraries are filtered out during ranking", () => {
+    const finalized = {
+      id: "/finalized",
+      title: "Finalized",
+      stars: 100,
+      trustScore: 5,
+      benchmarkScore: 50,
+      state: "finalized",
+    };
+    const processing = {
+      id: "/processing",
+      title: "Processing",
+      stars: 999999,
+      trustScore: 10,
+      benchmarkScore: 100,
+      state: "processing",
+    };
+    const initial = {
+      id: "/initial",
+      title: "Initial",
+      stars: 888888,
+      trustScore: 10,
+      benchmarkScore: 100,
+      state: "initial",
+    };
+
+    const ranked = rankLibraries([processing, initial, finalized]);
+    assert.equal(ranked.length, 1, "only finalized libraries should remain");
+    assert.equal(ranked[0].lib.id, "/finalized");
+  });
+
+  test("state missing (undefined) is kept (backwards compatible)", () => {
+    const lib = {
+      id: "/no-state",
+      title: "NoState",
+      stars: 1000,
+      trustScore: 7,
+      benchmarkScore: 70,
+      // no state field
+    };
+    const ranked = rankLibraries([lib]);
+    assert.equal(ranked.length, 1);
+  });
+});
+
+// ===========================================================================
+// Field Accessor Helpers
+// ===========================================================================
+
+describe("Field accessors handle alternate field names", () => {
+  test("getStars checks stars, githubStars, github_stars", () => {
+    assert.equal(getStars({ stars: 100 }), 100);
+    assert.equal(getStars({ githubStars: 200 }), 200);
+    assert.equal(getStars({ github_stars: 300 }), 300);
+    assert.equal(getStars({}), 0);
+  });
+
+  test("getTrust checks trustScore, trust_score", () => {
+    assert.equal(getTrust({ trustScore: 8 }), 8);
+    assert.equal(getTrust({ trust_score: 6 }), 6);
+    assert.equal(getTrust({}), 0);
+  });
+
+  test("getBenchmark checks benchmarkScore, benchmark_score", () => {
+    assert.equal(getBenchmark({ benchmarkScore: 75.5 }), 75);
+    assert.equal(getBenchmark({ benchmark_score: 42.7 }), 42);
+    assert.equal(getBenchmark({}), 0);
+  });
+});
+
+// ===========================================================================
+// Score Range Validation
+// ===========================================================================
+
+describe("Score range validation", () => {
+  test("perfect library (max stars, max trust, max benchmark) scores 1.0", () => {
+    const lib = { stars: 100000, trustScore: 10, benchmarkScore: 100 };
+    const score = computeQualityScore(lib, 100000);
+    assert.equal(score, 1.0);
+  });
+
+  test("worst library (0 everything) scores 0.0", () => {
+    const lib = { stars: 0, trustScore: 0, benchmarkScore: 0 };
+    const score = computeQualityScore(lib, 100000);
+    assert.equal(score, 0.0);
+  });
+
+  test("all scores are in [0, 1] range", () => {
+    const maxStars = 50000;
+    const testCases = [
+      { stars: 0, trustScore: 0, benchmarkScore: 0 },
+      { stars: 1, trustScore: 1, benchmarkScore: 1 },
+      { stars: 100, trustScore: 5, benchmarkScore: 50 },
+      { stars: 1000, trustScore: 7, benchmarkScore: 70 },
+      { stars: 50000, trustScore: 10, benchmarkScore: 100 },
+    ];
+    for (const tc of testCases) {
+      const score = computeQualityScore(tc, maxStars);
+      assert.ok(
+        score >= 0 && score <= 1,
+        `score ${score} for ${JSON.stringify(tc)} is out of [0,1]`,
+      );
+    }
+  });
+});

package/extensions/ranking.ts

@@ -0,0 +1,93 @@
+/**
+ * Library ranking logic for Context7 search results.
+ *
+ * Computes a composite quality score for each library using three signals:
+ *   - Stars (log-normalized) — strongest weight, reflects real-world adoption
+ *   - Trust score (linear 0–10) — source reputation
+ *   - Benchmark score (linear 0–100) — documentation quality
+ *
+ * Weights are exported as constants so they can be tested and kept in sync
+ * with SKILL.md documentation.
+ *
+ * @module extensions/ranking
+ */
+
+/**
+ * Weight for the log-normalized stars signal.
+ * Stars are the dominant ranking signal — popular, established libraries
+ * should win by default unless they have notably poor documentation quality.
+ */
+export const WEIGHT_STARS = 0.6;
+
+/**
+ * Weight for the trust score signal (0–10).
+ * Most major libraries score 9–10, so the difference is minimal — trust
+ * acts as a tie-breaker when stars are similar.
+ */
+export const WEIGHT_TRUST = 0.25;
+
+/**
+ * Weight for the benchmark score signal (0–100).
+ * The least stable metric (changes with each documentation refresh) and
+ * the least correlated with what the user actually wants.
+ */
+export const WEIGHT_BENCHMARK = 0.15;
+
+/**
+ * Extract the stars value from a library record, checking multiple
+ * possible field names (camelCase, snake_case, githubStars).
+ */
+export function getStars(lib: Record<string, unknown>): number {
+  return ((lib.stars ?? lib.githubStars ?? lib.github_stars ?? 0) as number) | 0;
+}
+
+/**
+ * Extract the trust score from a library record (0–10).
+ */
+export function getTrust(lib: Record<string, unknown>): number {
+  return ((lib.trustScore ?? lib.trust_score ?? 0) as number) | 0;
+}
+
+/**
+ * Extract the benchmark score from a library record (0–100).
+ */
+export function getBenchmark(lib: Record<string, unknown>): number {
+  return ((lib.benchmarkScore ?? lib.benchmark_score ?? 0) as number) | 0;
+}
+
+/**
+ * Compute the composite quality score for a library.
+ *
+ * Stars are log-normalized: `log(stars + 1) / log(maxStars + 1)`.
+ * This ensures a 1,000-star library scores meaningfully (~0.65) next to a
+ * 220k-star library, rather than near-zero with linear normalization.
+ *
+ * Trust and benchmark are linearly normalized to 0–1.
+ *
+ * @param lib - The library record from the API response.
+ * @param maxStars - The highest star count in the result set (for log normalization).
+ * @returns Composite score in the range [0, 1].
+ */
+export function computeQualityScore(
+  lib: Record<string, unknown>,
+  maxStars: number,
+): number {
+  const stars = getStars(lib);
+  const trust = getTrust(lib);
+  const benchmark = getBenchmark(lib);
+
+  // Log-normalize stars: log(stars + 1) / log(maxStars + 1)
+  // When maxStars is 0, all star contributions are 0 (avoids division by zero / NaN).
+  const starsNorm =
+    maxStars > 0 ? Math.log(stars + 1) / Math.log(maxStars + 1) : 0;
+
+  // Linear normalize trust (0-10) and benchmark (0-100)
+  const trustNorm = trust / 10;
+  const benchmarkNorm = benchmark / 100;
+
+  return (
+    WEIGHT_STARS * starsNorm +
+    WEIGHT_TRUST * trustNorm +
+    WEIGHT_BENCHMARK * benchmarkNorm
+  );
+}

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@mario-gc/pi-context7",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Context7 integration for pi coding agent — fetch up-to-date library documentation and code examples",
   "license": "MIT",
+  "scripts": {
+    "test": "node --test extensions/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "pi-package",
     "context7",

package/skills/context7/SKILL.md

@@ -27,11 +27,17 @@ Call `context7_search_library` with:
 
 ### Step 2: Select the Best Match
 
-From the results, choose based on:
-- Exact or closest name match to what the user asked for
-- Higher benchmark scores (out of 100) indicate better documentation quality
-- Higher trust scores (out of 10) indicate more authoritative sources
-- If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs from the `versions` list
+Results are automatically ranked by a composite quality score:
+- **Stars (60%)** — log-normalized so smaller libraries aren't drowned out
+- **Trust score (25%)** — source reputation (0–10)
+- **Benchmark score (15%)** — documentation quality (0–100)
+
+Only the top 3 results are shown, with the best match marked as ⭐ Recommended.
+Non-finalized libraries (still processing) are filtered out automatically.
+
+**You do not need to manually select a library** — use the Recommended ID
+for `context7_get_context`. If the recommended library doesn't match what
+you need, use one of the other shown results or refine your search.
 
 ### Step 3: Fetch Documentation
 
@@ -40,7 +46,6 @@ Call `context7_get_context` with:
 - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
 - `query`: The user's specific question — be descriptive
 - `type`: Use "json" for structured snippets (default), "txt" for plain text
-- `researchMode`: Only use this as a **retry** if the initial results are insufficient
 
 ### Step 4: Use the Documentation
 
@@ -48,7 +53,7 @@ Incorporate the fetched documentation into your response:
 - Answer the user's question using current, accurate information
 - Include relevant code examples from the docs
 - Cite the library version when relevant
-- Reference the source page/breadcrumb when helpful (from `pageTitle` or `breadcrumb`)
+- Reference the source page/breadcrumb when helpful (from `breadcrumb` or `pageId`)
 
 ## Query Quality
 
@@ -70,8 +75,8 @@ When users mention specific versions:
 ## Retry Strategy
 
 If `context7_get_context` returns insufficient or irrelevant results:
-1. Retry with `researchMode: true` — this uses deeper agentic search
-2. If still insufficient, consider refining the query with more specific terms
+1. Refine your query with more specific terms — include the exact API name, pattern, or feature
+2. Try a different library ID from the search results if multiple were shown
 3. Do not silently fall back to training data without telling the user
 
 ## Guidelines