@gmickel/gno 2.10.1 → 2.12.0

package/spec/mcp.md

@@ -7,7 +7,10 @@
 **Transport:** JSON-RPC 2.0 over stdio or resident Streamable HTTP
 **SDK:** `@modelcontextprotocol/server` 2.x (tool `inputSchema` /
 `outputSchema` carry the JSON Schema 2020-12 `$schema` stamp; an unknown tool
-name answers JSON-RPC `-32602`)
+name answers JSON-RPC `-32602`). Tool inputs are closed objects: an argument
+key a tool does not declare fails validation with an error naming the key, and
+the tool does not run. Each `inputSchema` advertises `additionalProperties:
+false` (per `oneOf` member for the discriminated-union inputs).
 
 This document specifies the MCP server interface for GNO.
 
@@ -153,7 +156,7 @@ the resident gateway applies one profile to every connected client.
 
 | Profile          | Without `--enable-write`                                                                              | With `--enable-write`                                   |
 | ---------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| `full` (default) | Every read tool below (37)                                                                            | Every read tool plus every write tool (59)              |
+| `full` (default) | Every read tool below (38)                                                                            | Every read tool plus every write tool (60)              |
 | `core`           | `gno_query`, `gno_search`, `gno_get`, `gno_multi_get`, `gno_context`, `gno_changes`, `gno_recall` (7) | The 7 read tools plus `gno_capture`, `gno_remember` (9) |
 
 Both lists are exact: `core` advertises nothing else, and `full` is byte-for-byte
@@ -525,7 +528,7 @@ non-reflection contract as all MCP retrieval tools.
 
 `structuredContent` is the complete canonical Context Capsule object for
 application clients. Model-visible text is always one deterministic
-`gno-context-agent-v1` JSON projection, even when the compatibility `format`
+`gno-context-agent-v2` JSON projection, even when the compatibility `format`
 field is present. The compact keys and tuple positions are part of that
 versioned contract:
 
@@ -537,8 +540,14 @@ versioned contract:
   or `null`, enabled capability names, fallbacks.
 - `e[]`: URI, start line, end line, source hash, mirror hash, passage hash,
   exact extractive text, title, heading, configured-context IDs, egress
-  classification. Title/heading are nullable; egress is explicit even when the
-  policy is unavailable.
+  classification, content date, `supersededBy`. Title/heading are nullable;
+  egress is explicit even when the policy is unavailable. The content date is
+  the document's own date (frontmatter date, a record's date, or a memory
+  fact's `memory.createdAt`), never the file modification time, and `null` when
+  the document has none. `supersededBy` is the current successor's URI when a
+  newer memory fact superseded this one, otherwise `null`; an agent must not
+  present superseded evidence as current. v2 appends these two positions to
+  the v1 tuple; every earlier position is unchanged.
 - `g`: evidence trust (`untrusted_data`), instruction boundary
   (`hard_delimited`), then configured-guidance tuples containing context ID,
   scope type, scope key, and exact guidance text. Evidence `contextIds` bind
@@ -907,7 +916,7 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
     },
     "fast": {
       "type": "boolean",
-      "description": "Fast mode: skip expansion and reranking (~0.7s)",
+      "description": "Fast mode: skip expansion and reranking (typically under a second on a warm server)",
       "default": false
     },
     "thorough": {
@@ -1937,6 +1946,27 @@ paths or session content.
 archive lock; `SESSIONS_RUNTIME_FAILURE` (fixed, path-free message) for filesystem or
 index failures.
 
+### gno_list_metadata
+
+List the typed metadata keys indexed documents carry, with observed types,
+document counts and most common values (array members count individually).
+
+**Input Schema:**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "collection": { "type": "string" },
+    "values": { "type": "integer", "minimum": 1, "maximum": 100 }
+  }
+}
+```
+
+**Output Schema:** `gno://schemas/metadata-summary`. Text content is the same
+summary as `gno metadata`. Full profile only.
+
 ### gno_list_tags
 
 List all tags with document counts.

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

@@ -169,6 +169,10 @@
           "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
         },
         "egressLineage": { "$ref": "#/$defs/egressLineage" },
+        "supersededBy": {
+          "type": "string",
+          "description": "URI of the current fact when a newer memory fact superseded this result"
+        },
         "snippet": {
           "type": "string",
           "description": "Matching text snippet from document mirror"
@@ -447,6 +451,10 @@
             "type": "integer",
             "description": "Citation end line",
             "minimum": 1
+          },
+          "supersededBy": {
+            "type": "string",
+            "description": "URI of the current fact when a newer memory fact superseded the cited one"
           }
         }
       }

package/spec/output-schemas/claim-verification.schema.json

@@ -186,7 +186,8 @@
             "semantic_entailment",
             "semantic_contradiction",
             "no_valid_evidence",
-            "semantic_judgment_unavailable"
+            "semantic_judgment_unavailable",
+            "quote_not_in_evidence"
           ]
         },
         "verifierFingerprint": {
@@ -260,7 +261,12 @@
           "if": { "properties": { "status": { "const": "uncertain" } } },
           "then": {
             "properties": {
-              "rationaleCode": { "const": "semantic_judgment_unavailable" },
+              "rationaleCode": {
+                "enum": [
+                  "semantic_judgment_unavailable",
+                  "quote_not_in_evidence"
+                ]
+              },
               "evidence": { "type": "array", "minItems": 1 }
             }
           }

package/spec/output-schemas/context-capsule-v1.schema.json

@@ -924,7 +924,12 @@
           "enum": ["local_only", "lan", "remote", "unclassified", "unavailable"]
         },
         "egressLineage": { "$ref": "#/definitions/egressLineage" },
-        "record": { "$ref": "#/definitions/recordEvidenceMetadata" }
+        "record": { "$ref": "#/definitions/recordEvidenceMetadata" },
+        "supersededBy": {
+          "type": "string",
+          "pattern": "^gno://",
+          "description": "Current successor when a newer memory fact superseded this one"
+        }
       }
     },
     "coverage": {

package/spec/output-schemas/context-capsule-verification.schema.json

@@ -1229,7 +1229,8 @@
             "chunk_missing",
             "chunk_corrupt",
             "source_missing",
-            "mirror_missing"
+            "mirror_missing",
+            "superseded"
           ]
         },
         "rankingStatus": {
@@ -1273,7 +1274,8 @@
                   "mirror_corrupt",
                   "passage_stale",
                   "chunk_missing",
-                  "chunk_corrupt"
+                  "chunk_corrupt",
+                  "superseded"
                 ]
               },
               "currentSourceHash": { "$ref": "#/definitions/sha256" },

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

@@ -129,6 +129,10 @@
         "reason": { "type": "string" }
       }
     },
+    "supersededBy": {
+      "type": "string",
+      "description": "URI of the current fact when a newer memory fact superseded this document"
+    },
     "record": {
       "type": "object",
       "additionalProperties": false,

package/spec/output-schemas/metadata-summary.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/metadata-summary",
+  "title": "Typed metadata summary",
+  "description": "Typed metadata keys indexed documents carry: observed types, document counts and the most common values. Returned by `gno metadata --json`, MCP gno_list_metadata, GET /api/metadata and SDK listMetadata.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["collection", "documents", "documentsWithMetadata", "keys"],
+  "properties": {
+    "collection": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+    "documents": { "type": "integer", "minimum": 0 },
+    "documentsWithMetadata": { "type": "integer", "minimum": 0 },
+    "keys": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "types", "documents", "values", "valuesTruncated"],
+        "properties": {
+          "key": { "type": "string", "minLength": 1 },
+          "types": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "enum": [
+                "string",
+                "number",
+                "boolean",
+                "string[]",
+                "number[]",
+                "boolean[]"
+              ]
+            }
+          },
+          "documents": { "type": "integer", "minimum": 1 },
+          "values": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["value", "documents"],
+              "properties": {
+                "value": {
+                  "oneOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "boolean" }
+                  ]
+                },
+                "documents": { "type": "integer", "minimum": 1 }
+              }
+            }
+          },
+          "valuesTruncated": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/multi-get.schema.json

@@ -49,6 +49,10 @@
               "ext": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" }
             }
           },
+          "supersededBy": {
+            "type": "string",
+            "description": "URI of the current fact when a newer memory fact superseded this document"
+          },
           "record": {
             "type": "object",
             "additionalProperties": false,

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

@@ -50,6 +50,10 @@
       "type": "string",
       "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
     },
+    "supersededBy": {
+      "type": "string",
+      "description": "URI of the current fact when a newer memory fact superseded this result"
+    },
     "snippet": {
       "type": "string",
       "description": "Matching text snippet from document mirror"

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

@@ -84,6 +84,10 @@
           "description": "Resolved user-configured retrieval guidance, ordered from global to collection to matching path prefixes"
         },
         "egressLineage": { "$ref": "#/$defs/egressLineage" },
+        "supersededBy": {
+          "type": "string",
+          "description": "URI of the current fact when a newer memory fact superseded this result"
+        },
         "snippet": {
           "type": "string",
           "description": "Matching text snippet from document mirror"

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

@@ -140,6 +140,21 @@
             "type": "integer",
             "description": "Number of chunks with embeddings",
             "minimum": 0
+          },
+          "rootError": {
+            "type": "object",
+            "description": "Present only while the collection root is missing or unreadable, checked when status is read; the collection's indexed documents are kept and still counted. The message names the filesystem error but not the path.",
+            "additionalProperties": false,
+            "required": ["code", "message"],
+            "properties": {
+              "code": {
+                "type": "string",
+                "const": "SOURCE_AVAILABILITY_UNKNOWN"
+              },
+              "message": {
+                "type": "string"
+              }
+            }
           }
         }
       }
@@ -257,6 +272,19 @@
         }
       }
     },
+    "staleCollections": {
+      "type": "array",
+      "description": "Indexed collections the config does not list. Commands that sync the config refuse to open the index (nothing is deleted) until the collections are added back or `gno cleanup` deletes their index data. Omitted when there are none.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "documents"],
+        "properties": {
+          "name": { "type": "string" },
+          "documents": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
     "recentErrors": {
       "type": "integer",
       "description": "Recent ingest errors in the last 24 hours",

package/src/app/constants.ts

@@ -361,6 +361,22 @@ export function decorateUriForIndex(uri: string, indexName?: string): string {
   });
 }
 
+/**
+ * Decorate a result's URI and, when present, its successor URI for the index
+ * it came from.
+ */
+export function decorateResultUris<
+  T extends { uri: string; supersededBy?: string },
+>(item: T, indexName?: string): T {
+  return {
+    ...item,
+    uri: decorateUriForIndex(item.uri, indexName),
+    ...(item.supersededBy
+      ? { supersededBy: decorateUriForIndex(item.supersededBy, indexName) }
+      : {}),
+  };
+}
+
 /**
  * Remove output-only index metadata from a gno:// URI.
  */

package/src/app/context-agent-projection.ts

@@ -3,7 +3,7 @@
 import type { ContextCapsuleV1 } from "../core/context-capsule";
 
 export const CONTEXT_AGENT_PROJECTION_SCHEMA_VERSION =
-  "gno-context-agent-v1" as const;
+  "gno-context-agent-v2" as const;
 
 export interface ContextAgentProjectionEvidence {
   uri: string;
@@ -17,6 +17,9 @@ export interface ContextAgentProjectionEvidence {
   contextIds: readonly string[];
   egress: "local_only" | "lan" | "remote" | "unclassified" | "unavailable";
   text: string;
+  /** Content date (frontmatter or record date), never the file mtime. */
+  documentDate: string | null;
+  supersededBy: string | null;
 }
 
 export interface ContextAgentProjectionGuidance {
@@ -97,6 +100,8 @@ type EvidenceTuple = readonly [
   heading: string | null,
   contextIds: readonly string[],
   egress: ContextAgentProjectionEvidence["egress"],
+  documentDate: string | null,
+  supersededBy: string | null,
 ];
 
 type GuidanceTuple = readonly [
@@ -207,6 +212,8 @@ const projection = (
       item.heading,
       item.contextIds,
       item.egress,
+      item.documentDate,
+      item.supersededBy,
     ]),
     g: [
       source.guidance.evidenceTrust,
@@ -275,6 +282,8 @@ export const projectContextCapsuleForAgent = (
     contextIds: item.contextIds,
     egress: item.egress,
     text: item.text,
+    documentDate: item.documentDate,
+    supersededBy: item.supersededBy ?? null,
   })),
   coverage: {
     requestedFacets: capsule.coverage.requestedFacets,

package/src/app/context-format.ts

@@ -98,6 +98,7 @@ const evidenceBlock = (
     `- Selection rank: ${item.selectionRank}`,
     `- Modified: ${nullable(item.modifiedAt)}`,
     `- Document date: ${nullable(item.documentDate)}`,
+    ...(item.supersededBy ? [`- Superseded by: ${item.supersededBy}`] : []),
     `- Observed: ${nullable(item.observedAt)}`,
     `- Facets: ${item.facets.length > 0 ? item.facets.join(", ") : "none"}`,
     `- Trust: ${item.trust}`,

package/src/app/verified-ask.ts

@@ -49,6 +49,8 @@ const generationSources = (capsule: ContextCapsuleV1) => {
         return text ? [text] : [];
       })
       .join("\n"),
+    date: evidence.documentDate ?? undefined,
+    supersededBy: evidence.supersededBy,
   }));
 };
 

package/src/cli/commands/agents/block.ts

@@ -17,7 +17,7 @@ import { CliError } from "../../errors.js";
 // ─────────────────────────────────────────────────────────────────────────────
 
 /** Version of the protocol block content. Bump on any content change. */
-export const BLOCK_VERSION = 3;
+export const BLOCK_VERSION = 5;
 
 /** Stable across block versions — never change these once shipped. */
 export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
@@ -43,17 +43,18 @@ Local knowledge search over indexed collections. Source files are the truth; the
 
 Ladder — scope to a collection first (\`--collection <name>\`):
 
-1. Exact term/identifier/quote/error: \`gno search "<text>"\`
-2. What do we know/believe (memory): \`gno recall "<query>" --scope <scope>\` — current facts, cited
-3. Entity or known document: \`gno query "<question>" --fast -n 10\`
-4. Multi-document evidence: \`gno context build "<goal>" --budget 12000\`
-5. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
-6. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
-7. Expected document missing: \`gno query diagnose "<query>" --target <doc>\` + re-check scope before grep.
+1. Exact term/identifier/quote/error you already have verbatim: \`gno search "<text>"\`. A question, or a name or topic taken from it, is not exact text: use rung 3
+2. What do we know/believe (memory): \`gno recall "<query>" --scope <scope>\`
+3. Any other question: \`gno query "<question>" --fast -n 10\` (hybrid)
+4. Not found or vague: \`gno query "<question>" -n 10\` (adds expansion + rerank)
+5. Multi-document evidence: \`gno context build "<goal>" --budget 12000\`
+6. Changes/dependencies: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
+7. Generated answer: \`gno ask "<question>" --verify\` (abstention is valid)
+8. Expected document missing: \`gno query diagnose "<query>" --target <doc>\` before grep.
 
 Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title, provenance) — never an update API. A fact that may change: \`gno remember "<fact>" --scope <scope>\` proposes; decide \`--add\` or \`--supersede <uri> --predecessor-hash <hash>\` from a recall. Recalled spans are context, not new facts: pass the receipt (\`--receipt\`). After writes: reindex the collection, verify retrieval.
 
-Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks) and memory recipes live in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
+Cite with gno:// URIs. Filters, structured queries, backlinks and memory recipes live in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
 }
 
 /** SHA-256 hex digest of the body, truncated for the stamp line. */

package/src/cli/commands/agents/commands.ts

@@ -170,7 +170,7 @@ async function runMutation(
   // the operator the exact block to paste (install/update only — uninstall
   // guidance is in the per-target detail).
   const manualBlock =
-    failedPaths.length > 0 && mode === "install" ? renderBlock() : undefined;
+    failedPaths.length > 0 && mode !== "uninstall" ? renderBlock() : undefined;
 
   if (json) {
     process.stdout.write(
@@ -217,15 +217,16 @@ async function runMutation(
 }
 
 /**
- * Install or refresh the protocol block. Both verbs converge the block to
- * the current release: install appends when absent, update replaces an
- * older/stale block in place; a current block is a no-op for either.
+ * Install or refresh the protocol block. Both verbs replace an older/stale
+ * block in place and treat a current block as a no-op; only install appends
+ * where no block exists. Update reports such a file `absent` (with an
+ * install hint) and never writes or creates it.
  */
 export function installAgents(
   opts: AgentsOptions = {},
   verb: "install" | "update" = "install"
 ): Promise<void> {
-  return runMutation(verb, "install", opts);
+  return runMutation(verb, verb, opts);
 }
 
 /** Remove the protocol block and its markers, leaving the rest untouched. */

package/src/cli/commands/agents/engine.ts

@@ -35,12 +35,16 @@ export type PlanAction =
   | "update" // block present but differs — replace in place
   | "current" // block present and identical — no-op
   | "remove" // uninstall: block present — remove it
-  | "absent" // uninstall: no block — no-op
+  | "absent" // update/uninstall: no block — no-op, file untouched
   | "covered" // import chain or same real file — another target owns it
   | "not-detected" // harness not installed on this machine — skipped
   | "error"; // fail-closed (malformed markers, unreadable file)
 
-export type PlanMode = "install" | "uninstall";
+/** `update` refreshes existing blocks only; it never appends or creates. */
+export type PlanMode = "install" | "update" | "uninstall";
+
+const UPDATE_ABSENT_DETAIL =
+  "no GNO agents block to refresh; run `gno agents install` to add one";
 
 export interface TargetPlan {
   target: ResolvedTarget;
@@ -261,6 +265,15 @@ export async function planTargets(
       );
       continue;
     }
+    if (mode === "update" && !extraction.found) {
+      plans.push({
+        ...base,
+        action: "absent",
+        detail: UPDATE_ABSENT_DETAIL,
+        newContent: content,
+      });
+      continue;
+    }
 
     const newContent = withBlock(
       content,

package/src/cli/commands/agents/harnesses.ts

@@ -183,25 +183,32 @@ function isDirectory(path: string): boolean {
   }
 }
 
+/**
+ * The harness's documented config-dir override from the environment
+ * (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`): trimmed, unset when empty, and
+ * rejected unless absolute. Shared with `gno skill` user-scope resolution.
+ */
+export function harnessConfigDirFromEnv(id: HarnessId): string | undefined {
+  const envVar = HARNESS_DEFS[id].configDirEnvVar;
+  const value = envVar ? process.env[envVar]?.trim() : undefined;
+  if (!(envVar && value)) {
+    return undefined;
+  }
+  if (!isAbsolute(value)) {
+    throw new CliError("VALIDATION", `${envVar} must be an absolute path`);
+  }
+  return normalize(value);
+}
+
 function resolveHarness(
   def: HarnessDef,
   home: string,
   explicitHome: boolean
 ): ResolvedTarget {
-  let configDir = join(home, def.configDir);
-
-  if (!explicitHome && def.configDirEnvVar) {
-    const envOverride = process.env[def.configDirEnvVar];
-    if (envOverride) {
-      if (!isAbsolute(envOverride)) {
-        throw new CliError(
-          "VALIDATION",
-          `${def.configDirEnvVar} must be an absolute path`
-        );
-      }
-      configDir = normalize(envOverride);
-    }
-  }
+  const envOverride = explicitHome
+    ? undefined
+    : harnessConfigDirFromEnv(def.id);
+  const configDir = envOverride ?? join(home, def.configDir);
 
   // A covered harness (grok → claude) reads its covering harness's file and
   // has none of its own, so that is the file its rows report.

package/src/cli/commands/ask-format.ts

@@ -146,6 +146,9 @@ const formatTerminal = (data: AskResult, opts: FormatOptions = {}): string => {
           ? ""
           : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
       lines.push(`  [${index + 1}] ${citation.uri}${range}`);
+      if (citation.supersededBy) {
+        lines.push(`      Superseded by: ${citation.supersededBy}`);
+      }
     }
     lines.push("");
   }
@@ -158,12 +161,18 @@ const formatTerminal = (data: AskResult, opts: FormatOptions = {}): string => {
         `  [${evidence.docid}] ${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}`
       );
       if (evidence.title) lines.push(`    ${evidence.title}`);
+      if (evidence.supersededBy) {
+        lines.push(`    Superseded by: ${evidence.supersededBy}`);
+      }
     }
   } else if (showAllSources && data.results.length > 0) {
     lines.push(hasAnswer ? "All Retrieved Sources:" : "Sources:");
     for (const result of data.results) {
       lines.push(`  [${result.docid}] ${result.uri}`);
       if (result.title) lines.push(`    ${result.title}`);
+      if (result.supersededBy) {
+        lines.push(`    Superseded by: ${result.supersededBy}`);
+      }
     }
   } else if (hasAnswer && data.results.length > 0) {
     const citedCount = data.citations?.length ?? 0;
@@ -196,7 +205,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
         citation.startLine === undefined
           ? ""
           : `:L${citation.startLine}${citation.endLine === undefined || citation.endLine === citation.startLine ? "" : `-L${citation.endLine}`}`;
-      lines.push(`**[${index + 1}]** \`${citation.uri}${range}\``);
+      lines.push(
+        `**[${index + 1}]** \`${citation.uri}${range}\`${citation.supersededBy ? ` (superseded by \`${citation.supersededBy}\`)` : ""}`
+      );
     }
     lines.push("");
   }
@@ -216,6 +227,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
           `${index + 1}. **${evidence.title || evidence.uri}**`,
           `   - URI: \`${exactSpan(evidence.uri, evidence.startLine, evidence.endLine)}\``
         );
+        if (evidence.supersededBy) {
+          lines.push(`   - Superseded by: \`${evidence.supersededBy}\``);
+        }
       }
     } else {
       for (const [index, result] of data.results.entries()) {
@@ -223,6 +237,9 @@ const formatMarkdown = (data: AskResult, opts: FormatOptions = {}): string => {
           `${index + 1}. **${result.title || result.source.relPath}**`
         );
         lines.push(`   - URI: \`${result.uri}\``);
+        if (result.supersededBy) {
+          lines.push(`   - Superseded by: \`${result.supersededBy}\``);
+        }
         lines.push(`   - Score: ${result.score.toFixed(2)}`);
       }
       if (data.results.length === 0) lines.push("*No relevant sources found.*");

package/src/cli/commands/ask.ts

@@ -15,7 +15,7 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
-import { decorateUriForIndex } from "../../app/constants";
+import { decorateResultUris } from "../../app/constants";
 import { buildVerifiedAsk } from "../../app/verified-ask";
 import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
@@ -89,10 +89,9 @@ export function decorateAskUris(
   result: AskResult,
   indexName: string | undefined
 ): AskResult {
-  const decorate = <T extends { uri: string }>(item: T): T => ({
-    ...item,
-    uri: decorateUriForIndex(item.uri, indexName),
-  });
+  const decorate = <T extends { uri: string; supersededBy?: string }>(
+    item: T
+  ): T => decorateResultUris(item, indexName);
   const answerContext = result.meta.answerContext;
   return {
     ...result,