oscar64-mcp-docs 1.0.7 → 1.0.9

package/dist/stdio.js

@@ -394,67 +394,30 @@ var toolErrorSchema = z.object({
     })
   ).optional().describe("Optional follow-up tool calls that can recover the workflow.")
 });
-var classificationEvidenceSchema = z.object({
-  label: z.string().describe("Label supported by this evidence item."),
-  facet: z.enum(["primary_track", "domain", "hardware", "technique", "abstraction", "artifact"]).describe("Facet channel that this evidence contributes to."),
-  reason: z.string().describe("Human-readable explanation for why this rule matched."),
-  weight: z.number().describe("Weighted contribution from this evidence match."),
-  matched_on: z.string().describe("Stable rule identifier that produced the evidence."),
-  source_field: z.enum(["title", "rel_path", "text", "files", "asset_refs", "derived"]).describe("Artifact field where the match was detected."),
-  matched_text: z.string().describe("Concrete snippet/text token that matched the rule."),
-  direct: z.boolean().describe("True when this is a direct artifact signal (API include/symbol) instead of a weak heuristic mention.")
-});
-var classificationDetailsSchema = z.object({
-  primary_track: z.string().describe("Selected primary track after evidence gating and fallback handling."),
-  primary_track_status: z.enum(["asserted", "neutral_fallback"]).describe("Whether the primary track is directly asserted or forced to a neutral fallback."),
-  facets: z.object({
-    domain: z.array(z.string()).describe("Functional domains covered by this result."),
-    hardware: z.array(z.string()).describe("Hardware domains referenced by this result."),
-    technique: z.array(z.string()).describe("Implementation techniques shown in this result."),
-    abstraction: z.array(z.string()).describe("Abstraction styles represented in this result."),
-    artifact: z.array(z.string()).describe("Artifact kinds used or produced in this result."),
-    systems: z.array(systemFamilySchema).describe("Detected target systems for this result; empty means shared/common."),
-    scope: z.enum(["tutorial", "sample", "manual"]).describe("Content scope of this result.")
-  }),
-  confidence: z.number().describe("Calibrated numeric confidence for the primary track decision."),
-  confidence_bucket: z.enum(["low", "medium", "high"]).describe("Confidence band intended for policy decisions and quality monitoring."),
-  evidence: z.array(classificationEvidenceSchema).describe("Inspectable evidence records used to derive primary track and facets.")
-});
 var classificationSummarySchema = z.object({
   track: z.string().describe("Primary track summary value for routing and filtering."),
   track_status: z.enum(["asserted", "neutral_fallback"]).describe("Whether the summary track was asserted or neutralized by fallback policy."),
-  confidence_bucket: z.enum(["low", "medium", "high"]).describe("Coarse confidence bucket for this classification summary."),
-  confidence: z.number().describe("Calibrated numeric confidence for summary consumers."),
-  domains: z.array(z.string()).describe("Top-level functional domains admitted after evidence gating."),
-  hardware: z.array(z.string()).describe("Relevant hardware domains admitted by evidence."),
-  techniques: z.array(z.string()).describe("Top techniques surfaced for this result."),
-  systems: z.array(systemFamilySchema).describe("Detected target systems for this result; empty means shared/common."),
-  scope: z.enum(["tutorial", "sample", "manual"]).describe("Content scope of this result.")
+  confidence_bucket: z.enum(["low", "medium", "high"]).describe("Coarse confidence bucket for this classification summary.")
 });
 var searchPreviewSchema = z.object({
   summary: z.string().describe("Compact preview summary for quick relevance checks."),
   signature: z.string().optional().describe("Declaration-like line extracted from content when available."),
-  include_path: z.string().optional().describe("Header include path context when relevant."),
-  declaration_context: z.string().optional().describe("Nearby declaration context that helps disambiguate similar APIs.")
+  include_path: z.string().optional().describe("Header include path context when relevant.")
 });
 var searchHitSchema = z.object({
-  source: z.enum(["manual", "code"]).describe("Where the result came from."),
   result_type: z.enum(["topics", "tutorials", "samples", "headers"]).describe("Artifact type for this result."),
   uri: z.string().describe("URI to pass into `read_uri` for full content."),
   title: z.string().describe("Short title for the matched result."),
   preview: searchPreviewSchema.describe("Structured preview fields for relevance evaluation."),
-  score: z.number().describe("Relative relevance score; higher means better match."),
   referenced_files: z.array(z.string()).optional().describe("Referenced `code://...` URIs that can be read with `read_uri` (for example from #embed or #include)."),
-  classification_summary: classificationSummarySchema.describe("Compact classification metadata always returned."),
-  classification_details: classificationDetailsSchema.optional().describe("Detailed classification, included when `include_details=true`.")
+  classification_summary: classificationSummarySchema.describe("Compact classification metadata always returned.")
 });
 var searchInputSchema = z.object({
   query: z.string().min(1).describe("Query text, symbol, API name, or error phrase to search for."),
   limit: z.number().int().min(1).max(80).default(20).describe("Maximum number of results to return."),
   type: searchTypeSchema.default("all").describe("Filter results by artifact type. Defaults to `all`."),
-  system: systemFilterSchema.default("c64").describe("Target system filter. Defaults to `c64`; use `all` for cross-system search."),
-  include_details: z.boolean().default(false).describe("Set to true to include full classification details and evidence per hit.")
-});
+  system: systemFilterSchema.default("c64").describe("Target system filter. Defaults to `c64`; use `all` for cross-system search.")
+}).strict();
 var searchDataSchema = z.object({
   results: z.array(searchHitSchema).describe("Ranked search hits.")
 });
@@ -580,11 +543,68 @@ var TUTORIAL_BAND_RULES = [
   { min: 5e3, max: 5099, primaryTrack: "bitmap_graphics", domain: "graphics" }
 ];
 var CLASSIFICATION_RULES = [
+  {
+    id: "video_memory_api",
+    appliesTo: ["tutorial", "sample", "manual"],
+    tests: [
+      {
+        pattern: "#include\\s*<(?:c64|c128|vic20|plus4|x16|pet|atari|mega65|nes)/(?:vic|vdc|ted)\\.h>",
+        flags: "i",
+        reason: "includes display memory/control API header",
+        weight: 3,
+        direct: true
+      },
+      {
+        pattern: "\\b(vic_setbank|vic_waitframe|vic_waitline|vdc_[a-z0-9_]+|ted_[a-z0-9_]+|screenmem|d018)\\b",
+        flags: "i",
+        reason: "uses display memory/control API symbols",
+        weight: 2.5,
+        direct: true
+      }
+    ],
+    emits: [
+      { kind: "primary_track", label: "memory_mapping" },
+      { kind: "domain", label: "memory" },
+      { kind: "hardware", label: "vic_ii" },
+      { kind: "technique", label: "bank_switching" }
+    ]
+  },
+  {
+    id: "charwin_api",
+    appliesTo: ["tutorial", "sample", "manual"],
+    tests: [
+      {
+        pattern: "#include\\s*<(?:c64|c128|vic20|plus4|x16|pet|atari|mega65|nes)/charwin\\.h>",
+        flags: "i",
+        reason: "includes character window API header",
+        weight: 3,
+        direct: true
+      },
+      {
+        pattern: "\\bcwin_[a-z0-9_]+\\b",
+        flags: "i",
+        reason: "uses char window API symbols",
+        weight: 2.5,
+        direct: true
+      }
+    ],
+    emits: [
+      { kind: "primary_track", label: "fundamentals" },
+      { kind: "domain", label: "display_textmode" },
+      { kind: "artifact", label: "text_ui" }
+    ]
+  },
   {
     id: "rasterirq_api",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/rasterirq\\.h>", flags: "i", reason: "includes raster IRQ API", weight: 3, direct: true },
+      {
+        pattern: "#include\\s*<(?:c64|c128|vic20|plus4|x16|pet|atari|mega65|nes)/rasterirq\\.h>",
+        flags: "i",
+        reason: "includes raster IRQ API",
+        weight: 3,
+        direct: true
+      },
       { pattern: "\\brirq_[a-z0-9_]+\\b", flags: "i", reason: "uses rirq_* routines", weight: 2, direct: true },
       { pattern: "\\braster\\s*irq\\b|\\birq\\b", flags: "i", reason: "mentions IRQ timing", weight: 1 }
     ],
@@ -1820,30 +1840,10 @@ var readUriTool = createTool2({
 // src/mcp/tools/search.tool.ts
 import { createTool as createTool3 } from "@mastra/core/tools";
 import path9 from "path";
-var INTENT_SYNONYMS = {
-  screenmem: ["screen", "memory", "screen memory"],
-  charset: ["character set", "font", "d018"],
-  d018: ["charset", "screen memory", "vic"],
-  bank: ["banking", "vic_setbank", "memmap", "bank switch"],
-  banking: ["bank", "vic_setbank", "memmap"],
-  rasterirq: ["raster irq", "rirq", "interrupt"],
-  sprite: ["sprites", "spr_", "vic"],
-  sprites: ["sprite", "spr_", "vic"],
-  charwin: ["cwin", "window", "text window"],
-  joystick: ["joy", "input", "cia"],
-  memmap: ["memory map", "banking", "mmap_"],
-  vic: ["vic_ii", "d018", "screen memory"]
-};
 function parseCodeUri(uri) {
-  if (uri.startsWith("code://oscar/")) {
-    return { scope: "oscar", relPath: uri.replace("code://oscar/", "") };
-  }
-  if (uri.startsWith("code://sample/")) {
-    return { scope: "sample", relPath: uri.replace("code://sample/", "") };
-  }
-  if (uri.startsWith("code://tutorial/")) {
-    return { scope: "tutorial", relPath: uri.replace("code://tutorial/", "") };
-  }
+  if (uri.startsWith("code://oscar/")) return { scope: "oscar", relPath: uri.replace("code://oscar/", "") };
+  if (uri.startsWith("code://sample/")) return { scope: "sample", relPath: uri.replace("code://sample/", "") };
+  if (uri.startsWith("code://tutorial/")) return { scope: "tutorial", relPath: uri.replace("code://tutorial/", "") };
   return null;
 }
 async function resolveReferencedUris(state, sourceUri, refs) {
@@ -1894,6 +1894,12 @@ async function resolveReferencedUris(state, sourceUri, refs) {
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function tokenizeQuery(query) {
+  return query.toLowerCase().split(/[^a-z0-9_]+/).map((token) => token.trim()).filter((token) => token.length >= 3);
+}
+function isExactSymbolQuery(query) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(query.trim());
+}
 function looksLikeDeclarationLine(line) {
   const trimmed = line.trim();
   if (!trimmed) return false;
@@ -1913,286 +1919,172 @@ function inferResultType(result) {
   if (uri.startsWith("code://oscar/include/") && uri.toLowerCase().endsWith(".h")) return "headers";
   return "samples";
 }
-function buildPreview(result, query) {
+function extractSignatureFromBody(body, query) {
+  if (!body || !query.trim()) return void 0;
+  const symbol = query.trim().toLowerCase();
+  const exactSymbol = isExactSymbolQuery(query) ? new RegExp(`\\b${escapeRegExp(symbol)}\\b`) : null;
+  const queryTokens = tokenizeQuery(query);
+  const lines = body.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || !looksLikeDeclarationLine(trimmed)) continue;
+    const lower = trimmed.toLowerCase();
+    if (exactSymbol && exactSymbol.test(lower)) return trimmed;
+    if (queryTokens.some((token) => lower.includes(token))) return trimmed;
+  }
+  return void 0;
+}
+function buildPreview(result, query, resultType) {
   const uri = String(result?.uri ?? "");
   const body = String(result?.body ?? "");
   const fallbackSummary = makeExcerpt(String(result?.snippet ?? ""), 700);
   const basePreview = typeof result?.preview === "object" && result.preview ? result.preview : { summary: fallbackSummary };
-  let signature = typeof basePreview.signature === "string" && basePreview.signature.trim().length > 0 ? basePreview.signature.trim() : void 0;
-  let declarationContext = typeof basePreview.declarationContext === "string" && basePreview.declarationContext.trim().length > 0 ? basePreview.declarationContext.trim() : void 0;
-  if (body && query.trim()) {
-    const queryWord = query.trim().toLowerCase();
-    const matcher = new RegExp(`\\b${escapeRegExp(queryWord)}\\b`);
-    const lines = body.split(/\r?\n/);
-    for (let i = 0; i < lines.length; i += 1) {
-      const line = String(lines[i] ?? "");
-      const lower = line.toLowerCase();
-      if (!lower.includes(queryWord)) continue;
-      if (!matcher.test(lower) || !looksLikeDeclarationLine(line)) continue;
-      signature = signature ?? line.trim();
-      const prev = lines.slice(Math.max(0, i - 1), i).find((v) => String(v).trim().length > 0)?.trim();
-      const next = lines.slice(i + 1, i + 3).find((v) => String(v).trim().length > 0)?.trim();
-      declarationContext = declarationContext ?? [prev, line.trim(), next].filter(Boolean).join(" | ");
-      break;
-    }
-  }
+  const signature = (typeof basePreview.signature === "string" && basePreview.signature.trim().length > 0 ? basePreview.signature.trim() : void 0) ?? extractSignatureFromBody(body, query);
   const includePathFromUri = uri.startsWith("code://oscar/include/") ? uri.replace("code://oscar/include/", "") : void 0;
-  const includePath = typeof basePreview.includePath === "string" && basePreview.includePath.trim().length > 0 ? basePreview.includePath.trim() : includePathFromUri;
+  const includePath = resultType === "headers" ? typeof basePreview.includePath === "string" && basePreview.includePath.trim().length > 0 ? basePreview.includePath.trim() : includePathFromUri : void 0;
   const summaryCandidate = typeof basePreview.summary === "string" && basePreview.summary.trim().length > 0 ? basePreview.summary : fallbackSummary;
   return {
     summary: summaryCandidate || makeExcerpt(body || String(result?.title ?? ""), 700),
     ...signature ? { signature } : {},
-    ...includePath ? { include_path: includePath } : {},
-    ...declarationContext ? { declaration_context: declarationContext } : {}
+    ...includePath ? { include_path: includePath } : {}
   };
 }
-function computeSymbolBoost(result, query) {
-  const symbol = query.trim();
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(symbol)) return 0;
-  const symbolLower = symbol.toLowerCase();
-  let boost = 0;
-  const title = String(result?.title ?? "").toLowerCase();
-  const titleBase = title.replace(/\.[a-z0-9]+$/i, "");
-  if (title === symbolLower || titleBase === symbolLower) boost += 90;
-  const body = String(result?.body ?? "");
-  if (body) {
-    const exactWord = new RegExp(`\\b${escapeRegExp(symbolLower)}\\b`);
-    const lines = body.split(/\r?\n/);
-    for (const line of lines) {
-      const lower = line.toLowerCase();
-      if (!lower.includes(symbolLower)) continue;
-      if (exactWord.test(lower)) {
-        boost = Math.max(boost, looksLikeDeclarationLine(line) ? 70 : 28);
-        break;
-      }
-      boost = Math.max(boost, 10);
+function normalizeSearchResults(raw) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const result of raw) {
+    const uri = String(result?.uri ?? "");
+    if (!uri) continue;
+    const prev = seen.get(uri);
+    if (!prev || Number(result?.score ?? 0) > Number(prev?.score ?? 0)) {
+      seen.set(uri, result);
     }
   }
-  const uri = String(result?.uri ?? "");
-  if (boost > 0 && uri.startsWith("code://oscar/include/")) boost += 12;
-  return boost;
-}
-function isExactSymbolQuery(query) {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(query.trim());
+  return [...seen.values()];
 }
-function tokenizeQuery(query) {
-  return query.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+function toClassificationSummary(classification) {
+  const confidence = Number(classification?.confidence ?? 0.25);
+  const confidenceBucket = classification?.confidenceBucket === "high" || classification?.confidenceBucket === "medium" || classification?.confidenceBucket === "low" ? classification.confidenceBucket : confidence >= 0.8 ? "high" : confidence >= 0.55 ? "medium" : "low";
+  const scope = classification?.facets?.scope === "manual" ? "manual" : "code";
+  const neutralTrack = scope === "manual" ? "compiler_language" : "fundamentals";
+  const track = String(classification?.primaryTrack ?? neutralTrack);
+  const status = classification?.primaryTrackStatus === "asserted" || classification?.primaryTrackStatus === "neutral_fallback" ? classification.primaryTrackStatus : confidence >= 0.62 ? "asserted" : "neutral_fallback";
+  return {
+    track,
+    track_status: status,
+    confidence_bucket: confidenceBucket
+  };
 }
-function expandQueryTerms(query) {
-  const tokens = tokenizeQuery(query);
+function extractSystems(classification) {
+  if (!Array.isArray(classification?.facets?.systems)) return [];
   const out = /* @__PURE__ */ new Set();
-  for (const token of tokens) {
-    out.add(token);
-    for (const synonym of INTENT_SYNONYMS[token] ?? []) out.add(synonym.toLowerCase());
+  for (const item of classification.facets.systems) {
+    const normalized = normalizeSystemToken(String(item ?? ""));
+    if (normalized) out.add(normalized);
   }
-  if (tokens.includes("vic") && tokens.includes("bank")) out.add("vic_setbank");
-  if (tokens.includes("screenmem")) out.add("d018");
   return [...out];
 }
-function buildExpandedQuery(query) {
-  const terms = expandQueryTerms(query);
-  if (terms.length === 0) return query;
-  return terms.join(" ");
-}
-function hasApiIntent(query) {
-  const tokens = tokenizeQuery(query);
-  return tokens.some(
-    (token) => ["vic", "d018", "bank", "banking", "charset", "screenmem", "memmap", "charwin", "rasterirq", "sprite"].includes(
-      token
-    )
-  );
-}
-function hasImplementationIntent(query) {
-  const tokens = tokenizeQuery(query);
-  return tokens.some((token) => ["setup", "init", "move", "print", "poll", "wait", "split"].includes(token));
-}
-function isActionableResult(result) {
-  const uri = String(result?.uri ?? "");
-  if (uri.startsWith("code://oscar/include/")) return uri.toLowerCase().endsWith(".h");
-  const signature = String(result?.preview?.signature ?? "");
-  if (signature.trim().length > 0) return true;
-  return uri.startsWith("code://tutorial/") || uri.startsWith("code://sample/");
-}
-function isLowConfidenceResultSet(rawResults, query) {
-  if (rawResults.length === 0) return true;
-  const top = Number(rawResults[0]?.score ?? 0);
-  const second = Number(rawResults[1]?.score ?? 0);
-  if (top < 0.6) return true;
-  if (second > 0 && top / second < 1.12) return true;
-  if (hasApiIntent(query) && !rawResults.slice(0, 3).some((entry) => isActionableResult(entry))) return true;
-  return false;
-}
-function computeIntentBoost(result, query) {
-  const uri = String(result?.uri ?? "");
+function hasQuerySignal(result, query) {
+  const queryTokens = tokenizeQuery(query);
+  if (queryTokens.length === 0) return false;
   const title = String(result?.title ?? "").toLowerCase();
+  const snippet = String(result?.snippet ?? "").toLowerCase();
   const body = String(result?.body ?? "").toLowerCase();
-  let boost = 0;
-  if (hasApiIntent(query) && uri.startsWith("code://oscar/include/")) boost += 14;
-  if (hasImplementationIntent(query) && (uri.startsWith("code://tutorial/") || uri.startsWith("code://sample/"))) {
-    boost += 8;
-  }
-  const expandedTerms = expandQueryTerms(query);
-  for (const term of expandedTerms) {
-    if (term.length < 3) continue;
-    if (title.includes(term)) boost += 1.2;
-    else if (body.includes(term)) boost += 0.5;
-  }
-  if (uri.includes("vic.h") && /\b(vic|d018|screenmem|charset|bank)\b/i.test(query)) boost += 10;
-  if (uri.includes("memmap.h") && /\b(memmap|bank|banking|rom|ram)\b/i.test(query)) boost += 9;
-  if (uri.toLowerCase().includes("screenmem") && /\b(screenmem|screen memory|charset|d018)\b/i.test(query)) boost += 11;
-  return boost;
+  return queryTokens.some((token) => title.includes(token) || snippet.includes(token) || body.includes(token));
 }
-function normalizePrimaryTrackForConfidence(details) {
-  const neutralTrack = details.facets.scope === "manual" ? "compiler_language" : "fundamentals";
-  if (details.confidence >= 0.55) return details;
-  if (details.primary_track === neutralTrack) return details;
-  return {
-    ...details,
-    primary_track: neutralTrack,
-    primary_track_status: "neutral_fallback",
-    confidence_bucket: "low"
-  };
+function hasClearCodingValue(hit) {
+  if (typeof hit.preview.signature === "string" && hit.preview.signature.trim().length > 0) return true;
+  if (hit.resultType === "headers" && typeof hit.preview.include_path === "string" && hit.preview.include_path.length > 0) return true;
+  if ((hit.referencedUris?.length ?? 0) > 0) return true;
+  if ((hit.resultType === "tutorials" || hit.resultType === "samples" || hit.resultType === "topics") && String(hit.preview.summary ?? "").trim().length > 0) {
+    return true;
+  }
+  if (hit.hasQuerySignal && (hit.resultType === "tutorials" || hit.resultType === "samples" || hit.resultType === "topics")) {
+    return true;
+  }
+  return false;
 }
-function normalizeSearchResults(raw) {
-  const seen = /* @__PURE__ */ new Map();
-  for (const result of raw) {
-    const uri = String(result?.uri ?? "");
-    if (!uri) continue;
-    const prev = seen.get(uri);
-    if (!prev || Number(result?.score ?? 0) > Number(prev?.score ?? 0)) {
-      seen.set(uri, result);
-    }
+function computeRankingBoost(hit) {
+  let boost = 0;
+  if (hit.resultType === "headers") boost += 20;
+  if (hit.resultType === "headers" && hit.classificationSummary.track_status === "asserted") boost += 12;
+  if (hit.resultType === "tutorials" || hit.resultType === "samples") boost += 6;
+  if (hit.preview.signature) boost += 16;
+  if ((hit.referencedUris?.length ?? 0) > 0) boost += 8;
+  if (hit.hasQuerySignal) boost += 5;
+  const symbol = hit.query.trim().toLowerCase();
+  if (isExactSymbolQuery(hit.query)) {
+    const signature = String(hit.preview.signature ?? "").toLowerCase();
+    if (signature.includes(symbol)) boost += 42;
+    if (hit.resultType === "headers" && hit.uri.toLowerCase().includes(`${symbol}.h`)) boost += 18;
+  }
+  if (hit.classificationSummary.track === "fundamentals" && hit.classificationSummary.confidence_bucket === "low") {
+    boost -= 8;
   }
-  return [...seen.values()];
+  return boost;
 }
 async function executeSearch(context) {
-  const { query, limit, include_details } = context;
+  const { query, limit } = context;
   const requestedType = context.type ?? "all";
   const system = context.system ?? "c64";
   const state = await getStateSnapshot();
-  const toFallbackClassification = () => ({
-    primary_track: "fundamentals",
-    primary_track_status: "neutral_fallback",
-    facets: {
-      domain: [],
-      hardware: [],
-      technique: [],
-      abstraction: [],
-      artifact: [],
-      systems: [],
-      scope: "sample"
-    },
-    confidence: 0.25,
-    confidence_bucket: "low",
-    evidence: [
-      {
-        label: "fundamentals",
-        facet: "primary_track",
-        reason: "Fallback classification due to missing source metadata",
-        weight: 3,
-        matched_on: "fallback",
-        source_field: "derived",
-        matched_text: "fallback",
-        direct: true
-      }
-    ]
-  });
-  const toDetails = (classification) => {
-    const fallback = toFallbackClassification();
-    const normalizeSystems = (systems) => {
-      if (!Array.isArray(systems)) return [];
-      const out = /* @__PURE__ */ new Set();
-      for (const entry of systems) {
-        const normalized = normalizeSystemToken(String(entry ?? ""));
-        if (normalized) out.add(normalized);
-      }
-      return [...out];
-    };
-    if (!classification || typeof classification !== "object") return fallback;
-    return normalizePrimaryTrackForConfidence({
-      primary_track: String(classification.primaryTrack ?? fallback.primary_track),
-      primary_track_status: classification.primaryTrackStatus === "asserted" || classification.primaryTrackStatus === "neutral_fallback" ? classification.primaryTrackStatus : fallback.primary_track_status,
-      facets: {
-        domain: Array.isArray(classification.facets?.domain) ? classification.facets.domain.map(String) : [],
-        hardware: Array.isArray(classification.facets?.hardware) ? classification.facets.hardware.map(String) : [],
-        technique: Array.isArray(classification.facets?.technique) ? classification.facets.technique.map(String) : [],
-        abstraction: Array.isArray(classification.facets?.abstraction) ? classification.facets.abstraction.map(String) : [],
-        artifact: Array.isArray(classification.facets?.artifact) ? classification.facets.artifact.map(String) : [],
-        systems: normalizeSystems(classification.facets?.systems),
-        scope: classification.facets?.scope === "tutorial" || classification.facets?.scope === "sample" || classification.facets?.scope === "manual" ? classification.facets.scope : fallback.facets.scope
-      },
-      confidence: Number(classification.confidence ?? fallback.confidence),
-      confidence_bucket: classification.confidenceBucket === "low" || classification.confidenceBucket === "medium" || classification.confidenceBucket === "high" ? classification.confidenceBucket : fallback.confidence_bucket,
-      evidence: Array.isArray(classification.evidence) ? classification.evidence.map((item) => ({
-        label: String(item?.label ?? ""),
-        facet: item?.facet === "primary_track" || item?.facet === "domain" || item?.facet === "hardware" || item?.facet === "technique" || item?.facet === "abstraction" || item?.facet === "artifact" ? item.facet : "primary_track",
-        reason: String(item?.reason ?? ""),
-        weight: Number(item?.weight ?? 0),
-        matched_on: String(item?.matchedOn ?? item?.matched_on ?? ""),
-        source_field: item?.sourceField === "title" || item?.sourceField === "rel_path" || item?.sourceField === "text" || item?.sourceField === "files" || item?.sourceField === "asset_refs" || item?.sourceField === "derived" ? item.sourceField : item?.source_field === "title" || item?.source_field === "rel_path" || item?.source_field === "text" || item?.source_field === "files" || item?.source_field === "asset_refs" || item?.source_field === "derived" ? item.source_field : "derived",
-        matched_text: String(item?.matchedText ?? item?.matched_text ?? ""),
-        direct: Boolean(item?.direct)
-      })) : []
-    });
-  };
-  const toSummary = (details) => ({
-    track: details.primary_track,
-    track_status: details.primary_track_status,
-    confidence_bucket: details.confidence_bucket,
-    confidence: details.confidence,
-    domains: details.facets.domain,
-    hardware: details.facets.hardware,
-    techniques: details.facets.technique,
-    systems: details.facets.systems,
-    scope: details.facets.scope
-  });
-  const primaryResults = state.searchIndex.search(query, {
-    combineWith: inferCombineMode(query),
-    prefix: true,
-    fuzzy: 0.12
-  });
-  const symbolQuery = isExactSymbolQuery(query);
-  const expandedQuery = buildExpandedQuery(query);
-  const useFallback = !symbolQuery && (isLowConfidenceResultSet(primaryResults, query) || expandedQuery !== query);
-  const expandedResults = useFallback ? state.searchIndex.search(expandedQuery, {
-    combineWith: "OR",
-    prefix: true,
-    fuzzy: 0.16
-  }) : [];
-  const rawResults = normalizeSearchResults([
-    ...primaryResults,
-    ...expandedResults.map((item) => ({
-      ...item,
-      score: Number(item?.score ?? 0) * 0.82
-    }))
-  ]);
+  const rawResults = normalizeSearchResults(
+    state.searchIndex.search(query, {
+      combineWith: inferCombineMode(query),
+      prefix: true,
+      fuzzy: 0.12
+    })
+  );
+  const fallbackResults = rawResults.length === 0 ? normalizeSearchResults(
+    state.searchIndex.search(query, {
+      combineWith: "OR",
+      prefix: true,
+      fuzzy: 0.16
+    })
+  ) : [];
+  const mergedResults = normalizeSearchResults([...rawResults, ...fallbackResults]);
   const mapped = await Promise.all(
-    rawResults.map(async (result) => {
-      const details = toDetails(result.classification);
-      const referencedUris = await resolveReferencedUris(state, String(result.uri ?? ""), result.referencedFiles);
+    mergedResults.map(async (result) => {
       const resultType = inferResultType(result);
-      const rerankBoost = computeSymbolBoost(result, query) + computeIntentBoost(result, query);
+      const preview = buildPreview(result, query, resultType);
+      const referencedUris = await resolveReferencedUris(state, String(result.uri ?? ""), result.referencedFiles);
+      const classificationSummary = toClassificationSummary(result.classification);
+      const systems = extractSystems(result.classification);
+      const hasSignal = hasQuerySignal(result, query);
+      const baseScore = Number(result?.score ?? 0);
+      const rankScore = baseScore + computeRankingBoost({
+        uri: String(result.uri ?? ""),
+        resultType,
+        preview,
+        query,
+        referencedUris,
+        classificationSummary,
+        hasQuerySignal: hasSignal
+      });
       return {
-        score: (result.score ?? 0) + rerankBoost,
+        rankScore,
+        systems,
+        keep: hasClearCodingValue({
+          resultType,
+          preview,
+          referencedUris,
+          hasQuerySignal: hasSignal
+        }),
         hit: {
-          source: result.source === "manual" ? "manual" : "code",
           result_type: resultType,
           uri: String(result.uri ?? ""),
           title: String(result.title ?? ""),
-          preview: buildPreview(result, query),
-          score: (result.score ?? 0) + rerankBoost,
+          preview,
           ...referencedUris ? { referenced_files: referencedUris } : {},
-          classification_summary: toSummary(details),
-          ...include_details ? { classification_details: details } : {}
+          classification_summary: classificationSummary
         }
       };
     })
   );
-  const hits = mapped.filter((entry) => {
+  const hits = mapped.filter((entry) => entry.keep).filter((entry) => {
     const uri = String(entry.hit.uri ?? "");
     if (uri.startsWith("code://oscar/include/") && !uri.toLowerCase().endsWith(".h")) return false;
     return true;
-  }).filter((entry) => requestedType === "all" || entry.hit.result_type === requestedType).filter((entry) => matchesSystemFilter(entry.hit.classification_summary.systems, system)).sort((a, b) => b.score - a.score || a.hit.uri.localeCompare(b.hit.uri)).slice(0, limit);
+  }).filter((entry) => requestedType === "all" || entry.hit.result_type === requestedType).filter((entry) => matchesSystemFilter(entry.systems, system)).sort((a, b) => b.rankScore - a.rankScore || a.hit.uri.localeCompare(b.hit.uri)).slice(0, limit);
   return {
     ok: true,
     data: {
@@ -2206,7 +2098,19 @@ var searchTool = createTool3({
   inputSchema: searchInputSchema,
   outputSchema: searchOutputSchema,
   execute: async (input) => {
-    const context = input?.context ?? input;
+    const rawInput = input?.context ?? input;
+    if (Object.prototype.hasOwnProperty.call(rawInput, "include_details")) {
+      return {
+        ok: false,
+        error: {
+          code: "INVALID_INPUT",
+          message: "include_details is no longer supported.",
+          hint: "Remove include_details and use classification_summary only.",
+          recoverable: true
+        }
+      };
+    }
+    const context = rawInput;
     try {
       return await executeSearch(context);
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oscar64-mcp-docs",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "private": false,
   "type": "module",
   "engines": {