oscar64-mcp-docs 1.0.1 → 1.0.3

package/dist/stdio.js

@@ -118,6 +118,83 @@ async function listFilesRecursive(root) {
   return out;
 }
 
+// src/mcp/tools/uri.ts
+import path3 from "path";
+function codeUri(scope, relPath) {
+  return `code://${scope}/${relPath.replace(/\\/g, "/")}`;
+}
+function extLower(filePath) {
+  return path3.extname(filePath).toLowerCase();
+}
+function isBinaryExposedPath(filePath) {
+  return BINARY_EXPOSED_EXTS.has(extLower(filePath));
+}
+function guessMimeType(filePath) {
+  switch (extLower(filePath)) {
+    case ".md":
+      return "text/markdown";
+    case ".txt":
+      return "text/plain";
+    case ".c":
+    case ".h":
+    case ".cpp":
+    case ".s":
+    case ".asm":
+    case ".inc":
+      return "text/plain";
+    case ".sid":
+      return "audio/prs.sid";
+    case ".spd":
+    case ".ctm":
+    case ".mcimg":
+    case ".bin":
+      return "application/octet-stream";
+    default:
+      return "application/octet-stream";
+  }
+}
+function uriToAbsPath(state, uri) {
+  if (uri.startsWith("code://oscar/")) {
+    return safeJoin(state.oscar64Root, uri.replace("code://oscar/", ""));
+  }
+  if (uri.startsWith("code://sample/")) {
+    return safeJoin(state.oscar64Root, uri.replace("code://sample/", ""));
+  }
+  if (uri.startsWith("code://tutorial/")) {
+    return safeJoin(state.tutorialsRoot, uri.replace("code://tutorial/", ""));
+  }
+  return null;
+}
+function maybeParseAsFileUri(state, uri) {
+  if (uri.startsWith("code://oscar/")) {
+    const relPath = uri.replace("code://oscar/", "");
+    return {
+      absPath: safeJoin(state.oscar64Root, relPath),
+      relPath
+    };
+  }
+  if (uri.startsWith("code://sample/")) {
+    const relPath = uri.replace("code://sample/", "");
+    return {
+      absPath: safeJoin(state.oscar64Root, relPath),
+      relPath
+    };
+  }
+  if (uri.startsWith("code://tutorial/")) {
+    const relPath = uri.replace("code://tutorial/", "");
+    return {
+      absPath: safeJoin(state.tutorialsRoot, relPath),
+      relPath
+    };
+  }
+  return null;
+}
+function isOscarIncludeHeaderPath(relPath) {
+  const normalized = relPath.replace(/\\/g, "/").toLowerCase();
+  if (!normalized.startsWith("include/")) return true;
+  return normalized.endsWith(".h");
+}
+
 // src/mcp/resources.ts
 function makeResources(getState) {
   const resourceTemplates = async () => [
@@ -130,7 +207,7 @@ function makeResources(getState) {
     {
       uriTemplate: "code://oscar/{path}",
       name: "Oscar64 Code File",
-      description: "A specific text file from oscar64 repository snapshot (headers/core/source).",
+      description: "A specific text file from the oscar64 repository snapshot (headers and other exposed non-include files).",
       mimeType: "text/plain"
     },
     {
@@ -175,6 +252,7 @@ function makeResources(getState) {
     if (uri.startsWith("code://oscar/")) {
       const rel = uri.replace("code://oscar/", "");
       const abs = safeJoin(state.oscar64Root, rel);
+      if (!isOscarIncludeHeaderPath(rel)) throw new Error("Implementation files under include/ are not exposed");
       if (!isExposedPath(rel)) throw new Error("File type is not exposed");
       const text = await safeReadText(abs);
       return {
@@ -210,7 +288,7 @@ function makeResources(getState) {
 
 // src/mcp/tools/list-indexes.tool.ts
 import { createTool } from "@mastra/core/tools";
-import path7 from "path";
+import path8 from "path";
 
 // src/classification/system.ts
 var SYSTEM_FAMILY_VALUES = [
@@ -317,13 +395,18 @@ var toolErrorSchema = z.object({
   ).optional().describe("Optional follow-up tool calls that can recover the workflow.")
 });
 var classificationEvidenceSchema = z.object({
-  label: z.string().describe("Classification label produced by a matched rule."),
-  reason: z.string().describe("Reason text explaining the matched rule."),
-  weight: z.number().describe("Weighted contribution of this evidence item."),
-  matched_on: z.string().describe("Rule identifier that produced this evidence.")
+  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("Primary track for routing or filtering this result."),
+  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."),
@@ -333,14 +416,18 @@ var classificationDetailsSchema = z.object({
     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("Relative confidence for the selected primary track."),
-  evidence: z.array(classificationEvidenceSchema).describe("Evidence items supporting this classification.")
+  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({
-  primary_track: z.string().describe("Primary track for quick filtering."),
-  domain: z.array(z.string()).describe("Top-level functional domains."),
-  hardware: z.array(z.string()).describe("Relevant hardware domains."),
-  technique: z.array(z.string()).describe("Top techniques for this result."),
+  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.")
 });
@@ -429,7 +516,7 @@ var listIndexesOutputSchema = z.union([listIndexesSuccessEnvelopeSchema, errorEn
 
 // src/state.ts
 import fs4 from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 
 // src/indexing/manual.ts
 function parseManualSections(text) {
@@ -462,7 +549,7 @@ function parseManualSections(text) {
 
 // src/indexing/code-collections.ts
 import fs2 from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 
 // src/config/classification-v2.ts
 var PRIMARY_TRACK_PRECEDENCE = [
@@ -497,8 +584,8 @@ var CLASSIFICATION_RULES = [
     id: "rasterirq_api",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/rasterirq\\.h>", flags: "i", reason: "includes raster IRQ API", weight: 3 },
-      { pattern: "\\brirq_[a-z0-9_]+\\b", flags: "i", reason: "uses rirq_* routines", weight: 2 },
+      { pattern: "#include\\s*<c64/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 }
     ],
     emits: [
@@ -512,7 +599,7 @@ var CLASSIFICATION_RULES = [
     id: "sprite_mux",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "\\bvspr_[a-z0-9_]+\\b", flags: "i", reason: "uses virtual sprite multiplexer", weight: 3 },
+      { pattern: "\\bvspr_[a-z0-9_]+\\b", flags: "i", reason: "uses virtual sprite multiplexer", weight: 3, direct: true },
       { pattern: "\\bmultiplex(er|ing)?\\b|sprmux", flags: "i", reason: "mentions sprite multiplexing", weight: 2 }
     ],
     emits: [
@@ -526,7 +613,7 @@ var CLASSIFICATION_RULES = [
     id: "sprites",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/sprites\\.h>", flags: "i", reason: "includes sprite API", weight: 3 },
+      { pattern: "#include\\s*<c64/sprites\\.h>", flags: "i", reason: "includes sprite API", weight: 3, direct: true },
       { pattern: "\\bsprite\\b", flags: "i", reason: "mentions sprites", weight: 1 }
     ],
     emits: [
@@ -555,7 +642,7 @@ var CLASSIFICATION_RULES = [
     id: "audio_sid",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/sid\\.h>", flags: "i", reason: "includes SID API", weight: 3 },
+      { pattern: "#include\\s*<c64/sid\\.h>", flags: "i", reason: "includes SID API", weight: 3, direct: true },
       { pattern: "\\.sid\\b|\\bsid\\b|music|sound|audio", flags: "i", reason: "mentions SID/music", weight: 2 }
     ],
     emits: [
@@ -569,8 +656,8 @@ var CLASSIFICATION_RULES = [
     id: "memory_map",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/memmap\\.h>", flags: "i", reason: "includes memory map API", weight: 3 },
-      { pattern: "\\bmmap_[a-z0-9_]+\\b|#pragma\\s+(region|section|data|code|stacksize)", flags: "i", reason: "uses memory layout controls", weight: 2 },
+      { pattern: "#include\\s*<c64/memmap\\.h>", flags: "i", reason: "includes memory map API", weight: 3, direct: true },
+      { pattern: "\\bmmap_[a-z0-9_]+\\b|#pragma\\s+(region|section|data|code|stacksize)", flags: "i", reason: "uses memory layout controls", weight: 2, direct: true },
       { pattern: "\\b(overlay|inlay|bank|full memory|resource region|easyflash)\\b", flags: "i", reason: "mentions banked/overlay memory", weight: 2 }
     ],
     emits: [
@@ -622,8 +709,8 @@ var CLASSIFICATION_RULES = [
     id: "input_io",
     appliesTo: ["tutorial", "sample", "manual"],
     tests: [
-      { pattern: "#include\\s*<c64/(joystick|keyboard|mouse)\\.h>", flags: "i", reason: "includes input APIs", weight: 2 },
-      { pattern: "#include\\s*<c64/(kernalio|iecbus)\\.h>", flags: "i", reason: "includes storage I/O APIs", weight: 2 }
+      { pattern: "#include\\s*<c64/(joystick|keyboard|mouse)\\.h>", flags: "i", reason: "includes input APIs", weight: 2, direct: true },
+      { pattern: "#include\\s*<c64/(kernalio|iecbus)\\.h>", flags: "i", reason: "includes storage I/O APIs", weight: 2, direct: true }
     ],
     emits: [
       { kind: "domain", label: "io" },
@@ -656,15 +743,27 @@ var CLASSIFICATION_RULES = [
 ];
 
 // src/classification/v2.ts
-function addScore(scores, facet, label, value) {
-  if (!scores.has(facet)) scores.set(facet, /* @__PURE__ */ new Map());
-  const bucket = scores.get(facet);
+var DIRECT_PRIMARY_MIN = 2.8;
+var ASSERTED_CONFIDENCE_MIN = 0.62;
+var DOMAIN_DIRECT_MIN = 1.8;
+function addScore(bucket, label, value) {
   bucket.set(label, (bucket.get(label) ?? 0) + value);
 }
-function sortedFacet(scores, facet) {
-  const bucket = scores.get(facet);
+function addFacetScore(acc, facet, label, value, direct) {
+  if (!acc.has(facet)) {
+    acc.set(facet, {
+      scores: /* @__PURE__ */ new Map(),
+      directScores: /* @__PURE__ */ new Map()
+    });
+  }
+  const facetBucket = acc.get(facet);
+  addScore(facetBucket.scores, label, value);
+  if (direct) addScore(facetBucket.directScores, label, value);
+}
+function sortedFacet(facetScores, facet, minDirect) {
+  const bucket = facetScores.get(facet);
   if (!bucket) return [];
-  return [...bucket.entries()].filter(([, score]) => score > 0).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([label]) => label);
+  return [...bucket.scores.entries()].filter(([label, score]) => score > 0 && (bucket.directScores.get(label) ?? 0) >= minDirect).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([label]) => label);
 }
 function primaryTrackFromScores(trackScores) {
   const ranked = [...trackScores.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
@@ -679,7 +778,6 @@ function primaryTrackFromScores(trackScores) {
 }
 function defaultTrack(scope) {
   if (scope === "manual") return "compiler_language";
-  if (scope === "sample") return "fundamentals";
   return "fundamentals";
 }
 function tutorialBandSeed(tutorialId) {
@@ -689,70 +787,138 @@ function tutorialBandSeed(tutorialId) {
   if (!band) return {};
   return { primaryTrack: band.primaryTrack, domain: band.domain };
 }
+function buildConfidenceBucket(confidence) {
+  if (confidence >= 0.8) return "high";
+  if (confidence >= 0.55) return "medium";
+  return "low";
+}
+function firstMatch(regex, sources) {
+  for (const source of sources) {
+    const match = regex.exec(source.text);
+    if (match) {
+      return {
+        field: source.field,
+        matchedText: String(match[0] ?? "").slice(0, 80)
+      };
+    }
+  }
+  return null;
+}
+function clamp(n, min, max) {
+  return Math.max(min, Math.min(max, n));
+}
+function withNeutralEvidence(evidence, neutralTrack, status) {
+  if (status === "asserted") return evidence;
+  return [
+    {
+      label: neutralTrack,
+      facet: "primary_track",
+      reason: "Fallback to neutral track due to weak or conflicting direct evidence",
+      weight: 3,
+      matchedOn: "neutral_fallback",
+      sourceField: "derived",
+      matchedText: "confidence_guardrail",
+      direct: true
+    },
+    ...evidence
+  ];
+}
 function classifyV2(input) {
-  const haystack = [
-    input.title,
-    input.relPath ?? "",
-    input.text ?? "",
-    ...input.files ?? [],
-    ...input.assetRefs ?? []
-  ].join("\n").toLowerCase();
+  const sources = [
+    { field: "title", text: input.title },
+    { field: "rel_path", text: input.relPath ?? "" },
+    { field: "text", text: input.text ?? "" },
+    { field: "files", text: (input.files ?? []).join("\n") },
+    { field: "asset_refs", text: (input.assetRefs ?? []).join("\n") }
+  ];
   const evidence = [];
   const facetScores = /* @__PURE__ */ new Map();
   const trackScores = /* @__PURE__ */ new Map();
+  const trackDirectScores = /* @__PURE__ */ new Map();
   const seeded = input.scope === "tutorial" ? tutorialBandSeed(input.tutorialId) : {};
-  if (seeded.primaryTrack) trackScores.set(seeded.primaryTrack, (trackScores.get(seeded.primaryTrack) ?? 0) + 2);
-  if (seeded.domain) addScore(facetScores, "domain", seeded.domain, 2);
+  if (seeded.primaryTrack) addScore(trackScores, seeded.primaryTrack, 0.6);
+  if (seeded.domain) addFacetScore(facetScores, "domain", seeded.domain, 0.4, false);
   for (const rule of CLASSIFICATION_RULES) {
     if (!rule.appliesTo.includes(input.scope)) continue;
     for (const test of rule.tests) {
       const regex = new RegExp(test.pattern, test.flags ?? "i");
-      if (!regex.test(haystack)) continue;
+      const matched = firstMatch(regex, sources);
+      if (!matched) continue;
       const testWeight = test.weight ?? 1;
+      const isDirect = test.direct ?? testWeight >= 3;
       for (const emit of rule.emits) {
         const emitWeight = emit.weight ?? 1;
         const weighted = testWeight * emitWeight;
         if (emit.kind === "primary_track") {
-          trackScores.set(emit.label, (trackScores.get(emit.label) ?? 0) + weighted);
+          addScore(trackScores, emit.label, weighted);
+          if (isDirect) addScore(trackDirectScores, emit.label, weighted);
         } else {
-          addScore(facetScores, emit.kind, emit.label, weighted);
+          addFacetScore(facetScores, emit.kind, emit.label, weighted, isDirect);
         }
         evidence.push({
           label: emit.label,
+          facet: emit.kind,
           reason: test.reason,
           weight: weighted,
-          matchedOn: rule.id
+          matchedOn: rule.id,
+          sourceField: matched.field,
+          matchedText: matched.matchedText,
+          direct: isDirect
         });
       }
     }
   }
-  const primaryTrack = primaryTrackFromScores(trackScores) ?? defaultTrack(input.scope);
-  const trackTotal = [...trackScores.values()].reduce((acc, n) => acc + n, 0);
-  const topTrackScore = trackScores.get(primaryTrack) ?? 0;
-  const confidence = trackTotal > 0 ? Number((topTrackScore / trackTotal).toFixed(3)) : 0.25;
+  const neutralTrack = defaultTrack(input.scope);
+  const inferredPrimaryTrack = primaryTrackFromScores(trackScores);
+  let primaryTrack = inferredPrimaryTrack ?? neutralTrack;
+  const rankedTracks = [...trackScores.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const topTrackScore = rankedTracks[0]?.[1] ?? 0;
+  const secondTrackScore = rankedTracks[1]?.[1] ?? 0;
+  const totalTrackScore = rankedTracks.reduce((acc, [, score]) => acc + score, 0);
+  const directPrimaryScore = trackDirectScores.get(primaryTrack) ?? 0;
+  const precision = totalTrackScore > 0 ? topTrackScore / totalTrackScore : 0.2;
+  const margin = topTrackScore > 0 ? (topTrackScore - secondTrackScore) / topTrackScore : 0;
+  const directness = topTrackScore > 0 ? directPrimaryScore / topTrackScore : 0;
+  const conflictPenalty = secondTrackScore > 0 && topTrackScore > 0 ? clamp(secondTrackScore / topTrackScore, 0, 1) * 0.25 : 0;
+  let confidence = clamp(0.2 + precision * 0.4 + margin * 0.22 + directness * 0.28 - conflictPenalty, 0.05, 0.98);
+  let primaryTrackStatus = "asserted";
+  if (primaryTrack !== neutralTrack && (directPrimaryScore < DIRECT_PRIMARY_MIN || confidence < ASSERTED_CONFIDENCE_MIN)) {
+    primaryTrack = neutralTrack;
+    primaryTrackStatus = "neutral_fallback";
+    confidence = Math.min(confidence, 0.42);
+  }
   const systems = inferSystems({
     relPath: input.relPath,
     text: [input.title, input.text ?? "", ...input.files ?? [], ...input.assetRefs ?? []].join("\n"),
     files: input.files
   });
+  const outputEvidence = withNeutralEvidence(
+    evidence.sort((a, b) => b.weight - a.weight || a.label.localeCompare(b.label)).slice(0, 60),
+    neutralTrack,
+    primaryTrackStatus
+  );
+  const confidenceRounded = Number(confidence.toFixed(3));
+  const confidenceBucket = buildConfidenceBucket(confidenceRounded);
   return {
     primaryTrack,
+    primaryTrackStatus,
     facets: {
-      domain: sortedFacet(facetScores, "domain"),
-      hardware: sortedFacet(facetScores, "hardware"),
-      technique: sortedFacet(facetScores, "technique"),
-      abstraction: sortedFacet(facetScores, "abstraction"),
-      artifact: sortedFacet(facetScores, "artifact"),
+      domain: sortedFacet(facetScores, "domain", DOMAIN_DIRECT_MIN),
+      hardware: sortedFacet(facetScores, "hardware", 0.75),
+      technique: sortedFacet(facetScores, "technique", 0),
+      abstraction: sortedFacet(facetScores, "abstraction", 0),
+      artifact: sortedFacet(facetScores, "artifact", 0),
       systems,
       scope: input.scope
     },
-    confidence,
-    evidence: evidence.sort((a, b) => b.weight - a.weight || a.label.localeCompare(b.label)).slice(0, 40)
+    confidence: confidenceRounded,
+    confidenceBucket,
+    evidence: outputEvidence
   };
 }
 
 // src/search/minisearch.ts
-import path3 from "path";
+import path4 from "path";
 import MiniSearch from "minisearch";
 function oscarTokenizer(text) {
   return text.toLowerCase().split(/[^0-9a-zA-Z_\-$]+/).filter(Boolean);
@@ -769,7 +935,7 @@ function oscarProcessTerm(term) {
 function inferCombineMode(query) {
   return query.trim().split(/\s+/).filter(Boolean).length <= 1 ? "OR" : "AND";
 }
-function codeUri(scope, relPath) {
+function codeUri2(scope, relPath) {
   return `code://${scope}/${relPath.replace(/\\/g, "/")}`;
 }
 function extractDeclarationInfo(text) {
@@ -856,7 +1022,7 @@ async function buildSearchIndex(state) {
   const roots = [
     { scope: "tutorial", absRoot: state.tutorialsRoot },
     { scope: "sample", absRoot: state.samplesRoot, uriPrefix: "samples" },
-    { scope: "oscar", absRoot: path3.join(state.oscar64Root, "include"), uriPrefix: "include" }
+    { scope: "oscar", absRoot: path4.join(state.oscar64Root, "include"), uriPrefix: "include" }
   ];
   for (const root of roots) {
     let files = [];
@@ -869,6 +1035,7 @@ async function buildSearchIndex(state) {
       const rel = abs.replace(root.absRoot + "/", "").replace(/\\/g, "/");
       const uriRel = root.uriPrefix ? `${root.uriPrefix}/${rel}` : rel;
       if (!isExposedPath(rel)) continue;
+      if (root.scope === "oscar" && !uriRel.toLowerCase().endsWith(".h")) continue;
       let text;
       try {
         text = await safeReadText(abs);
@@ -882,8 +1049,8 @@ async function buildSearchIndex(state) {
         id: `${root.scope}:${uriRel}`,
         source: "code",
         resultType,
-        uri: root.scope === "sample" && !uriRel.startsWith("samples/") ? codeUri("oscar", uriRel) : codeUri(root.scope === "oscar" ? "oscar" : root.scope, uriRel),
-        title: path3.basename(uriRel),
+        uri: root.scope === "sample" && !uriRel.startsWith("samples/") ? codeUri2("oscar", uriRel) : codeUri2(root.scope === "oscar" ? "oscar" : root.scope, uriRel),
+        title: path4.basename(uriRel),
         preview: {
           summary: makeExcerpt(text, 700),
           ...declarationInfo.signature ? { signature: declarationInfo.signature } : {},
@@ -895,7 +1062,7 @@ ${text}`,
         referencedFiles: extractReferencedFiles(text),
         classification: collectionClassification ?? classifyV2({
           scope: root.scope === "oscar" ? "sample" : root.scope,
-          title: path3.basename(uriRel),
+          title: path4.basename(uriRel),
           relPath: uriRel,
           text
         })
@@ -919,7 +1086,7 @@ async function readFirstLines(filePath, maxLines = 120) {
   return text.split(/\r?\n/).slice(0, maxLines).join("\n");
 }
 function isPrimaryCodeFile(relPath) {
-  const ext = path4.extname(relPath).toLowerCase();
+  const ext = path5.extname(relPath).toLowerCase();
   return ext === ".c" || ext === ".cpp" || ext === ".s" || ext === ".asm";
 }
 function pickPrimaryFiles(files) {
@@ -933,7 +1100,7 @@ function pickPrimaryFiles(files) {
     });
     return mainFirst;
   }
-  const readme = normalized.filter((f) => /^readme(\.[^/]+)?$/i.test(path4.basename(f)));
+  const readme = normalized.filter((f) => /^readme(\.[^/]+)?$/i.test(path5.basename(f)));
   if (readme.length > 0) return readme;
   return normalized;
 }
@@ -950,7 +1117,7 @@ function buildKeywords(input) {
     for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
   }
   for (const rel of input.files) {
-    for (const token of oscarTokenizer(path4.basename(rel, path4.extname(rel)))) {
+    for (const token of oscarTokenizer(path5.basename(rel, path5.extname(rel)))) {
       for (const term of oscarProcessTerm(token)) if (term.length >= 3) keywords.add(term);
     }
   }
@@ -979,21 +1146,21 @@ async function buildCodeCollectionIndex(root, options) {
   const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).filter((name) => !name.startsWith(".") && !exclude.has(name.toLowerCase())).sort((a, b) => a.localeCompare(b, void 0, { numeric: true }));
   const items = [];
   for (const folderName of dirs) {
-    const absDir = path4.join(root, folderName);
+    const absDir = path5.join(root, folderName);
     const filesAbs = await listFilesRecursive(absDir);
-    const files = filesAbs.map((f) => path4.relative(absDir, f)).filter((f) => isExposedPath(f));
+    const files = filesAbs.map((f) => path5.relative(absDir, f)).filter((f) => isExposedPath(f));
     if (files.length === 0) continue;
     const { id, title } = parseCollectionIdentity(options.scope, folderName);
     const primaryFiles = pickPrimaryFiles(files);
     for (const primaryFile of primaryFiles) {
       let previewText = "";
       try {
-        previewText = await readFirstLines(path4.join(absDir, primaryFile));
+        previewText = await readFirstLines(path5.join(absDir, primaryFile));
       } catch {
         previewText = "";
       }
-      const entryTitle = primaryFiles.length > 1 ? `${title} - ${path4.basename(primaryFile, path4.extname(primaryFile))}` : title;
-      const entryId = primaryFiles.length > 1 ? `${id}-${slugify(path4.basename(primaryFile, path4.extname(primaryFile)))}` : id;
+      const entryTitle = primaryFiles.length > 1 ? `${title} - ${path5.basename(primaryFile, path5.extname(primaryFile))}` : title;
+      const entryId = primaryFiles.length > 1 ? `${id}-${slugify(path5.basename(primaryFile, path5.extname(primaryFile)))}` : id;
       const assetRefs = extractAssetRefs(previewText);
       const classification = classifyV2({
         scope: options.scope,
@@ -1040,7 +1207,7 @@ async function buildSamplesIndex(samplesRoot) {
 // src/sync/github-http.ts
 import AdmZip from "adm-zip";
 import fs3 from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 var LOCK_TTL_MS = 30 * 60 * 1e3;
 var LOCK_WAIT_MS = 5 * 60 * 1e3;
 var LOCK_RETRY_MS = 250;
@@ -1086,7 +1253,7 @@ async function unpackZipToDir(zipBuf, targetDir) {
       await fs3.mkdir(abs, { recursive: true });
       continue;
     }
-    await fs3.mkdir(path5.dirname(abs), { recursive: true });
+    await fs3.mkdir(path6.dirname(abs), { recursive: true });
     await fs3.writeFile(abs, entry.getData());
   }
   await fs3.rm(targetDir, { recursive: true, force: true });
@@ -1125,9 +1292,9 @@ async function acquireRepoLock(lockPath) {
 async function syncRepo(cfg, force = false) {
   await fs3.mkdir(META_DIR, { recursive: true });
   await fs3.mkdir(SOURCES_DIR, { recursive: true });
-  const metaPath = path5.join(META_DIR, `${cfg.key}.json`);
-  const lockPath = path5.join(META_DIR, `${cfg.key}.lock`);
-  const sourceRoot = path5.join(SOURCES_DIR, cfg.key, "current");
+  const metaPath = path6.join(META_DIR, `${cfg.key}.json`);
+  const lockPath = path6.join(META_DIR, `${cfg.key}.lock`);
+  const sourceRoot = path6.join(SOURCES_DIR, cfg.key, "current");
   const existingBeforeLock = await readJson(metaPath);
   const now = Date.now();
   const stale = !existingBeforeLock?.lastCheckedAt || now - existingBeforeLock.lastCheckedAt > UPDATE_TTL_MS;
@@ -1251,8 +1418,8 @@ async function initState(forceRefresh = false) {
   const repos = await syncAllRepos(forceRefresh);
   const oscar64Root = repos.oscar64.rootDir;
   const tutorialsRoot = repos.OscarTutorials.rootDir;
-  const samplesRoot = path6.join(oscar64Root, "samples");
-  const manualPath = path6.join(oscar64Root, "oscar64.md");
+  const samplesRoot = path7.join(oscar64Root, "samples");
+  const manualPath = path7.join(oscar64Root, "oscar64.md");
   const manualText = await safeReadText(manualPath);
   const { lines: manualLines, sections: manualSections } = parseManualSections(manualText);
   const tutorials = await buildTutorialsIndex(tutorialsRoot);
@@ -1334,13 +1501,13 @@ ${body}`
     }
   }
   if (type === "all" || type === "headers") {
-    const includeRoot = path7.join(state.oscar64Root, "include");
+    const includeRoot = path8.join(state.oscar64Root, "include");
     try {
       const files = await listFilesRecursive(includeRoot);
       for (const abs of files) {
-        const relFromOscar = path7.relative(state.oscar64Root, abs).replace(/\\/g, "/");
+        const relFromOscar = path8.relative(state.oscar64Root, abs).replace(/\\/g, "/");
         if (!relFromOscar.toLowerCase().endsWith(".h")) continue;
-        const relFromInclude = path7.relative(includeRoot, abs).replace(/\\/g, "/");
+        const relFromInclude = path8.relative(includeRoot, abs).replace(/\\/g, "/");
         const systems = inferSystems({ relPath: relFromOscar });
         if (!matchesSystemFilter(systems, system)) continue;
         items.push({
@@ -1385,80 +1552,6 @@ var listIndexesTool = createTool({
 // src/mcp/tools/read-uri.tool.ts
 import fs5 from "fs/promises";
 import { createTool as createTool2 } from "@mastra/core/tools";
-
-// src/mcp/tools/uri.ts
-import path8 from "path";
-function codeUri2(scope, relPath) {
-  return `code://${scope}/${relPath.replace(/\\/g, "/")}`;
-}
-function extLower(filePath) {
-  return path8.extname(filePath).toLowerCase();
-}
-function isBinaryExposedPath(filePath) {
-  return BINARY_EXPOSED_EXTS.has(extLower(filePath));
-}
-function guessMimeType(filePath) {
-  switch (extLower(filePath)) {
-    case ".md":
-      return "text/markdown";
-    case ".txt":
-      return "text/plain";
-    case ".c":
-    case ".h":
-    case ".cpp":
-    case ".s":
-    case ".asm":
-    case ".inc":
-      return "text/plain";
-    case ".sid":
-      return "audio/prs.sid";
-    case ".spd":
-    case ".ctm":
-    case ".mcimg":
-    case ".bin":
-      return "application/octet-stream";
-    default:
-      return "application/octet-stream";
-  }
-}
-function uriToAbsPath(state, uri) {
-  if (uri.startsWith("code://oscar/")) {
-    return safeJoin(state.oscar64Root, uri.replace("code://oscar/", ""));
-  }
-  if (uri.startsWith("code://sample/")) {
-    return safeJoin(state.oscar64Root, uri.replace("code://sample/", ""));
-  }
-  if (uri.startsWith("code://tutorial/")) {
-    return safeJoin(state.tutorialsRoot, uri.replace("code://tutorial/", ""));
-  }
-  return null;
-}
-function maybeParseAsFileUri(state, uri) {
-  if (uri.startsWith("code://oscar/")) {
-    const relPath = uri.replace("code://oscar/", "");
-    return {
-      absPath: safeJoin(state.oscar64Root, relPath),
-      relPath
-    };
-  }
-  if (uri.startsWith("code://sample/")) {
-    const relPath = uri.replace("code://sample/", "");
-    return {
-      absPath: safeJoin(state.oscar64Root, relPath),
-      relPath
-    };
-  }
-  if (uri.startsWith("code://tutorial/")) {
-    const relPath = uri.replace("code://tutorial/", "");
-    return {
-      absPath: safeJoin(state.tutorialsRoot, relPath),
-      relPath
-    };
-  }
-  return null;
-}
-
-// src/mcp/tools/read-uri.tool.ts
 async function readResourceUriFromState(uri) {
   const state = await getStateSnapshot();
   const resources = makeResources(() => state);
@@ -1505,6 +1598,17 @@ async function executeReadUri(context) {
     }
   }
   const rel = fileTarget.relPath;
+  if (uri.startsWith("code://oscar/") && !isOscarIncludeHeaderPath(rel)) {
+    return {
+      ok: false,
+      error: {
+        code: "UNSUPPORTED_SCOPE",
+        message: "Implementation files under include/ are not exposed.",
+        hint: "Use the corresponding header file (for example .h) or tutorial/sample source instead.",
+        recoverable: true
+      }
+    };
+  }
   const allowText = isExposedPath(rel);
   const allowBinary = isBinaryExposedPath(rel);
   if (!allowText && !allowBinary) {
@@ -1597,6 +1701,20 @@ 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/", "") };
@@ -1630,7 +1748,7 @@ async function resolveReferencedUris(state, sourceUri, refs) {
     const addCandidate = (scope, rel) => {
       const clean = rel.replace(/^\/+/, "");
       if (!clean) return;
-      candidates.push(codeUri2(scope, clean));
+      candidates.push(codeUri(scope, clean));
     };
     if (ref.startsWith("./") || ref.startsWith("../")) {
       addCandidate(parsed.scope, path9.posix.normalize(path9.posix.join(currentDir, ref)));
@@ -1735,6 +1853,99 @@ function computeSymbolBoost(result, query) {
   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());
+}
+function tokenizeQuery(query) {
+  return query.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+}
+function expandQueryTerms(query) {
+  const tokens = tokenizeQuery(query);
+  const out = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    out.add(token);
+    for (const synonym of INTENT_SYNONYMS[token] ?? []) out.add(synonym.toLowerCase());
+  }
+  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 ?? "");
+  const title = String(result?.title ?? "").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;
+}
+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 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);
+    }
+  }
+  return [...seen.values()];
+}
 async function executeSearch(context) {
   const { query, limit, include_details } = context;
   const requestedType = context.type ?? "all";
@@ -1742,6 +1953,7 @@ async function executeSearch(context) {
   const state = await getStateSnapshot();
   const toFallbackClassification = () => ({
     primary_track: "fundamentals",
+    primary_track_status: "neutral_fallback",
     facets: {
       domain: [],
       hardware: [],
@@ -1752,7 +1964,19 @@ async function executeSearch(context) {
       scope: "sample"
     },
     confidence: 0.25,
-    evidence: []
+    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();
@@ -1766,8 +1990,9 @@ async function executeSearch(context) {
       return [...out];
     };
     if (!classification || typeof classification !== "object") return fallback;
-    return {
+    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) : [],
@@ -1778,33 +2003,56 @@ async function executeSearch(context) {
         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 ?? "")
+        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) => ({
-    primary_track: details.primary_track,
-    domain: details.facets.domain,
+    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,
-    technique: details.facets.technique,
+    techniques: details.facets.technique,
     systems: details.facets.systems,
     scope: details.facets.scope
   });
-  const rawResults = state.searchIndex.search(query, {
+  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 mapped = await Promise.all(
     rawResults.map(async (result) => {
       const details = toDetails(result.classification);
       const referencedUris = await resolveReferencedUris(state, String(result.uri ?? ""), result.referencedFiles);
       const resultType = inferResultType(result);
-      const rerankBoost = computeSymbolBoost(result, query);
+      const rerankBoost = computeSymbolBoost(result, query) + computeIntentBoost(result, query);
       return {
         score: (result.score ?? 0) + rerankBoost,
         hit: {
@@ -1821,7 +2069,11 @@ async function executeSearch(context) {
       };
     })
   );
-  const hits = mapped.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);
+  const hits = mapped.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);
   return {
     ok: true,
     data: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oscar64-mcp-docs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "type": "module",
   "files": [
@@ -26,15 +26,15 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@mastra/core": "^0.10.7",
-    "@mastra/mcp": "^0.10.7",
+    "@mastra/core": "^1.9.0",
+    "@mastra/mcp": "^1.0.3",
     "adm-zip": "^0.5.16",
     "minisearch": "^7.1.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.5",
-    "mastra": "^0.10.7",
+    "mastra": "^1.3.6",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.6.3",