@gmickel/gno 1.26.0 → 1.27.0

package/src/cli/commands/search.ts

@@ -12,6 +12,7 @@ import type {
 } from "../../core/retrieval-trace-session";
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
+import { normalizeContentTypes } from "../../config";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -28,7 +29,10 @@ import { decorateSearchResultsForIndex, initStore } from "./shared";
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type SearchCommandOptions = Omit<SearchOptions, "projectAffinity"> &
+export type SearchCommandOptions = Omit<
+  SearchOptions,
+  "contentTypeRules" | "projectAffinity"
+> &
   CliProjectAffinityRequest & {
     /** Override config path */
     configPath?: string;
@@ -121,6 +125,7 @@ export async function search(
       ...searchOptions,
       limit,
       projectAffinity,
+      contentTypeRules: normalizeContentTypes(config.contentTypes ?? []).rules,
       traceSession,
     });
 

package/src/cli/commands/status.ts

@@ -5,11 +5,17 @@
  * @module src/cli/commands/status
  */
 
+import type { ContentTypeBoostStatus } from "../../config/content-types";
 import type { ActivationStatus } from "../../core/activation-status";
 import type { IndexStatus } from "../../store/types";
 
 import { getIndexDbPath, getModelsCachePath } from "../../app/constants";
-import { getConfigPaths, isInitialized, loadConfig } from "../../config";
+import {
+  buildContentTypeBoostStatus,
+  getConfigPaths,
+  isInitialized,
+  loadConfig,
+} from "../../config";
 import { isConnectorActivationComplete } from "../../core/activation-connector-health";
 import { buildActivationStatus } from "../../core/activation-status";
 import { ModelCache } from "../../llm/cache";
@@ -36,7 +42,12 @@ export interface StatusOptions {
  * Result of status command.
  */
 export type StatusResult =
-  | { success: true; status: IndexStatus; activation: ActivationStatus }
+  | {
+      success: true;
+      status: IndexStatus;
+      activation: ActivationStatus;
+      contentTypeBoost: ContentTypeBoostStatus;
+    }
   | { success: false; error: string };
 
 function connectorProjectionLine(activation: ActivationStatus): string | null {
@@ -63,7 +74,8 @@ function isStatusHealthy(
  */
 function formatTerminal(
   indexStatus: IndexStatus,
-  activation: ActivationStatus
+  activation: ActivationStatus,
+  contentTypeBoost: ContentTypeBoostStatus
 ): string {
   const lines: string[] = [];
 
@@ -101,6 +113,11 @@ function formatTerminal(
     lines.push(`Last updated: ${indexStatus.lastUpdatedAt}`);
   }
 
+  lines.push(
+    `Content-type boosts: ${contentTypeBoost.rules.length ? contentTypeBoost.rules.map((rule) => `${rule.id}=${rule.searchBoost}`).join(", ") : "none"}`
+  );
+  lines.push(`Ranking fingerprint: ${contentTypeBoost.rulesFingerprint}`);
+
   lines.push(
     `Health: ${isStatusHealthy(indexStatus, activation) ? "OK" : "DEGRADED"}`
   );
@@ -138,7 +155,8 @@ function formatTerminal(
  */
 function formatMarkdown(
   indexStatus: IndexStatus,
-  activation: ActivationStatus
+  activation: ActivationStatus,
+  contentTypeBoost: ContentTypeBoostStatus
 ): string {
   const lines: string[] = [];
 
@@ -174,6 +192,10 @@ function formatMarkdown(
   if (indexStatus.lastUpdatedAt) {
     lines.push(`- **Last updated**: ${indexStatus.lastUpdatedAt}`);
   }
+  lines.push(
+    `- **Content-type boosts**: ${contentTypeBoost.rules.length ? contentTypeBoost.rules.map((rule) => `${rule.id}=${rule.searchBoost}`).join(", ") : "none"}`
+  );
+  lines.push(`- **Ranking fingerprint**: ${contentTypeBoost.rulesFingerprint}`);
 
   lines.push("");
   lines.push("## Lexical activation");
@@ -254,7 +276,12 @@ export async function status(
       }
     );
 
-    return { success: true, status: statusResult.value, activation };
+    return {
+      success: true,
+      status: statusResult.value,
+      activation,
+      contentTypeBoost: buildContentTypeBoostStatus(config.contentTypes ?? []),
+    };
   } finally {
     await store.close();
   }
@@ -294,6 +321,7 @@ export function formatStatus(
         embeddingBacklog: s.embeddingBacklog,
         lastUpdated: s.lastUpdatedAt,
         healthy: isStatusHealthy(s, result.activation),
+        contentTypeBoost: result.contentTypeBoost,
         activation: result.activation,
       },
       null,
@@ -302,8 +330,16 @@ export function formatStatus(
   }
 
   if (options.md) {
-    return formatMarkdown(result.status, result.activation);
+    return formatMarkdown(
+      result.status,
+      result.activation,
+      result.contentTypeBoost
+    );
   }
 
-  return formatTerminal(result.status, result.activation);
+  return formatTerminal(
+    result.status,
+    result.activation,
+    result.contentTypeBoost
+  );
 }

package/src/cli/program.ts

@@ -1151,6 +1151,7 @@ function wireSearchCommands(program: Command): void {
     .option("--context-budget-bytes <num>", "verified Context byte budget")
     .option("--min-score <score>", "minimum retrieval score (0-1)")
     .option("--graph", "include bounded graph expansion")
+    .option("--explain", "include retrieval scoring explanation")
     .option(
       "--project-root <path>",
       "trusted project root (repeatable; replaces cwd affinity)",
@@ -1259,6 +1260,7 @@ function wireSearchCommands(program: Command): void {
         noExpand: depthPolicy.noExpand,
         noRerank: depthPolicy.noRerank,
         candidateLimit: depthPolicy.candidateLimit,
+        explain: Boolean(cmdOpts.explain),
         // Per spec: --answer defaults to false, --no-answer forces retrieval-only
         // Commander creates separate cmdOpts.noAnswer for --no-answer flag
         answer: Boolean(cmdOpts.answer),

package/src/config/content-types.ts

@@ -8,6 +8,7 @@ import type { NotePresetId } from "../core/note-presets";
 import type { Config, ContentTypeConfig } from "./types";
 
 import { NOTE_PRESETS } from "../core/note-presets";
+import { CONTENT_TYPE_SEARCH_BOOST_NEUTRAL } from "./types";
 
 export type ConfigWarningCode =
   | "UNKNOWN_CONTENT_TYPE_PRESET"
@@ -21,6 +22,7 @@ export interface ConfigWarning {
 
 export interface NormalizedContentTypeRule extends ContentTypeConfig {
   preset: NotePresetId;
+  searchBoost: number;
 }
 
 export interface ContentTypeNormalizationResult {
@@ -33,6 +35,14 @@ export interface ConfigNormalizationResult {
   warnings: ConfigWarning[];
 }
 
+export interface ContentTypeBoostStatus {
+  rulesFingerprint: string;
+  rules: Array<{
+    id: string;
+    searchBoost: number;
+  }>;
+}
+
 const NOTE_PRESET_IDS = new Set<NotePresetId>(
   NOTE_PRESETS.map((preset) => preset.id)
 );
@@ -48,6 +58,10 @@ function isNotePresetId(value: string): value is NotePresetId {
   return NOTE_PRESET_IDS.has(value as NotePresetId);
 }
 
+function normalizeSearchBoost(value: number | undefined): number {
+  return value ?? CONTENT_TYPE_SEARCH_BOOST_NEUTRAL;
+}
+
 export function normalizeContentTypes(
   contentTypes: ContentTypeConfig[]
 ): ContentTypeNormalizationResult {
@@ -89,6 +103,7 @@ export function normalizeContentTypes(
         graphHints: contentType.graphHints
           ? contentType.graphHints.map(normalizeGraphHint).filter(Boolean)
           : undefined,
+        searchBoost: normalizeSearchBoost(contentType.searchBoost),
       });
       continue;
     }
@@ -100,6 +115,7 @@ export function normalizeContentTypes(
       graphHints: contentType.graphHints
         ? contentType.graphHints.map(normalizeGraphHint).filter(Boolean)
         : undefined,
+      searchBoost: normalizeSearchBoost(contentType.searchBoost),
     });
   }
 
@@ -112,6 +128,34 @@ export function normalizeContentTypes(
   return { rules, warnings };
 }
 
+export interface ContentTypeRuleResolution {
+  rule: NormalizedContentTypeRule;
+  source: "configured-id" | "prefix";
+}
+
+/**
+ * Resolve one canonical configured rule. A configured frontmatter type wins;
+ * otherwise normalized rule order provides longest-prefix matching. Arbitrary
+ * category text is intentionally not an input and boosts never stack.
+ */
+export function resolveContentTypeRule(
+  configuredId: string | undefined,
+  relativePath: string,
+  rules: NormalizedContentTypeRule[]
+): ContentTypeRuleResolution | undefined {
+  if (configuredId) {
+    const configuredRule = rules.find((rule) => rule.id === configuredId);
+    if (configuredRule) {
+      return { rule: configuredRule, source: "configured-id" };
+    }
+  }
+
+  const prefixRule = rules.find((rule) =>
+    rule.prefixes.some((prefix) => relativePath.startsWith(prefix))
+  );
+  return prefixRule ? { rule: prefixRule, source: "prefix" } : undefined;
+}
+
 export function normalizeConfigContentTypes(
   config: Config
 ): ConfigNormalizationResult {
@@ -127,6 +171,44 @@ export function normalizeConfigContentTypes(
 
 export function fingerprintContentTypeRules(
   rules: NormalizedContentTypeRule[]
+): string {
+  const canonical = rules.map((rule) => {
+    const base = {
+      id: rule.id,
+      preset: rule.preset,
+      prefixes: rule.prefixes,
+      graphHints: rule.graphHints ?? [],
+    };
+    return rule.searchBoost === CONTENT_TYPE_SEARCH_BOOST_NEUTRAL
+      ? base
+      : { ...base, searchBoost: rule.searchBoost };
+  });
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(JSON.stringify(canonical));
+  return hasher.digest("hex");
+}
+
+/**
+ * Redacted live-ranking projection for status surfaces. Prefixes remain local
+ * configuration details; rule IDs and factors are enough to audit behavior.
+ */
+export function buildContentTypeBoostStatus(
+  contentTypes: ContentTypeConfig[]
+): ContentTypeBoostStatus {
+  const { rules } = normalizeContentTypes(contentTypes);
+  return {
+    rulesFingerprint: fingerprintContentTypeRules(rules),
+    rules: rules.map(({ id, searchBoost }) => ({ id, searchBoost })),
+  };
+}
+
+/**
+ * Fingerprint only fields that derive persisted document metadata.
+ * Search boosts are evaluated from live config at query time, so changing one
+ * must not force content conversion or vector rebuilds.
+ */
+export function fingerprintContentTypeMetadataRules(
+  rules: NormalizedContentTypeRule[]
 ): string {
   const canonical = rules.map((rule) => ({
     id: rule.id,

package/src/config/index.ts

@@ -6,13 +6,18 @@
 
 export { createDefaultConfig } from "./defaults";
 export {
+  type ContentTypeRuleResolution,
+  type ContentTypeBoostStatus,
   type ConfigWarning,
+  buildContentTypeBoostStatus,
+  fingerprintContentTypeMetadataRules,
   fingerprintContentTypeRules,
   formatConfigWarning,
   formatConfigWarnings,
   normalizeConfigContentTypes,
   normalizeContentTypes,
   type NormalizedContentTypeRule,
+  resolveContentTypeRule,
   writeConfigWarningsToStderr,
 } from "./content-types";
 // Loading
@@ -47,6 +52,9 @@ export {
 // Types and schemas
 export {
   CONFIG_VERSION,
+  CONTENT_TYPE_SEARCH_BOOST_MAX,
+  CONTENT_TYPE_SEARCH_BOOST_MIN,
+  CONTENT_TYPE_SEARCH_BOOST_NEUTRAL,
   type Collection,
   CollectionSchema,
   type Config,

package/src/config/project-profile.ts

@@ -3,6 +3,8 @@ import { z } from "zod";
 import { NOTE_PRESETS } from "../core/note-presets";
 import { hasLikelySecretPath } from "../core/path-rules";
 import {
+  CONTENT_TYPE_SEARCH_BOOST_MAX,
+  CONTENT_TYPE_SEARCH_BOOST_MIN,
   isValidLanguageHint,
   PROJECT_AFFINITY_MAX_CONTRIBUTION,
 } from "./types";
@@ -284,7 +286,12 @@ export const ProjectProfileContentTypeSchema = z
         }
       })
       .optional(),
-    searchBoost: z.number().finite().optional(),
+    searchBoost: z
+      .number()
+      .finite()
+      .min(CONTENT_TYPE_SEARCH_BOOST_MIN)
+      .max(CONTENT_TYPE_SEARCH_BOOST_MAX)
+      .optional(),
     temporal: z.boolean().optional(),
   })
   .strict();

package/src/config/types.ts

@@ -385,6 +385,10 @@ export const CONTENT_TYPE_GRAPH_HINTS = [
 
 export type ContentTypeGraphHint = (typeof CONTENT_TYPE_GRAPH_HINTS)[number];
 
+export const CONTENT_TYPE_SEARCH_BOOST_MIN = 0.5;
+export const CONTENT_TYPE_SEARCH_BOOST_NEUTRAL = 1;
+export const CONTENT_TYPE_SEARCH_BOOST_MAX = 2;
+
 export const ContentTypeSchema = z.object({
   /** Stable content type identifier */
   id: z.string().min(1),
@@ -394,8 +398,13 @@ export const ContentTypeSchema = z.object({
   preset: z.string().min(1),
   /** Reserved for fn-84 typed graph hints; accepted but no-op in fn-83 */
   graphHints: z.array(z.string().min(1)).optional(),
-  /** Reserved for future ranking; accepted but no-op in fn-83 */
-  searchBoost: z.number().finite().optional(),
+  /** Bounded soft ranking factor; normalized to 1.0 when omitted */
+  searchBoost: z
+    .number()
+    .finite()
+    .min(CONTENT_TYPE_SEARCH_BOOST_MIN)
+    .max(CONTENT_TYPE_SEARCH_BOOST_MAX)
+    .optional(),
   /** Marks time-oriented content types; accepted but no-op in fn-83 */
   temporal: z.boolean().optional(),
 });

package/src/core/context-compiler.ts

@@ -11,6 +11,7 @@ import type {
   HybridSearchOptions,
   QueryModeInput,
   SearchMeta,
+  SearchExplain,
   SearchResult,
   SearchResults,
 } from "../pipeline/types";
@@ -113,6 +114,8 @@ export interface ContextCompilerInput {
   limits: ContextBudgetLimits;
   /** One caller-owned, successfully loaded context snapshot for this plan. */
   contextSnapshot: ContextRow[];
+  /** Internal non-canonical retrieval explanation request. */
+  explain?: boolean;
 }
 
 export interface ContextRetrievalPlan {
@@ -159,6 +162,8 @@ export interface ContextEvidencePlan<
   uriPrefix: string | null;
   retrieval: ContextRetrievalPlan;
   configuredContexts: ContextConfiguredGuidance[];
+  /** Non-canonical scoring sidecar; never included in Capsule projection. */
+  explain?: SearchExplain;
 }
 
 const compareCodeUnits = (left: string, right: string): number => {
@@ -365,6 +370,7 @@ export const planContextEvidence = async <T, P>(
         limit: resultLimit === undefined ? undefined : Math.max(1, resultLimit),
         candidateLimit:
           rerankLimit === undefined ? undefined : Math.max(1, rerankLimit),
+        explain: input.explain,
       })
     );
   }
@@ -393,6 +399,33 @@ export const planContextEvidence = async <T, P>(
     .slice(0, input.limit ?? decoratedResults.length)
     .map(({ result }) => result)
     .sort(compareSearchResults);
+  const explainByResult = new Map<string, SearchExplain["results"][number]>();
+  for (const response of responses) {
+    for (const [index, result] of response.results.entries()) {
+      const detail = response.meta.explain?.results[index];
+      if (detail) explainByResult.set(`${result.docid}\0${result.uri}`, detail);
+    }
+  }
+  const explain = input.explain
+    ? {
+        lines: responses.flatMap(
+          (response) => response.meta.explain?.lines ?? []
+        ),
+        results: results.flatMap((result) => {
+          const detail = explainByResult.get(`${result.docid}\0${result.uri}`);
+          const retrievalRank = plannerMeta(result)?.retrievalRank;
+          return detail
+            ? [
+                {
+                  ...detail,
+                  rank: retrievalRank ?? detail.rank,
+                  score: result.score,
+                },
+              ]
+            : [];
+        }),
+      }
+    : undefined;
   const uriPrefix =
     input.uriPrefix === null || input.uriPrefix === undefined
       ? null
@@ -528,5 +561,9 @@ export const planContextEvidence = async <T, P>(
     projectCanonical: (state) =>
       deps.projectCanonical({ ...baseDraft, selection: state }),
   });
-  return { ...baseDraft, ...selection };
+  return {
+    ...baseDraft,
+    ...selection,
+    ...(explain ? { explain } : {}),
+  };
 };

package/src/core/retrieval-replay-candidate.ts

@@ -12,6 +12,7 @@ import type { RetrievalQrelsCase } from "./retrieval-qrels";
 import type { RetrievalReplayCandidate } from "./retrieval-replay-types";
 
 import { parseUri } from "../app/constants";
+import { normalizeContentTypes } from "../config";
 import { searchHybrid } from "../pipeline/hybrid";
 import { searchBm25 } from "../pipeline/search";
 import { SEARCH_RESULTS_TRACE_METADATA } from "../pipeline/types";
@@ -145,7 +146,11 @@ const runCandidateOnce = async (
   options: HybridSearchOptions
 ): Promise<StoreResult<SearchResults>> => {
   if (candidate.type === "bm25") {
-    return searchBm25(deps.store, source.query.text, options);
+    return searchBm25(deps.store, source.query.text, {
+      ...options,
+      contentTypeRules: normalizeContentTypes(deps.config.contentTypes ?? [])
+        .rules,
+    });
   }
   if (candidate.type === "vector") {
     if (!(deps.vectorIndex && deps.embedPort)) {

package/src/ingestion/sync-options.ts

@@ -7,7 +7,10 @@
 import type { Config, NormalizedContentTypeRule } from "../config";
 import type { SyncOptions } from "./types";
 
-import { fingerprintContentTypeRules, normalizeContentTypes } from "../config";
+import {
+  fingerprintContentTypeMetadataRules,
+  normalizeContentTypes,
+} from "../config";
 
 export function resolveContentTypeRules(
   config?: Pick<Config, "contentTypes">
@@ -24,6 +27,7 @@ export function withContentTypeRules(
     ...options,
     contentTypeRules: rules,
     contentTypeRulesFingerprint:
-      options.contentTypeRulesFingerprint ?? fingerprintContentTypeRules(rules),
+      options.contentTypeRulesFingerprint ??
+      fingerprintContentTypeMetadataRules(rules),
   };
 }

package/src/ingestion/sync.ts

@@ -33,7 +33,10 @@ import type {
   WalkerPort,
 } from "./types";
 
-import { fingerprintContentTypeRules } from "../config";
+import {
+  fingerprintContentTypeMetadataRules,
+  resolveContentTypeRule,
+} from "../config";
 import { getDefaultMimeDetector, type MimeDetector } from "../converters/mime";
 import {
   type ConversionPipeline,
@@ -80,7 +83,8 @@ const MAX_CONCURRENCY = 16;
  * Documents with ingestVersion < INGEST_VERSION will be re-processed.
  */
 export const INGEST_VERSION = 6;
-const EMPTY_CONTENT_TYPE_RULES_FINGERPRINT = fingerprintContentTypeRules([]);
+const EMPTY_CONTENT_TYPE_RULES_FINGERPRINT =
+  fingerprintContentTypeMetadataRules([]);
 const RELATION_EDGE_TYPE_PATTERN = /^[a-z][a-z0-9_]*$/;
 const PROJECTION_YIELD_INTERVAL = 25;
 const NON_RETRYABLE_CONVERSION_ERROR_CODES = new Set([
@@ -401,18 +405,6 @@ function parseCategories(input: unknown): string[] {
   return [];
 }
 
-function matchPrefixContentType(
-  relPath: string,
-  rules: NormalizedContentTypeRule[]
-): string | undefined {
-  for (const rule of rules) {
-    if (rule.prefixes.some((prefix) => relPath.startsWith(prefix))) {
-      return rule.id;
-    }
-  }
-  return undefined;
-}
-
 export function extractDocumentMetadata(
   markdown: string,
   relPath: string,
@@ -421,23 +413,23 @@ export function extractDocumentMetadata(
 ): DocumentMetadata {
   const parsed = parseFrontmatter(markdown);
   const metadata = parsed.metadata;
-  const typedRules = new Map(contentTypeRules.map((rule) => [rule.id, rule]));
   const rawFrontmatterType =
     typeof metadata.type === "string"
       ? normalizeFrontmatterScalar(metadata.type)
       : "";
-  const frontmatterType = typedRules.get(rawFrontmatterType)?.id;
-  const prefixType =
-    frontmatterType === undefined
-      ? matchPrefixContentType(relPath, contentTypeRules)
-      : undefined;
+  const configuredRule = resolveContentTypeRule(
+    rawFrontmatterType,
+    relPath,
+    contentTypeRules
+  );
   const inferred = inferPathContentType(relPath, ext);
-  const contentType = frontmatterType ?? prefixType ?? inferred.contentType;
-  const contentTypeSource: ContentTypeSource = frontmatterType
-    ? "frontmatter-type"
-    : prefixType
-      ? "prefix"
-      : inferred.source;
+  const contentType = configuredRule?.rule.id ?? inferred.contentType;
+  const contentTypeSource: ContentTypeSource =
+    configuredRule?.source === "configured-id"
+      ? "frontmatter-type"
+      : configuredRule?.source === "prefix"
+        ? "prefix"
+        : inferred.source;
   const categories = new Set<string>([contentType]);
 
   const fmCategories = parseCategories(
@@ -679,7 +671,7 @@ export class SyncService {
       const contentTypeRules = options.contentTypeRules ?? [];
       const contentTypeRulesFingerprint =
         options.contentTypeRulesFingerprint ??
-        fingerprintContentTypeRules(contentTypeRules);
+        fingerprintContentTypeMetadataRules(contentTypeRules);
 
       // 4. Check existing doc for skip/repair decision
       const existingResult = await store.getDocument(
@@ -1066,7 +1058,7 @@ export class SyncService {
       contentTypeRules: options.contentTypeRules ?? [],
       contentTypeRulesFingerprint:
         options.contentTypeRulesFingerprint ??
-        fingerprintContentTypeRules(options.contentTypeRules ?? []),
+        fingerprintContentTypeMetadataRules(options.contentTypeRules ?? []),
     };
     const results: FileSyncResult[] = [];
     const projectionSourceIds = new Set<number>();
@@ -1411,7 +1403,7 @@ export class SyncService {
       contentTypeRules: options.contentTypeRules ?? [],
       contentTypeRulesFingerprint:
         options.contentTypeRulesFingerprint ??
-        fingerprintContentTypeRules(options.contentTypeRules ?? []),
+        fingerprintContentTypeMetadataRules(options.contentTypeRules ?? []),
     };
     const errors: Array<{ relPath: string; code: string; message: string }> =
       [];

package/src/ingestion/types.ts

@@ -135,7 +135,7 @@ export interface SyncOptions {
   concurrency?: number;
   /** Normalized content type rules from config.contentTypes. */
   contentTypeRules?: NormalizedContentTypeRule[];
-  /** Stable hash of the normalized content type rules, used for re-derivation. */
+  /** Stable hash of metadata-affecting rules, used for re-derivation. */
   contentTypeRulesFingerprint?: string;
   /** Internal orchestration flag: defer graph projection to an outer sync. */
   projectTypedEdges?: boolean;

package/src/mcp/tools/ask.ts

@@ -50,6 +50,7 @@ export const askInputSchema = z
     graph: z.boolean().optional(),
     noGraph: z.boolean().optional(),
     noRerank: z.boolean().optional(),
+    explain: z.boolean().optional(),
     maxAnswerTokens: z.number().int().positive().optional(),
     contextBudgetTokens: z.number().int().positive().optional(),
     contextBudgetBytes: z.number().int().positive().optional(),

package/src/mcp/tools/index.ts

@@ -562,6 +562,10 @@ export const queryInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Enable bounded one-hop graph neighbor expansion"),
+  explain: z
+    .boolean()
+    .optional()
+    .describe("Include deterministic stage and per-result scoring metadata"),
   tagsAll: z.array(z.string()).optional().describe("Require ALL of these tags"),
   tagsAny: z.array(z.string()).optional().describe("Require ANY of these tags"),
 });

package/src/mcp/tools/query.ts

@@ -22,7 +22,7 @@ import type { ToolContext } from "../server";
 import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
 import {
-  fingerprintContentTypeRules,
+  fingerprintContentTypeMetadataRules,
   normalizeContentTypes,
 } from "../../config";
 import { resolveDepthPolicy } from "../../core/depth-policy";
@@ -71,6 +71,7 @@ interface QueryInput {
   graph?: boolean;
   tagsAll?: string[];
   tagsAny?: string[];
+  explain?: boolean;
 }
 
 interface QueryDiagnoseInput extends QueryInput {
@@ -260,6 +261,7 @@ export function handleQuery(
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,
+        explain: args.explain,
       };
 
       try {
@@ -538,7 +540,7 @@ export function handleQueryDiagnose(
           projectAffinity,
           contentTypeRules,
           contentTypeRulesFingerprint:
-            fingerprintContentTypeRules(contentTypeRules),
+            fingerprintContentTypeMetadataRules(contentTypeRules),
         });
 
         if (!result.ok) {

package/src/mcp/tools/search.ts

@@ -11,6 +11,7 @@ import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import { normalizeContentTypes } from "../../config";
 import { resolveRemoteProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
@@ -133,6 +134,8 @@ export function handleSearch(
         tagsAll: normalizeTagFilters(args.tagsAll),
         tagsAny: normalizeTagFilters(args.tagsAny),
         projectAffinity,
+        contentTypeRules: normalizeContentTypes(ctx.config.contentTypes ?? [])
+          .rules,
       };
       let traceSession: RetrievalTraceSession | undefined;
       try {