@gmickel/gno 2.10.0 → 2.11.0

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/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-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 = 4;
 
 /** Stable across block versions — never change these once shipped. */
 export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
@@ -44,16 +44,17 @@ 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.
+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/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,

package/src/cli/commands/cleanup.ts

@@ -1,6 +1,7 @@
 /**
  * gno cleanup command implementation.
- * Remove orphaned content, chunks, vectors not referenced by active documents.
+ * Remove documents of collections no longer configured, then orphaned
+ * content, chunks and vectors not referenced by active documents.
  *
  * @module src/cli/commands/cleanup
  */
@@ -61,6 +62,13 @@ export async function cleanup(
   }
 
   try {
+    // Drop collections no longer in the config first (their documents follow
+    // by cascade), so their content, chunks and vectors count as orphans.
+    const syncResult = await store.syncCollections(config.collections);
+    if (!syncResult.ok) {
+      return { success: false, error: syncResult.error.message };
+    }
+
     const cleanupResult = await store.cleanupOrphans();
     if (!cleanupResult.ok) {
       return { success: false, error: cleanupResult.error.message };

package/src/cli/commands/collection/remove.ts

@@ -3,43 +3,62 @@
  */
 
 import { removeCollection } from "../../../collection";
-import { applyConfigFileChange } from "../../../core/config-mutation";
+import { applyConfigChange } from "../../../core/config-mutation";
 import { CliError } from "../../errors";
+import { initStore } from "../shared";
 
 export async function collectionRemove(
   name: string,
-  options: { configPath?: string } = {}
+  options: { configPath?: string; indexName?: string } = {}
 ): Promise<void> {
-  const mutation = await applyConfigFileChange(
-    { configPath: options.configPath },
-    (config) => {
-      const result = removeCollection(config, { name });
-      return result.ok
-        ? {
-            ok: true as const,
-            config: result.config,
-            value: result.collection,
-          }
-        : {
-            ok: false as const,
-            error: result.message,
-            code: result.code,
-          };
+  // Open the index so the removal reaches the store in the same locked
+  // boundary: syncing collections deletes the collection row, and its
+  // documents follow by cascade. A config-only edit left them active (and
+  // counted in the embedding backlog) until some later command synced.
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) {
+    throw new CliError("RUNTIME", initialized.error);
+  }
+
+  try {
+    const mutation = await applyConfigChange(
+      { store: initialized.store, configPath: initialized.actualConfigPath },
+      (config) => {
+        const result = removeCollection(config, { name });
+        return result.ok
+          ? {
+              ok: true as const,
+              config: result.config,
+              value: result.collection,
+            }
+          : {
+              ok: false as const,
+              error: result.message,
+              code: result.code,
+            };
+      }
+    );
+
+    if (!mutation.ok) {
+      // Map collection error codes to CLI error codes
+      const cliCode =
+        mutation.code === "VALIDATION" ||
+        mutation.code === "NOT_FOUND" ||
+        mutation.code === "HAS_REFERENCES"
+          ? "VALIDATION"
+          : "RUNTIME";
+      throw new CliError(cliCode, mutation.error);
     }
-  );
 
-  if (!mutation.ok) {
-    // Map collection error codes to CLI error codes
-    const cliCode =
-      mutation.code === "VALIDATION" ||
-      mutation.code === "NOT_FOUND" ||
-      mutation.code === "HAS_REFERENCES"
-        ? "VALIDATION"
-        : "RUNTIME";
-    throw new CliError(cliCode, mutation.error);
+    process.stdout.write(
+      `Collection "${mutation.value?.name}" removed successfully\n`
+    );
+  } finally {
+    await initialized.store.close();
   }
-
-  process.stdout.write(
-    `Collection "${mutation.value?.name}" removed successfully\n`
-  );
 }

package/src/cli/commands/collection/rename.ts

@@ -3,19 +3,51 @@
  */
 
 import { CollectionSchema, getCollectionFromScope } from "../../../config";
-import { applyConfigFileChange } from "../../../core/config-mutation";
+import { applyConfigChange } from "../../../core/config-mutation";
 import { CliError } from "../../errors";
+import { initStore, type InitStoreResult } from "../shared";
 
 export async function collectionRename(
   oldName: string,
   newName: string,
-  options: { configPath?: string } = {}
+  options: { configPath?: string; indexName?: string } = {}
 ): Promise<void> {
   const oldCollectionName = oldName.toLowerCase();
   const newCollectionName = newName.toLowerCase();
 
-  const mutation = await applyConfigFileChange(
-    { configPath: options.configPath },
+  // Documents are keyed by collection name (URIs, FTS paths, links), so the
+  // index cannot rename them in place. Sync in the same locked boundary: the
+  // old name's documents go now instead of at some later sync, and the next
+  // update indexes the files under the new name.
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) {
+    throw new CliError("RUNTIME", initialized.error);
+  }
+
+  try {
+    await renameAndSync(initialized, oldCollectionName, newCollectionName);
+  } finally {
+    await initialized.store.close();
+  }
+
+  process.stdout.write(
+    `Collection "${oldCollectionName}" renamed to "${newCollectionName}"\n` +
+      "Run: gno update to index it under the new name\n"
+  );
+}
+
+async function renameAndSync(
+  initialized: Extract<InitStoreResult, { ok: true }>,
+  oldCollectionName: string,
+  newCollectionName: string
+): Promise<void> {
+  const mutation = await applyConfigChange(
+    { store: initialized.store, configPath: initialized.actualConfigPath },
     (config) => {
       const collection = config.collections.find(
         (item) => item.name === oldCollectionName
@@ -70,8 +102,4 @@ export async function collectionRename(
       mutation.error
     );
   }
-
-  process.stdout.write(
-    `Collection "${oldCollectionName}" renamed to "${newCollectionName}"\n`
-  );
 }

package/src/cli/commands/daemon.ts

@@ -99,7 +99,11 @@ export function logSessionAutomationResult(
 }
 
 function formatCollectionSyncSummary(result: CollectionSyncResult): string {
-  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
+  const collectionErrors = result.errors
+    .filter((error) => error.relPath === "")
+    .map((error) => `; [${error.code}] ${error.message}`)
+    .join("");
+  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors${collectionErrors}`;
 }
 
 export const authorizeDaemonStatus = async (

package/src/cli/commands/get.ts

@@ -29,6 +29,7 @@ import {
   evidenceFromExactDocument,
   RetrievalTraceSession as TraceSession,
 } from "../../core/retrieval-trace-session";
+import { supersedingUri } from "../../pipeline/result-context";
 import { parseRef } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -90,6 +91,8 @@ export interface GetResponse {
     mirrorHash?: string;
   };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
   capabilities: DocumentCapabilities;
 }
 
@@ -269,7 +272,7 @@ async function fetchDocument(
     return { success: false, error: "Mirror content unavailable" };
   }
 
-  return buildResponse({
+  const response = buildResponse({
     doc,
     fullContent: contentResult.value,
     parsed,
@@ -277,6 +280,10 @@ async function fetchDocument(
     config,
     indexName,
   });
+  const successor = await supersedingUri(store, doc.uri);
+  if (response.success && successor)
+    response.data.supersededBy = decorateUriForIndex(successor, indexName);
+  return response;
 }
 
 interface BuildResponseContext {
@@ -467,6 +474,9 @@ function formatMarkdown(data: GetResponse, options: GetCommandOptions): string {
   lines.push("");
   lines.push(`- **URI**: \`${data.uri}\``);
   lines.push(`- **DocID**: \`${data.docid}\``);
+  if (data.supersededBy) {
+    lines.push(`- **Superseded by**: \`${data.supersededBy}\``);
+  }
   if (data.returnedLines) {
     lines.push(
       `- **Lines**: ${data.returnedLines.start}-${data.returnedLines.end} of ${data.totalLines}`

package/src/cli/commands/metadata.ts

@@ -0,0 +1,79 @@
+/**
+ * gno metadata - list the typed metadata keys indexed documents carry.
+ *
+ * @module src/cli/commands/metadata
+ */
+
+import {
+  formatMetadataSummary,
+  type MetadataSummary,
+  readMetadataSummary,
+} from "../../core/metadata-discovery";
+import { initStore } from "./shared";
+
+export interface MetadataListOptions {
+  configPath?: string;
+  indexName?: string;
+  collection?: string;
+  values?: number;
+}
+
+export type MetadataListResult =
+  | { success: true; data: MetadataSummary }
+  | { success: false; error: string; isValidation?: boolean };
+
+export async function metadataList(
+  options: MetadataListOptions = {}
+): Promise<MetadataListResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+  });
+  if (!initResult.ok) return { success: false, error: initResult.error };
+  const { store } = initResult;
+  try {
+    return {
+      success: true,
+      data: await readMetadataSummary(store, {
+        collection: options.collection,
+        values: options.values,
+      }),
+    };
+  } catch (cause) {
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : String(cause),
+      isValidation: cause instanceof RangeError,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatMetadataList(
+  data: MetadataSummary,
+  options: { json?: boolean; md?: boolean }
+): string {
+  if (options.json) return JSON.stringify(data, null, 2);
+  if (!options.md) return formatMetadataSummary(data);
+  const lines = [
+    "# Typed metadata",
+    "",
+    `*${data.documentsWithMetadata} of ${data.documents} documents${data.collection ? ` in \`${data.collection}\`` : ""}*`,
+  ];
+  if (data.keys.length === 0) return lines.join("\n");
+  lines.push(
+    "",
+    "| Key | Types | Documents | Common values |",
+    "|---|---|---|---|"
+  );
+  for (const key of data.keys) {
+    const values = key.values
+      .map((item) => `\`${JSON.stringify(item.value)}\` (${item.documents})`)
+      .join(", ");
+    lines.push(
+      `| \`${key.key}\` | ${key.types.join(", ")} | ${key.documents} | ${values}${key.valuesTruncated ? ", ..." : ""} |`
+    );
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/multi-get.ts

@@ -21,6 +21,7 @@ import {
   projectRecordEvidenceMetadata,
   type RecordEvidenceMetadata,
 } from "../../core/record-metadata";
+import { supersedingUri } from "../../pipeline/result-context";
 import { isGlobPattern, parseRef, splitRefs } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -58,6 +59,8 @@ export interface MultiGetDocument {
   totalLines?: number;
   source: { absPath?: string; relPath: string; mime: string; ext: string };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
 }
 
 export interface SkippedDoc {
@@ -236,7 +239,11 @@ async function fetchSingleDocument(
   const coll = ctx.config.collections.find((c) => c.name === doc.collection);
 
   const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+  const successor = await supersedingUri(ctx.store, doc.uri);
   ctx.documents.push({
+    ...(successor
+      ? { supersededBy: decorateUriForIndex(successor, ctx.indexName) }
+      : {}),
     docid: doc.docid,
     uri: decorateUriForIndex(doc.uri, ctx.indexName),
     title: doc.title ?? undefined,
@@ -422,6 +429,9 @@ function formatMarkdown(
   for (const doc of data.documents) {
     lines.push(`## ${doc.title || doc.source.relPath}`);
     lines.push(`- **URI**: \`${doc.uri}\``);
+    if (doc.supersededBy) {
+      lines.push(`- **Superseded by**: \`${doc.supersededBy}\``);
+    }
     if (doc.truncated) {
       lines.push(`- **Truncated**: yes (max ${data.meta.maxBytes} bytes)`);
     }
@@ -450,6 +460,9 @@ function formatTerminal(
 
   for (const doc of data.documents) {
     lines.push(`=== ${doc.uri} ===`);
+    if (doc.supersededBy) {
+      lines.push(`Superseded by: ${doc.supersededBy}`);
+    }
     lines.push(formatContent(doc.content, Boolean(options.lineNumbers)));
     lines.push("");
   }

package/src/cli/commands/shared.ts

@@ -11,7 +11,7 @@ import type { SearchResults } from "../../pipeline/types";
 
 import {
   DEFAULT_INDEX_NAME,
-  decorateUriForIndex,
+  decorateResultUris,
   getIndexDbPath,
 } from "../../app/constants";
 import {
@@ -164,10 +164,9 @@ export function decorateSearchResultsForIndex(
   }
   return {
     ...data,
-    results: data.results.map((result) => ({
-      ...result,
-      uri: decorateUriForIndex(result.uri, indexName),
-    })),
+    results: data.results.map((result) =>
+      decorateResultUris(result, indexName)
+    ),
   };
 }
 
@@ -217,10 +216,13 @@ export function formatSyncResultLines(
       lines.push(`  ${c.filesErrored} errors`);
     }
     // A file stopped at its conversion budget is always named, not only in
-    // verbose output: it stays unindexed until a later run finishes it.
+    // verbose output: it stays unindexed until a later run finishes it. So is
+    // a collection-level error such as an unavailable root.
     if (!options.verbose) {
       for (const err of c.errors) {
-        if (BUDGET_ERROR_CODES.has(err.code)) {
+        if (err.relPath === "") {
+          lines.push(`    [${err.code}] ${err.message}`);
+        } else if (BUDGET_ERROR_CODES.has(err.code)) {
           lines.push(`    [${err.code}] ${err.relPath}: ${err.message}`);
         }
       }

package/src/cli/format/search-results.ts

@@ -88,6 +88,9 @@ function formatTerminal(data: SearchResults, options: FormatOptions): string {
     if (r.title) {
       lines.push(`  ${r.title}`);
     }
+    if (r.supersededBy) {
+      lines.push(`  Superseded by: ${r.supersededBy}`);
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet
@@ -175,6 +178,9 @@ function formatMarkdown(data: SearchResults, options: FormatOptions): string {
     lines.push(`- **URI**: \`${r.uri}\``);
     lines.push(`- **Score**: ${r.score.toFixed(2)}`);
     lines.push(`- **DocID**: \`${r.docid}\``);
+    if (r.supersededBy) {
+      lines.push(`- **Superseded by**: \`${r.supersededBy}\``);
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet
@@ -223,6 +229,11 @@ function formatXml(data: SearchResults, options: FormatOptions): string {
       lines.push(`    <title>${escapeXml(r.title)}</title>`);
     }
     lines.push(`    <relPath>${escapeXml(r.source.relPath)}</relPath>`);
+    if (r.supersededBy) {
+      lines.push(
+        `    <supersededBy>${escapeXml(r.supersededBy)}</supersededBy>`
+      );
+    }
     if (r.snippet) {
       const content = options.full
         ? r.snippet

package/src/cli/options.ts

@@ -82,6 +82,7 @@ export const CMD = {
   contextSaved: "context.saved",
   modelsList: "models.list",
   tagsList: "tags.list",
+  metadataList: "metadata",
   linksList: "links.list",
   backlinks: "backlinks",
   similar: "similar",
@@ -118,6 +119,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.contextSaved]: ["terminal", "json"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
+  [CMD.metadataList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],
   [CMD.backlinks]: ["terminal", "json", "md"],
   [CMD.similar]: ["terminal", "json", "md"],