@gmickel/gno 1.26.0 → 1.27.0

package/README.md

@@ -149,7 +149,8 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
   remote fetch, store listing, or Firefox parity is claimed.
 - **Schema-lite content types**: optional `contentTypes` rules map configured
   frontmatter `type` values or path prefixes to canonical `contentType` metadata
-  in JSON search/query results
+  in JSON search/query results and can apply one bounded, explainable
+  `searchBoost` without bypassing hard filters
 - **Publish to [gno.sh](https://gno.sh/publish)**: new `gno publish export` CLI and Web UI action produce a self-contained artifact you upload to the hosted reader — public, secret, invite-only, or locally encrypted before upload
 - **Retrieval Quality Upgrade**: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
 - **Code Embedding Benchmarks**: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models

package/assets/skill/SKILL.md

@@ -122,6 +122,7 @@ Recipe rules:
 --line-numbers        Include line numbers
 --project-root <path> Trusted local root; repeatable and replaces cwd affinity
 --no-project-affinity Disable trusted local project-aware ranking
+--explain            Include retrieval scoring details
 ```
 
 CLI searches use explicit `--project-root`, the nearest valid compiled project
@@ -137,6 +138,13 @@ cannot change another repository's fallback. Explain/diagnose identify this
 trusted source as `project_profile`; contexts, content types, source metadata,
 and document fields never become project identity.
 
+Configured `contentTypes[].searchBoost` is a separate local ranking signal.
+`1` is neutral; `0.5..2` maps to a bounded `-0.05..+0.05` contribution, and
+all auxiliary signals share `±0.08`. It cannot create candidates or bypass hard
+filters. Use `gno query --explain`, `gno ask --explain`, or
+`gno query diagnose` when the ranking effect matters; normal output omits the
+boost receipt.
+
 Do not treat MCP/SDK/REST `projectHints` as paths. They are opaque, untrusted,
 limited to 16, never trigger filesystem probing, and currently produce zero
 affinity. Explain uses redacted aliases only. Diagnose preserves exact closed

package/browser-extension/artifacts/gno-browser-clipper-v1.27.0.zip.sha256

@@ -0,0 +1 @@
+3da63d624c5d61f121c5082cd5db2b233e95be5c72beba14f4a3e73a14384e02  gno-browser-clipper-v1.27.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.26.0"
+  "version": "1.27.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -436,7 +436,14 @@ Zod validates `id`, `prefixes`, `preset`, `graphHints`, `searchBoost`, and
 `temporal`, while `preset` remains a permissive string. Post-parse normalization
 warns and drops unknown preset references, dedupes exact duplicate prefixes,
 retains overlapping prefixes, and sorts rules longest-prefix-first. `searchBoost`
-is accepted but currently no-op. `graphHints` is active: ordered hints type
+defaults to neutral `1`, accepts `0.5..2`, and maps one canonical configured
+type to a bounded `-0.05..+0.05` ranking contribution. A frontmatter type ID
+wins over longest-prefix matching; boosts never stack, cannot create
+candidates, never widen retrieval or defer `minScore`, and share the final
+`±0.08` auxiliary cap with project affinity. Hybrid applies the composed score
+to normalized fusion before rerank blending; rerank order and lexical top-hit
+protection remain authoritative.
+`graphHints` is active: ordered hints type
 projected wiki/markdown edges and surface in graph traversal/diagnose metadata.
 
 ---
@@ -1203,7 +1210,7 @@ Human-friendly query with citations-first output and optional grounded answer.
 **Synopsis:**
 
 ```bash
-gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer|--verify] [--no-answer] [--max-answer-tokens <n>] [--context-budget-tokens <n>] [--context-budget-bytes <n>] [--min-score <score>] [--graph] [--no-expand] [--no-rerank] [--show-sources] [--json|--md]
+gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer|--verify] [--no-answer] [--max-answer-tokens <n>] [--context-budget-tokens <n>] [--context-budget-bytes <n>] [--min-score <score>] [--graph] [--no-expand] [--no-rerank] [--explain] [--show-sources] [--json|--md]
 ```
 
 **Options:**
@@ -1228,6 +1235,7 @@ gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [
 | `-C, --candidate-limit`   | integer  | 20      | Max candidates passed to reranking                                                 |
 | `--no-expand`             | boolean  | false   | Disable query expansion                                                            |
 | `--no-rerank`             | boolean  | false   | Disable cross-encoder reranking                                                    |
+| `--explain`               | boolean  | false   | Include retrieval scoring details; prints to stderr outside structured output      |
 | `--show-sources`          | boolean  | false   | Show all retrieved sources (not just cited)                                        |
 | `--project-root`          | string[] | cwd     | Trusted project root; repeatable, replaces default cwd/repository affinity         |
 | `--no-project-affinity`   | boolean  | false   | Disable project-aware soft ranking; invalid with `--project-root`                  |
@@ -1238,6 +1246,11 @@ See [Output Schemas](./output-schemas/ask.schema.json)
 Notes:
 
 - `meta.answerContext` is optional explain payload for answer source selection.
+- `meta.explain` is present only with `--explain`. Its optional
+  `contentTypeBoost` result component contains the raw/base score, configured
+  factor, capped and combined contributions, final score, rule source, and full
+  ranking-rules fingerprint. Verified Ask attaches this as a non-canonical
+  sidecar; Capsule identity and bytes do not change.
 - `--verify` implies answer generation and cannot be combined with
   `--no-answer`. The JSON result adds the closed Capsule, freshness receipt,
   four-state per-claim verdicts (`supported`, `contradicted`, `insufficient`,

package/spec/evals-agentic.md

@@ -26,6 +26,7 @@ evals/agentic/
   project-affinity-outcome.ts
   project-affinity-promotion.ts
   project-affinity-runtime.ts
+  content-type-boost-promotion.ts
   verified-ask-outcome.ts
   verified-ask-promotion.ts
   demos/context-capsule.ts
@@ -103,6 +104,22 @@ receipts, and compares the committed artifact with a fresh deterministic
 production run. The controlled synthetic lane isolates the score seam and makes
 no general workload superiority claim.
 
+## Separate content-type boost promotion
+
+The authoritative lane also writes
+`content-type-boost-promotion.json` and `.md`. These 24 before/after receipts
+project the fn-97 production retrieval rankings through the shipped
+content-type ranking seam with no configured rules. Every ordered URI and
+required-evidence receipt must remain byte-identical, with zero accuracy and
+coverage loss. This is backward-compatibility evidence for existing configs,
+not an active-rule quality claim.
+
+Active positive/negative factors, keyword stuffing, deterministic ties,
+configured-ID versus prefix conflicts, filter isolation, and project-affinity
+composition are gated separately by the deterministic adversarial pipeline
+suite. Egress policy is not yet an available retrieval capability, so the
+artifact makes no egress-enforcement claim.
+
 The first fixture version contains 24 original synthetic tasks and 34 Markdown
 documents under the MIT license. It covers exact identifiers, ambiguity,
 multi-document comparisons, meeting decisions, temporal questions, typed

package/spec/mcp.md

@@ -216,7 +216,7 @@ Required input:
 Optional fields are `collection`, `limit` (default 5), `minScore`, `lang`,
 `intent`, `candidateLimit`, `exclude`, `queryModes`, `tagsAll`, `tagsAny`,
 `since`, `until`, `categories`, `author`, `graph`, `noGraph`, `noRerank`,
-`maxAnswerTokens`, `contextBudgetTokens`, and `contextBudgetBytes`. Input
+`explain`, `maxAnswerTokens`, `contextBudgetTokens`, and `contextBudgetBytes`. Input
 objects are closed.
 `projectHints` is an optional array of at most 16 non-empty caller hints. Hints
 are normalized and deduplicated as opaque values, never resolved against or
@@ -648,6 +648,11 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
       "description": "Enable cross-encoder reranking",
       "default": true
     },
+    "explain": {
+      "type": "boolean",
+      "description": "Include deterministic stage and per-result scoring metadata",
+      "default": false
+    },
     "noGraph": {
       "type": "boolean",
       "description": "Compatibility no-op unless graph is also true",
@@ -692,6 +697,11 @@ Search result items include `contentType` when available and always include
 human-oriented; structured clients should read `structuredContent.results`.
 Structured result items also preserve optional `context` guidance in
 global-to-specific order without changing the result `uri` or `docid`.
+When `explain: true`, `structuredContent.meta.explain` includes deterministic
+stage lines and per-result score receipts. Non-neutral configured content-type
+rules add `contentTypeBoost` with base/raw scores, factor, capped contribution,
+shared auxiliary-cap composition, final score, rule source, and redacted rules
+fingerprint. Normal output omits this sidecar.
 
 Compatibility / migration notes:
 
@@ -753,16 +763,17 @@ plus a required `target` reference.
 - `target`: URI, `#docid`, or `collection/path` for the document to diagnose.
 - `query`, filters, `queryModes`, `fast`/`thorough`, `graph`, and rerank/expand controls behave like `gno_query`.
 
-**Output Schema:** `gno://schemas/query-diagnose@1.0`
+**Output Schema:** `gno://schemas/query-diagnose@1.2`
 
 Structured content includes `schemaVersion`, normalized `query`, `target`
 metadata/status (`not_found`, `inactive`, `no_indexed_content`,
 `filtered_out`, or `diagnosed`), `stages` for BM25/vector/fusion/graph/rerank,
 the selected target `chunk`, and retrieval `meta`.
-MCP inputs are remote and untrusted, so this tool preserves exact v1.0 bytes
-and omits `affinity`, even when `projectHints` are supplied. The shared current
-validation schema is `gno://schemas/query-diagnose@1.1`; its affinity-bearing
-v1.1 branch is reserved for trusted local CLI diagnose requests.
+MCP inputs are remote and untrusted, so this tool omits `affinity`, even when
+`projectHints` are supplied. Neutral configurations preserve exact v1.0 bytes;
+an active configured content-type boost emits v1.2 with the same bounded score
+receipt exposed by query explain. The v1.1 affinity-bearing branch remains
+reserved for trusted local CLI diagnose requests.
 
 Use when an expected target is missing from `gno_query`, when filters may have
 excluded it, or when an agent needs evidence before raising `candidateLimit`,
@@ -979,11 +990,19 @@ counters; it never claims attachment to another process.
     "totalDocuments": 150,
     "totalChunks": 800,
     "embeddingBacklog": 0,
+    "contentTypeBoost": {
+      "rulesFingerprint": "<sha256>",
+      "rules": [{ "id": "decision", "searchBoost": 2 }]
+    },
     "healthy": true
   }
 }
 ```
 
+`contentTypeBoost` is a redacted ranking-status projection. It exposes only
+normalized IDs/factors plus the rules fingerprint; path prefixes are never
+returned.
+
 ---
 
 ### gno_capture

package/spec/output-schemas/ask.schema.json

@@ -557,6 +557,9 @@
               }
             }
           }
+        },
+        "explain": {
+          "$ref": "gno://schemas/search-results@1.0#/properties/meta/properties/explain"
         }
       }
     }

package/spec/output-schemas/query-diagnose.schema.json

@@ -1,11 +1,11 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "gno://schemas/query-diagnose@1.1",
+  "$id": "gno://schemas/query-diagnose@1.2",
   "title": "GNO Query Diagnose",
   "type": "object",
   "required": ["schemaVersion", "query", "target", "stages", "chunk", "meta"],
   "properties": {
-    "schemaVersion": { "type": "string", "enum": ["1.0", "1.1"] },
+    "schemaVersion": { "type": "string", "enum": ["1.0", "1.1", "1.2"] },
     "query": { "type": "string" },
     "target": {
       "type": "object",
@@ -160,6 +160,51 @@
       },
       "additionalProperties": false
     },
+    "contentTypeBoost": {
+      "type": "object",
+      "required": [
+        "baseScore",
+        "cappedContribution",
+        "combinedAuxiliaryApplied",
+        "combinedAuxiliaryCap",
+        "combinedAuxiliaryRequested",
+        "configuredFactor",
+        "contentType",
+        "finalScore",
+        "rawContribution",
+        "rawScore",
+        "rawScoreKind",
+        "ruleSource",
+        "rulesFingerprint"
+      ],
+      "properties": {
+        "baseScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "cappedContribution": {
+          "type": "number",
+          "minimum": -0.05,
+          "maximum": 0.05
+        },
+        "combinedAuxiliaryApplied": {
+          "type": "number",
+          "minimum": -0.08,
+          "maximum": 0.08
+        },
+        "combinedAuxiliaryCap": { "type": "number", "const": 0.08 },
+        "combinedAuxiliaryRequested": { "type": "number" },
+        "configuredFactor": { "type": "number", "minimum": 0.5, "maximum": 2 },
+        "contentType": { "type": "string" },
+        "finalScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "rawContribution": { "type": "number" },
+        "rawScore": { "type": "number" },
+        "rawScoreKind": {
+          "type": "string",
+          "enum": ["bm25", "hybrid_blended", "normalized", "vector_distance"]
+        },
+        "ruleSource": { "type": "string", "enum": ["configured-id", "prefix"] },
+        "rulesFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
     "chunk": {
       "type": "object",
       "required": ["seq", "startLine", "endLine", "language"],
@@ -199,7 +244,9 @@
         "properties": { "schemaVersion": { "const": "1.0" } },
         "required": ["schemaVersion"]
       },
-      "then": { "properties": { "affinity": false } }
+      "then": {
+        "properties": { "affinity": false, "contentTypeBoost": false }
+      }
     },
     {
       "if": {
@@ -207,9 +254,19 @@
         "required": ["schemaVersion"]
       },
       "then": {
-        "properties": { "affinity": {} },
+        "properties": { "affinity": {}, "contentTypeBoost": false },
         "required": ["affinity"]
       }
+    },
+    {
+      "if": {
+        "properties": { "schemaVersion": { "const": "1.2" } },
+        "required": ["schemaVersion"]
+      },
+      "then": {
+        "properties": { "contentTypeBoost": {} },
+        "required": ["contentTypeBoost"]
+      }
     }
   ],
   "additionalProperties": false

package/spec/output-schemas/search-results.schema.json

@@ -166,7 +166,78 @@
             "type": "string"
           }
         }
-      }
+      },
+      "additionalProperties": false
+    },
+    "contentTypeBoost": {
+      "type": "object",
+      "required": [
+        "baseScore",
+        "cappedContribution",
+        "combinedAuxiliaryApplied",
+        "combinedAuxiliaryCap",
+        "combinedAuxiliaryRequested",
+        "configuredFactor",
+        "contentType",
+        "finalScore",
+        "rawContribution",
+        "rawScore",
+        "rawScoreKind",
+        "ruleSource",
+        "rulesFingerprint"
+      ],
+      "properties": {
+        "baseScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "cappedContribution": {
+          "type": "number",
+          "minimum": -0.05,
+          "maximum": 0.05
+        },
+        "combinedAuxiliaryApplied": {
+          "type": "number",
+          "minimum": -0.08,
+          "maximum": 0.08
+        },
+        "combinedAuxiliaryCap": { "type": "number", "const": 0.08 },
+        "combinedAuxiliaryRequested": { "type": "number" },
+        "configuredFactor": { "type": "number", "minimum": 0.5, "maximum": 2 },
+        "contentType": { "type": "string" },
+        "finalScore": { "type": "number", "minimum": 0, "maximum": 1 },
+        "rawContribution": { "type": "number" },
+        "rawScore": { "type": "number" },
+        "rawScoreKind": {
+          "type": "string",
+          "enum": ["bm25", "hybrid_blended", "normalized", "vector_distance"]
+        },
+        "ruleSource": { "type": "string", "enum": ["configured-id", "prefix"] },
+        "rulesFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "explainLine": {
+      "type": "object",
+      "required": ["stage", "message"],
+      "properties": {
+        "stage": { "type": "string" },
+        "message": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "explainResult": {
+      "type": "object",
+      "required": ["rank", "docid", "score"],
+      "properties": {
+        "rank": { "type": "integer", "minimum": 1 },
+        "docid": { "type": "string", "pattern": "^#[a-f0-9]{6,8}$" },
+        "score": { "type": "number" },
+        "fusionScore": { "type": "number" },
+        "bm25Score": { "type": "number" },
+        "vecScore": { "type": "number" },
+        "rerankScore": { "type": "number" },
+        "projectAffinity": { "type": "object" },
+        "contentTypeBoost": { "$ref": "#/$defs/contentTypeBoost" }
+      },
+      "additionalProperties": false
     }
   },
   "properties": {
@@ -331,6 +402,21 @@
           "type": "array",
           "items": { "type": "string" },
           "description": "Tags ANY filter applied (if any)"
+        },
+        "explain": {
+          "type": "object",
+          "required": ["lines", "results"],
+          "properties": {
+            "lines": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/explainLine" }
+            },
+            "results": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/explainResult" }
+            }
+          },
+          "additionalProperties": false
         }
       }
     }

package/spec/output-schemas/status.schema.json

@@ -15,6 +15,7 @@
     "recentErrors",
     "activePreset",
     "capabilities",
+    "contentTypeBoost",
     "activation",
     "onboarding",
     "health",
@@ -136,6 +137,29 @@
         }
       }
     },
+    "contentTypeBoost": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rulesFingerprint", "rules"],
+      "properties": {
+        "rulesFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "searchBoost"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "searchBoost": { "type": "number", "minimum": 0.5, "maximum": 2 }
+            }
+          }
+        }
+      }
+    },
     "activation": {
       "type": "object",
       "additionalProperties": false,

package/spec/project-profile.schema.json

@@ -270,7 +270,9 @@
           }
         },
         "searchBoost": {
-          "type": "number"
+          "type": "number",
+          "minimum": 0.5,
+          "maximum": 2
         },
         "temporal": {
           "type": "boolean"

package/src/app/context-runtime-contract.ts

@@ -26,7 +26,10 @@ const fingerprint = (value: unknown): string =>
 
 export const contextRuntimeConfigFingerprint = (
   deps: Pick<ContextCapsuleRuntimeDeps, "config">
-): string => fingerprint(deps.config);
+): string =>
+  fingerprint(
+    JSON.parse(JSON.stringify(deps.config)) as Record<string, unknown>
+  );
 
 const configuredContextFingerprint = (
   deps: ContextCapsuleRuntimeDeps

package/src/app/context-runtime-types.ts

@@ -55,6 +55,8 @@ export interface ContextCapsuleRuntimeDeps {
   projectAffinity?: ProjectAffinityScoringInput;
   /** Optional non-canonical receipt session owned by the calling surface. */
   traceSession?: RetrievalTraceSession;
+  /** Internal non-canonical retrieval explanation request. */
+  explain?: boolean;
 }
 
 export type ContextRuntimeErrorCode =

package/src/app/context-runtime.ts

@@ -4,6 +4,7 @@ import type {
   ContextCapsuleV1,
   ContextCapsuleVerification,
 } from "../core/context-capsule";
+import type { SearchExplain } from "../pipeline/types";
 import type {
   ContextCapsuleBuildInput,
   ContextCapsuleRuntimeDeps,
@@ -36,6 +37,19 @@ export type {
 } from "./context-runtime-types";
 export { ContextRuntimeError } from "./context-runtime-types";
 
+export const CONTEXT_CAPSULE_EXPLAIN_METADATA = Symbol(
+  "gno.contextCapsuleExplainMetadata"
+);
+
+export const getContextCapsuleExplain = (
+  capsule: ContextCapsuleV1
+): SearchExplain | undefined =>
+  (
+    capsule as ContextCapsuleV1 & {
+      [CONTEXT_CAPSULE_EXPLAIN_METADATA]?: SearchExplain;
+    }
+  )[CONTEXT_CAPSULE_EXPLAIN_METADATA];
+
 /** Build one strict Capsule through the shared compiler composition. */
 export const buildContextCapsule = async (
   input: ContextCapsuleBuildInput,
@@ -72,6 +86,7 @@ export const buildContextCapsule = async (
       limit: normalized.limit,
       candidateLimit: normalized.candidateLimit,
       temporalNow: now,
+      explain: deps.explain,
       limits: {
         requestedBytes: normalized.budgetBytes,
         requestedTokens: normalized.budgetTokens,
@@ -134,6 +149,17 @@ export const buildContextCapsule = async (
       traceResult.error.cause
     );
   }
+  if (plan.explain) {
+    Object.defineProperty(
+      plan.projection.value,
+      CONTEXT_CAPSULE_EXPLAIN_METADATA,
+      {
+        configurable: true,
+        enumerable: false,
+        value: plan.explain,
+      }
+    );
+  }
   return plan.projection.value;
 };
 

package/src/app/verified-ask.ts

@@ -16,6 +16,7 @@ import { attachCitationTraceMetadata } from "../pipeline/trace-metadata";
 import { CITATION_TRACE_METADATA } from "../pipeline/types";
 import {
   buildContextCapsule,
+  getContextCapsuleExplain,
   verifyContextCapsuleRuntime,
 } from "./context-runtime";
 import { contextRuntimeConfigFingerprint } from "./context-runtime-contract";
@@ -199,7 +200,7 @@ export const buildVerifiedAsk = async (
       budgetBytes: options.contextBudgetBytes,
       depthPolicy: "balanced",
     },
-    deps
+    { ...deps, explain: options.explain }
   );
   const freshness = await verifyContextCapsuleRuntime(capsule, deps);
   return synthesizeVerifiedAsk(query, options, capsule, freshness, deps);
@@ -258,6 +259,9 @@ export const synthesizeVerifiedAsk = async (
     citationEvidenceIds(verification, new Set(["supported", "contradicted"]))
   );
   await recordRetainedCitations(deps.traceSession, traceCitations);
+  const retrievalExplain = options.explain
+    ? getContextCapsuleExplain(capsule)
+    : undefined;
   return {
     query,
     mode: capsule.capabilities.semanticSearch ? "hybrid" : "bm25_only",
@@ -276,6 +280,7 @@ export const synthesizeVerifiedAsk = async (
       exclude: capsule.retrieval.request.exclude,
       answerGenerated: generated.ok,
       totalResults: capsule.evidence.length,
+      ...(retrievalExplain ? { explain: retrievalExplain } : {}),
       verificationRequested: true,
       abstained: verification.verification.abstained,
     },

package/src/cli/commands/ask.ts

@@ -48,7 +48,10 @@ export { formatAsk } from "./ask-format";
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type AskCommandOptions = Omit<AskOptions, "projectAffinity"> &
+export type AskCommandOptions = Omit<
+  AskOptions,
+  "contentTypeRules" | "projectAffinity"
+> &
   CliProjectAffinityRequest & {
     /** Override config path */
     configPath?: string;
@@ -318,6 +321,7 @@ export async function ask(
       noExpand: options.noExpand,
       noRerank: options.noRerank,
       candidateLimit: options.candidateLimit,
+      explain: options.explain,
       projectAffinity,
       traceSession,
     });
@@ -397,6 +401,9 @@ export async function ask(
         answerGenerated,
         totalResults: results.length,
         answerContext,
+        ...(options.explain && searchResult.value.meta.explain
+          ? { explain: searchResult.value.meta.explain }
+          : {}),
       },
     };
 

package/src/cli/commands/query.ts

@@ -16,7 +16,7 @@ import type {
 import type { HybridSearchOptions, SearchResults } from "../../pipeline/types";
 
 import {
-  fingerprintContentTypeRules,
+  fingerprintContentTypeMetadataRules,
   normalizeContentTypes,
 } from "../../config";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
@@ -48,7 +48,10 @@ import { decorateSearchResultsForIndex, initStore } from "./shared";
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type QueryCommandOptions = Omit<HybridSearchOptions, "projectAffinity"> &
+export type QueryCommandOptions = Omit<
+  HybridSearchOptions,
+  "contentTypeRules" | "projectAffinity"
+> &
   CliProjectAffinityRequest & {
     /** Override config path */
     configPath?: string;
@@ -439,7 +442,7 @@ export async function queryDiagnose(
       projectAffinity,
       contentTypeRules,
       contentTypeRulesFingerprint:
-        fingerprintContentTypeRules(contentTypeRules),
+        fingerprintContentTypeMetadataRules(contentTypeRules),
     });
 
     if (!result.ok) {