@hraness/wordcell 0.23.0 → 0.24.1

package/README.md

@@ -3,9 +3,11 @@
 
 [![Agent Skill](https://raw.githubusercontent.com/hraness/wordcell/main/assets/agent-skill.svg)](https://github.com/hraness/wordcell/tree/main/skills/wordcell)
 
-Wordcell keeps decisions, plans, and sources as Markdown files beside your
-code. Coding agents find them by exact words, by meaning with an optional
-local model, or from the file they are about to change.
+Wordcell is a Markdown knowledge base and local MCP memory server for coding
+agents such as Claude Code, Codex, and Cursor. It keeps decisions, plans, and
+sources as Markdown files beside your code, and agents find them by exact
+words, by meaning with an optional local model, or from the file they are
+about to change.
 
 A new coding-agent session can read your code, but not the decisions that
 stayed in the last session's chat. Wordcell keeps those decisions as Markdown
@@ -20,7 +22,7 @@ Web capture, optional hosted reranking, and your agent's provider reach other
 services; [Privacy and boundaries](#privacy-and-boundaries) says what each one
 sends.
 
-[Documentation](https://wordcell.io/docs) · [Comparisons](https://github.com/hraness/wordcell/blob/main/docs/comparisons.md) · [Measured evidence](https://github.com/hraness/wordcell/blob/main/docs/evidence.md) · [Changelog](https://github.com/hraness/wordcell/blob/main/CHANGELOG.md)
+[Documentation](https://wordcell.io/docs) · [Comparisons](https://wordcell.io/docs/comparisons) · [Measured evidence](https://wordcell.io/docs/evidence) · [Changelog](https://github.com/hraness/wordcell/blob/main/CHANGELOG.md)
 
 ## Why Wordcell
 
@@ -42,7 +44,7 @@ sends.
 Plain Markdown may be enough for a small set of notes. QMD is a good fit for
 local document retrieval and also supplies Wordcell's optional semantic search.
 Wordcell adds a connected workflow for repository context, authored relationships,
-Git evidence, and selective publishing. [Compare the tradeoffs](https://github.com/hraness/wordcell/blob/main/docs/comparisons.md).
+Git evidence, and selective publishing. [Compare the tradeoffs](https://wordcell.io/docs/comparisons).
 
 Wordcell keeps the record in Markdown files you own, rebuilds every index from those files, and lets the next session start from the notes for the file it is changing: the design every Hraness project shares. [The thread through hraness](https://hraness.com/writing/the-thread-through-hraness) follows that design across the projects, and the [ALGAL vision](https://algal.computer/docs/vision/) states the bet behind it.
 
@@ -52,14 +54,14 @@ Wordcell keeps the record in Markdown files you own, rebuilds every index from t
 The CLI and TypeScript SDK run with Bun. Install the versioned GitHub archive:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.23.0/hraness-wordcell-0.23.0.tgz
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.24.1/hraness-wordcell-0.24.1.tgz
 wordcell --help
 ```
 
 Prefer npm? The same release is [mirrored there](https://www.npmjs.com/package/@hraness/wordcell):
 
 ```sh
-npm install --global --ignore-scripts @hraness/wordcell@0.23.0
+npm install --global --ignore-scripts @hraness/wordcell@0.24.1
 wordcell --help
 ```
 
@@ -101,7 +103,7 @@ After trying the CLI, install the public Agent Skill into a compatible agent,
 such as Claude Code, Codex, Cursor, or GitHub Copilot:
 
 ```sh
-bunx skills add hraness/wordcell#v0.23.0 --skill wordcell
+bunx skills add hraness/wordcell#v0.24.1 --skill wordcell
 ```
 
 Then ask:
@@ -247,6 +249,14 @@ keeps one vault current on several machines.
 
 ## Evidence and comparisons
 
+On eight questions sealed before the passage selector was finished,
+`wordcell search --selected-passage` returned an excerpt holding the labeled
+answer for **6 of 8**, versus **1 of 8** for the older search snippets, at the
+same 512-byte limit and from the same retrieved notes. It runs locally with no
+model. The corpus is small and consists of Wordcell's own notes; containing the
+answer is not the same as an agent answering correctly.
+[Method, raw results, and reproduction](https://github.com/hraness/wordcell/blob/main/docs/evidence.md#measure-whether-excerpts-contain-the-answer).
+
 In a four-query example over a seven-note public vault, packed search snippets
 used **80% fewer UTF-8 bytes** than passing the same matching notes in full:
 12,126 versus 60,584 bytes. This measures context payload size, not tokenizer
@@ -262,17 +272,20 @@ Wordcell's benefit is selecting relevant context and keeping its sources
 inspectable. Local ownership is also available in other tools, and Wordcell
 does not claim to beat QMD's retrieval quality or every Markdown workflow.
 
-[Measured evidence](https://github.com/hraness/wordcell/blob/main/docs/evidence.md)
+[Measured evidence](https://wordcell.io/docs/evidence)
 shows a reproducible public-vault example, with the inputs, output sizes, and
-limits beside each result. [The comparison guide](https://github.com/hraness/wordcell/blob/main/docs/comparisons.md)
+limits beside each result. [The comparison guide](https://wordcell.io/docs/comparisons)
 covers Markdown alone, QMD, Basic Memory, Obsidian, static publishing tools,
 Supermemory, Mem0, and Zep using their own documentation. Choose the smallest
 workflow that meets your needs.
 
-The [benchmarks page](https://wordcell.io/benchmarks) shows the payload and
-SciFact results beside the published results of Oh, the embedded memory
-framework, each with its source data and limits. Oh's scores measure its own
-memory-retrieval path, not a Wordcell vault.
+The [benchmarks page](https://wordcell.io/benchmarks) shows the excerpt, payload,
+and SciFact results beside the published results of Oh, the embedded memory
+framework, each with its source data and limits. On all 500 LongMemEval-S
+questions, Oh semantic retrieval scored 88.87% and BM25 86.13% with the same
+reader and budget; on the measure Oh named before the run, its interval does
+not rule out a tie. Oh's scores measure its own memory-retrieval path, not a
+Wordcell vault.
 
 ## How the files fit together
 
@@ -321,7 +334,7 @@ exist. [Graph queries and proof limits](https://github.com/hraness/wordcell/blob
 Add the same immutable release to a Bun project:
 
 ```sh
-bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.23.0/hraness-wordcell-0.23.0.tgz
+bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.24.1/hraness-wordcell-0.24.1.tgz
 ```
 
 The SDK provides read-only vault sessions, metadata queries, search, graph
@@ -358,7 +371,7 @@ the design. Browse it on the [documentation index](https://wordcell.io/docs).
 | [Web capture](https://github.com/hraness/wordcell/blob/main/docs/capture.md) and [PDF capture](https://github.com/hraness/wordcell/blob/main/docs/pdf.md) | Save sources with provenance, assets, and explicit completeness limits. |
 | [Publish selected notes](https://github.com/hraness/wordcell/blob/main/docs/publish.md) | Preview a slice, build a static site, and choose how to host it. |
 | [Graph guide](https://github.com/hraness/wordcell/blob/main/docs/graph-authority.md) | Named queries, proofs, revisions, resource limits, and cache recovery. |
-| [Portfolio federation](https://github.com/hraness/wordcell/blob/main/docs/portfolio.md) | Search only selected, authorized vaults. |
+| [Search several vaults together](https://github.com/hraness/wordcell/blob/main/docs/portfolio.md) | Search only selected, authorized vaults. |
 | [Sync with Git](https://github.com/hraness/wordcell/blob/main/docs/sync.md) | Keep one vault current on several machines with a private repository. |
 | [Migrate from Supermemory](https://github.com/hraness/wordcell/blob/main/docs/migration-from-supermemory.md) | Export documents and memory entries, import them as notes, and replace connectors. |
 | [Design](https://github.com/hraness/wordcell/blob/main/docs/design.md) and [memory rationale](https://github.com/hraness/wordcell/blob/main/docs/agent-memory.md) | File contracts, design choices, and evaluation context. |

package/dist/authoring.js

@@ -14,8 +14,9 @@ import {
   noteRevision,
   removeNoteRelation,
   updateNoteBody
-} from "./index-b0khj0h5.js";
+} from "./index-qt2zwza8.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import"./index-z1w83f81.js";
 export {

package/dist/cli.js

@@ -6,10 +6,10 @@ import {
   parseArguments,
   runExecutable,
   usage
-} from "./index-vtwbapjr.js";
-import"./index-0eacgvpv.js";
+} from "./index-jqkkb4fr.js";
+import"./index-t0fh8a1q.js";
 import"./index-qfqjfxaa.js";
-import"./index-r4qs6vq4.js";
+import"./index-hz2wyggk.js";
 import"./index-j4zgmzjr.js";
 import"./index-2fmnttca.js";
 import"./index-6jcz0m1c.js";
@@ -28,16 +28,16 @@ import"./index-mxxxytys.js";
 import"./index-23z4zxgg.js";
 import"./index-pj501bh1.js";
 import"./index-9rf81m0p.js";
-import"./index-mnq2wy34.js";
-import"./index-tvd2sqrx.js";
+import"./index-59bcxqee.js";
+import"./index-mcpppwbq.js";
 import"./index-adx6khj5.js";
 import"./index-fp732bgg.js";
 import"./index-4j3tt0c3.js";
 import"./index-j70m75wd.js";
 import"./index-b88v3vtm.js";
-import"./index-tcaq1c7f.js";
+import"./index-e26mdwxz.js";
 import"./index-bdwcjvr4.js";
-import"./index-1er88ckw.js";
+import"./index-3gc2yk4k.js";
 import"./index-pgtm2nhf.js";
 import"./index-1gwbassd.js";
 import"./index-ahyhryb8.js";
@@ -53,8 +53,9 @@ import"./index-23m6bbjt.js";
 import"./index-hya40gb2.js";
 import"./index-5vwpzb5a.js";
 import"./index-x3fthpsc.js";
-import"./index-b0khj0h5.js";
+import"./index-qt2zwza8.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import {
   __require
@@ -62,7 +63,7 @@ import {
 
 // src/cli.ts
 if (import.meta.main) {
-  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-c8hy7qfa.js");
+  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-07jpt1z4.js");
   const env = standaloneSupportEnvironment();
   const args = process.argv.slice(2);
   if (args[0] === "support") {

package/dist/clip/jobs.js

@@ -9,6 +9,9 @@ import {
 import {
   acquireFileLease
 } from "../index-3rm7cz6h.js";
+import {
+  syncsDirectories
+} from "../index-qkesh4c6.js";
 import"../index-z1w83f81.js";
 
 // src/clip/jobs.ts
@@ -360,7 +363,8 @@ async function fsyncStore(store) {
     if (!stat.isDirectory() || !sameIdentity(stat, expected)) {
       throw new CaptureJobSafetyError("Capture job store changed before synchronization.");
     }
-    await handle.sync();
+    if (syncsDirectories())
+      await handle.sync();
   } finally {
     await handle.close();
   }

package/dist/evaluation-builder.js

@@ -4,8 +4,8 @@ import {
   knowledgeBaseEvaluationRetrieverIds,
   openKnowledgeBaseEvaluation,
   verifyFrozenEvaluationSnapshot
-} from "./index-mnq2wy34.js";
-import"./index-tvd2sqrx.js";
+} from "./index-59bcxqee.js";
+import"./index-mcpppwbq.js";
 import"./index-adx6khj5.js";
 import {
   indexSemanticVault,
@@ -19,9 +19,9 @@ import {
   MAX_EVALUATION_EVIDENCE_BYTES,
   MAX_EVALUATION_RESULTS_PER_QUERY
 } from "./index-b88v3vtm.js";
-import"./index-tcaq1c7f.js";
+import"./index-e26mdwxz.js";
 import"./index-bdwcjvr4.js";
-import"./index-1er88ckw.js";
+import"./index-3gc2yk4k.js";
 import"./index-pgtm2nhf.js";
 import {
   runGitCommand
@@ -36,6 +36,7 @@ import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import"./index-z1w83f81.js";
 

package/dist/evaluation-kb.js

@@ -4,16 +4,16 @@ import {
   knowledgeBaseEvaluationRetrieverIds,
   openKnowledgeBaseEvaluation,
   verifyFrozenEvaluationSnapshot
-} from "./index-mnq2wy34.js";
-import"./index-tvd2sqrx.js";
+} from "./index-59bcxqee.js";
+import"./index-mcpppwbq.js";
 import"./index-adx6khj5.js";
 import"./index-fp732bgg.js";
 import"./index-4j3tt0c3.js";
 import"./index-j70m75wd.js";
 import"./index-b88v3vtm.js";
-import"./index-tcaq1c7f.js";
+import"./index-e26mdwxz.js";
 import"./index-bdwcjvr4.js";
-import"./index-1er88ckw.js";
+import"./index-3gc2yk4k.js";
 import"./index-pgtm2nhf.js";
 import"./index-1gwbassd.js";
 import"./index-ahyhryb8.js";
@@ -24,6 +24,7 @@ import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import"./index-z1w83f81.js";
 export {

package/dist/graph-authority.js

@@ -5,7 +5,7 @@ import {
   queryGraph,
   rebuildGraph,
   verifyGraph
-} from "./index-1er88ckw.js";
+} from "./index-3gc2yk4k.js";
 import {
   GRAPH_LIMITS,
   GraphAuthorityError,
@@ -15,6 +15,7 @@ import"./index-1s8mc4hz.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import"./index-z1w83f81.js";
 export {

package/dist/graph-percolation.js

@@ -1,14 +1,15 @@
 // @bun
 import {
   percolateWithGraph
-} from "./index-tcaq1c7f.js";
+} from "./index-e26mdwxz.js";
 import"./index-bdwcjvr4.js";
-import"./index-1er88ckw.js";
+import"./index-3gc2yk4k.js";
 import"./index-pgtm2nhf.js";
 import"./index-1s8mc4hz.js";
 import"./index-06c9ctr6.js";
 import"./index-5vwpzb5a.js";
 import"./index-3rm7cz6h.js";
+import"./index-qkesh4c6.js";
 import"./index-jvb7w0gg.js";
 import"./index-z1w83f81.js";
 export {

package/dist/{index-1er88ckw.js → index-3gc2yk4k.js}

@@ -13,6 +13,9 @@ import {
 import {
   acquireFileLease
 } from "./index-3rm7cz6h.js";
+import {
+  syncsDirectories
+} from "./index-qkesh4c6.js";
 import {
   VaultAnalysisBudgetError,
   analyzeVault,
@@ -443,11 +446,13 @@ async function rebuildGraph(rootInput, options = {}) {
       await handle.close();
     }
     await rename(stagedPath, path);
-    const directory = await graphCacheFileSystem.open(cache, constants.O_RDONLY);
-    try {
-      await directory.sync();
-    } finally {
-      await directory.close();
+    if (syncsDirectories()) {
+      const directory = await graphCacheFileSystem.open(cache, constants.O_RDONLY);
+      try {
+        await directory.sync();
+      } finally {
+        await directory.close();
+      }
     }
     return result;
   } finally {

package/dist/{index-mnq2wy34.js → index-59bcxqee.js}

@@ -2,7 +2,7 @@
 import {
   MAX_SEARCH_RESULTS,
   openKnowledgeBase
-} from "./index-tvd2sqrx.js";
+} from "./index-mcpppwbq.js";
 import {
   MAX_EVALUATION_EVIDENCE_BYTES,
   redactEvaluationMachinePaths

package/dist/{index-p70t8j13.js → index-7drercgk.js}

@@ -4,7 +4,7 @@ import {
 } from "./index-h170byqw.js";
 import {
   packUntrustedSearchContext
-} from "./index-tvd2sqrx.js";
+} from "./index-mcpppwbq.js";
 
 // src/workflows/decision-context.ts
 var decisionContextWorkflow = defineWorkflow({

package/dist/{index-tcaq1c7f.js → index-e26mdwxz.js}

@@ -5,7 +5,7 @@ import {
 import {
   createGraphSnapshot,
   openGraphAuthority
-} from "./index-1er88ckw.js";
+} from "./index-3gc2yk4k.js";
 import {
   GraphAuthorityError,
   validateGraphPercolationOptions

package/dist/{index-r4qs6vq4.js → index-hz2wyggk.js}

@@ -5,7 +5,7 @@ import {
   MAX_SEARCH_RESULTS,
   openKnowledgeBase,
   validateKnowledgeBaseSearchHistory
-} from "./index-tvd2sqrx.js";
+} from "./index-mcpppwbq.js";
 import {
   expandSearchRequest,
   parseSearchRules

package/dist/{index-vtwbapjr.js → index-jqkkb4fr.js}

@@ -3,7 +3,7 @@ import {
   backfillSavedUrlMetadata,
   createRustMetadataSearchProvider,
   savedSourceProblem
-} from "./index-0eacgvpv.js";
+} from "./index-t0fh8a1q.js";
 import {
   main as main2
 } from "./index-qfqjfxaa.js";
@@ -13,7 +13,7 @@ import {
   loadPortfolioRegistry,
   openKnowledgePortfolio,
   snapshotPortfolioRegistry
-} from "./index-r4qs6vq4.js";
+} from "./index-hz2wyggk.js";
 import {
   diffCaptureBundle
 } from "./index-j4zgmzjr.js";
@@ -51,7 +51,7 @@ import {
 import {
   knowledgeBaseEvaluationRetrieverIds,
   openKnowledgeBaseEvaluation
-} from "./index-mnq2wy34.js";
+} from "./index-59bcxqee.js";
 import {
   DEFAULT_SEARCH_RESULTS,
   MAX_SEARCH_CANDIDATES,
@@ -60,7 +60,7 @@ import {
   MAX_SEARCH_RESULTS,
   openKnowledgeBase,
   searchEvidenceRank
-} from "./index-tvd2sqrx.js";
+} from "./index-mcpppwbq.js";
 import {
   MAX_SEARCH_RULE_CONFIG_BYTES,
   parseSearchRules
@@ -85,7 +85,7 @@ import {
 } from "./index-b88v3vtm.js";
 import {
   percolateWithGraph
-} from "./index-tcaq1c7f.js";
+} from "./index-e26mdwxz.js";
 import {
   MAX_PERCOLATION_MENTIONS,
   MAX_PERCOLATION_MENTION_PAIRS,
@@ -97,7 +97,7 @@ import {
   queryGraph,
   rebuildGraph,
   verifyGraph
-} from "./index-1er88ckw.js";
+} from "./index-3gc2yk4k.js";
 import {
   validateGraphQueryRequest
 } from "./index-pgtm2nhf.js";
@@ -184,7 +184,10 @@ import {
   sha256,
   updateNoteBody,
   updateNoteBodyProgram
-} from "./index-b0khj0h5.js";
+} from "./index-qt2zwza8.js";
+import {
+  syncsDirectories
+} from "./index-qkesh4c6.js";
 import {
   isMetadataNumber,
   lookupNote,
@@ -440,7 +443,10 @@ function installMetadataSearchExecutable(input) {
   const backupName = `.${executableName}.${process.pid}.${randomUUID()}.backup`;
   const stagingPath = join(toolDirectory, stagingName);
   const backupPath = join(toolDirectory, backupName);
-  const syncDirectory = input.syncDirectory ?? ((descriptor) => fsyncSync(descriptor));
+  const syncDirectory = input.syncDirectory ?? ((descriptor) => {
+    if (syncsDirectories())
+      fsyncSync(descriptor);
+  });
   const toolBinding = openBoundDirectory(toolDirectory, "metadata-search tool directory");
   let targetBinding = null;
   let releaseBinding = null;
@@ -932,6 +938,7 @@ var commandHelp = [
       ["--min-score <score>", "Drop results scoring below this (0 to 1)"],
       ["--rerank <typesafe>", "Rerank results with the hosted TypeSafe service"],
       ["--rerank-limit <2..25>", "How many results the reranker sees"],
+      ["--selected-passage", "Add a local source excerpt to each result"],
       JSON_OPTION
     ],
     examples: ['wordcell search "retries" --root kb --mode exact', 'wordcell search "retry policy" --root kb --limit 5']
@@ -3624,6 +3631,15 @@ function requiredText(arguments_, key, maxBytes) {
 function optionalText(arguments_, key, maxBytes) {
   return has(arguments_, key) ? checkedText(arguments_[key], key, maxBytes) : undefined;
 }
+function optionalBoolean(arguments_, key) {
+  if (!has(arguments_, key))
+    return;
+  const value = arguments_[key];
+  if (typeof value !== "boolean") {
+    throw new ToolArgumentError(`Invalid argument "${key}": expected a boolean.`);
+  }
+  return value;
+}
 function optionalInteger(arguments_, key, minimum, maximum) {
   if (!has(arguments_, key))
     return;
@@ -3923,6 +3939,11 @@ function readTools(root, sessions) {
           properties: {
             query: { type: "string", minLength: 1, maxLength: MAX_QUERY_TEXT_UTF8_BYTES },
             mode: { type: "string", enum: SEARCH_MODES, default: "hybrid" },
+            selectedPassage: {
+              type: "boolean",
+              default: false,
+              description: "Include a local source excerpt with line references and section headings. Ranking is unchanged."
+            },
             limit: { type: "integer", minimum: 1, maximum: MAX_SEARCH_RESULTS, default: DEFAULT_SEARCH_RESULTS },
             ...filterProperties
           }
@@ -3930,10 +3951,11 @@ function readTools(root, sessions) {
         annotations: { title: "Search notes", ...READ_ONLY }
       },
       handler: async (arguments_) => {
-        allowOnly(arguments_, ["query", "mode", "limit", "tags", "where", "has", "scope"]);
+        allowOnly(arguments_, ["query", "mode", "limit", "tags", "where", "has", "scope", "selectedPassage"]);
         const query = requiredText(arguments_, "query", MAX_QUERY_TEXT_UTF8_BYTES);
         const mode = optionalChoice(arguments_, "mode", SEARCH_MODES) ?? "hybrid";
         const limit = optionalInteger(arguments_, "limit", 1, MAX_SEARCH_RESULTS) ?? DEFAULT_SEARCH_RESULTS;
+        const selectedPassage = optionalBoolean(arguments_, "selectedPassage");
         const filters = metadataFilters(arguments_);
         const tags = optionalTextList(arguments_, "tags", MAX_QUERY_TAGS, MAX_QUERY_TEXT_UTF8_BYTES);
         const scopes = optionalTextList(arguments_, "scope", MAX_REPOSITORY_SCOPES, MAX_QUERY_TEXT_UTF8_BYTES);
@@ -3942,6 +3964,7 @@ function readTools(root, sessions) {
           query,
           mode,
           limit,
+          ...selectedPassage === undefined ? {} : { selectedPassage },
           ...filters.length === 0 ? {} : { filters },
           ...tags === undefined ? {} : { tags },
           ...scopes === undefined ? {} : { repositoryScopes: scopes }
@@ -5151,6 +5174,7 @@ function parseSemanticCommand(command, arguments_) {
   let minScore;
   let rerank;
   let rerankLimit;
+  let selectedPassage = false;
   let graphDepth;
   let noGraph = false;
   let history = false;
@@ -5177,6 +5201,10 @@ function parseSemanticCommand(command, arguments_) {
       noGraph = true;
       continue;
     }
+    if (argument === "--selected-passage" && command === "search") {
+      selectedPassage = true;
+      continue;
+    }
     if (argument === "--no-history" && command === "search") {
       noHistory = true;
       continue;
@@ -5402,6 +5430,7 @@ function parseSemanticCommand(command, arguments_) {
       ...minScore === undefined ? {} : { minScore },
       ...rerank === undefined ? {} : { rerank },
       ...rerankLimit === undefined ? {} : { rerankLimit },
+      ...selectedPassage ? { selectedPassage: true } : {},
       query,
       json
     }
@@ -6293,6 +6322,22 @@ function renderSemanticIndex(result) {
   ].join(`
 `);
 }
+function searchForDisplay(result) {
+  return {
+    ...result,
+    results: result.results.map((hit) => {
+      const passage = hit.selectedPassage;
+      if (passage?.status !== "selected")
+        return hit;
+      const texts = [passage.text, ...passage.headings.map(({ text }) => text)];
+      if (texts.every((text) => sanitizeTerminalText(redactSensitiveText(text)) === text.replaceAll(`\r
+`, `
+`).replaceAll("\t", "    ")))
+        return hit;
+      return { ...hit, selectedPassage: { status: "unavailable", reason: "display-sanitized" } };
+    })
+  };
+}
 function renderKnowledgeBaseSearch(result) {
   const lines = [
     `${result.mode[0]?.toLocaleUpperCase("en-US") ?? ""}${result.mode.slice(1)} results for \u201C${safe(result.query)}\u201D (${result.results.length})${result.partial ? " [partial]" : ""}`
@@ -6315,8 +6360,21 @@ function renderKnowledgeBaseSearch(result) {
     const location = `${safe(hit.path)}${hit.line === undefined ? "" : `:${hit.line}`}`;
     const evidence = hit.evidence.map((item) => `${item.kind}#${searchEvidenceRank(item)}`).join(", ");
     lines.push(`  ${hit.rank}. ${hit.score.toFixed(3)}  ${location} \u2014 ${safe(hit.title)} [${safe(evidence)}]`);
-    if (hit.snippet !== "")
-      lines.push(`    ${safe(hit.snippet)}`);
+    const passage = hit.selectedPassage;
+    if (passage?.status === "selected") {
+      lines.push(`    Selected passage: ${safe(hit.path)}:${passage.startLine}-${passage.endLine}` + (passage.clippedStart || passage.clippedEnd ? " (clipped excerpt)" : ""));
+      for (const heading of passage.headings) {
+        lines.push(`    Section: ${safe(heading.text)}${heading.truncated ? " (clipped)" : ""}`);
+      }
+      for (const line of passage.text.split(/\r?\n/u))
+        lines.push(`    ${safe(line)}`);
+    } else {
+      if (hit.snippet !== "")
+        lines.push(`    ${safe(hit.snippet)}`);
+      if (passage !== undefined) {
+        lines.push(`    Selected passage: ${passage.status} (${safe(passage.reason)}); showing the search snippet.`);
+      }
+    }
   }
   if ((result.graph?.related.length ?? 0) > 0) {
     lines.push(`  Related graph context: ${result.graph?.related.length ?? 0}`);
@@ -6369,6 +6427,7 @@ async function runSemantic(command, output, dependencies) {
       ...command.limit === undefined ? {} : { limit: command.limit },
       ...command.candidateLimit === undefined ? {} : { candidateLimit: command.candidateLimit },
       ...command.minScore === undefined ? {} : { minScore: command.minScore },
+      ...command.selectedPassage === undefined ? {} : { selectedPassage: command.selectedPassage },
       ...command.rerank === undefined ? {} : {
         rerank: {
           engine: command.rerank,
@@ -6376,7 +6435,8 @@ async function runSemantic(command, output, dependencies) {
         }
       }
     });
-    output.stdout(command.json ? terminalSafeJson(result) : sanitizeTerminalText(renderKnowledgeBaseSearch(result)));
+    const display = searchForDisplay(result);
+    output.stdout(command.json ? terminalSafeJson(display) : sanitizeTerminalText(renderKnowledgeBaseSearch(display)));
     if (withoutIndex && person) {
       output.stderr("Searched without an index, so only exact words matched. " + `For meaning-based search, run wordcell index --root ${safe(shellWord(command.root))} ` + `(downloads about 300 MB once).
 `);