@gmickel/gno 1.36.0 → 1.37.0

package/README.md

@@ -105,7 +105,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 **Start here** · [Quick Start](#quick-start) · [Installation](#installation) · [Agent Integration](#agent-integration) · [Search Modes](#search-modes)
 
-**Surfaces** · [Web UI](#web-ui) · [REST API](#rest-api) · [SDK](#sdk) · [Daemon Mode](#daemon-mode) · [Publish to gno.sh](#publish-to-gnosh)
+**Surfaces** · [Web UI](#web-ui) · [Omarchy Plugin](#omarchy-plugin) · [REST API](#rest-api) · [SDK](#sdk) · [Daemon Mode](#daemon-mode) · [Publish to gno.sh](#publish-to-gnosh)
 
 **Under the hood** · [How It Works](#how-it-works) · [Features](#features) · [Local Models](#local-models) · [Fine-Tuned Models](#fine-tuned-models) · [Architecture](#architecture) · [Development](#development)
 
@@ -117,12 +117,25 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.35.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.36.1**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **Cheap peek snapshot**: `gno peek --json` and MCP `gno_peek` return a
+  model-free `peek@1.0` snapshot (document/collection counts, embedding backlog,
+  10 recent docs with `docid` and `absPath`, pid-file serve detection).
+  Uninitialized reports `initialized:false` with pinned nulls and exit 0. Any
+  subquery failure is an atomic `RUNTIME` envelope (exit 2). `serve.running` is
+  true only for `gno serve --detach`. JSON search hits pin
+  `results[].source.absPath`. Open a document in the Web UI with
+  `{serveUrl}/doc?uri=<encodeURIComponent(uri)>`.
+- **Prose-first snippets**: `gno search`, `gno vsearch`, and `gno query` skip
+  leading YAML frontmatter and prefer document prose. A frontmatter-dominated
+  FTS window falls back to stripped chunk prose. `--full` and `--line-numbers`
+  still emit raw source. `line` and `snippetRange.startLine` follow the trimmed
+  display range.
 - **Trustworthy local context compiler**: deterministic Context Capsules replace
   repeated agent `query → get → multi-get` orchestration with one bounded,
   citation-complete evidence handoff. The promoted benchmark retained 100%
@@ -544,7 +557,10 @@ Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
 # Search one collection
 gno search "PostgreSQL connection pool" --collection work-docs
 
-# Export retrieval results for an agent
+# Cheap index snapshot for a status bar or desktop widget
+gno peek --json
+
+# Export retrieval results for an agent (`source.absPath` on file-backed hits)
 gno query "authentication flow" --json -n 10
 gno query "deployment rollback" --all --files --min-score 0.4
 
@@ -645,30 +661,31 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 25 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 33 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 15 opt-in mutation tools, for 40 total.
-
-| Tool                 | Description                           |
-| :------------------- | :------------------------------------ |
-| `gno_search`         | BM25 keyword search                   |
-| `gno_vsearch`        | Vector semantic search                |
-| `gno_query`          | Hybrid search (recommended)           |
-| `gno_context`        | Budgeted exact evidence Capsule       |
-| `gno_context_verify` | Verify saved Capsule provenance       |
-| `gno_ask`            | Opt-in closed-Capsule verified answer |
-| `gno_get`            | Retrieve document by ID               |
-| `gno_multi_get`      | Batch document retrieval              |
-| `gno_links`          | Get outgoing links from document      |
-| `gno_backlinks`      | Get documents linking TO document     |
-| `gno_similar`        | Find semantically similar documents   |
-| `gno_graph`          | Get knowledge graph (nodes and edges) |
-| `gno_status`         | Index health check                    |
-| `gno_trace_list`     | List private local retrieval receipts |
-| `gno_trace_show`     | Inspect one bounded trace receipt     |
-| `gno_changes`        | Read retained metadata-only changes   |
-| `gno_diff`           | Read one structural document delta    |
-| `gno_impact`         | Trace bounded dependency impact       |
+adds 18 opt-in mutation tools, for 51 total.
+
+| Tool                 | Description                                     |
+| :------------------- | :---------------------------------------------- |
+| `gno_search`         | BM25 keyword search                             |
+| `gno_vsearch`        | Vector semantic search                          |
+| `gno_query`          | Hybrid search (recommended)                     |
+| `gno_context`        | Budgeted exact evidence Capsule                 |
+| `gno_context_verify` | Verify saved Capsule provenance                 |
+| `gno_ask`            | Opt-in closed-Capsule verified answer           |
+| `gno_get`            | Retrieve document by ID                         |
+| `gno_multi_get`      | Batch document retrieval                        |
+| `gno_links`          | Get outgoing links from document                |
+| `gno_backlinks`      | Get documents linking TO document               |
+| `gno_similar`        | Find semantically similar documents             |
+| `gno_graph`          | Get knowledge graph (nodes and edges)           |
+| `gno_peek`           | Cheap `peek@1.0` counts, backlog, recent, serve |
+| `gno_status`         | Index health check                              |
+| `gno_trace_list`     | List private local retrieval receipts           |
+| `gno_trace_show`     | Inspect one bounded trace receipt               |
+| `gno_changes`        | Read retained metadata-only changes             |
+| `gno_diff`           | Read one structural document delta              |
+| `gno_impact`         | Trace bounded dependency impact                 |
 
 **Design**: Default MCP mode is read-only: retrieval, opt-in verified synthesis,
 graph, status, and job inspection. Raw retrieval tools leave synthesis to your
@@ -792,6 +809,18 @@ gno.sh.
 
 ---
 
+## Omarchy Plugin
+
+On [Omarchy](https://omarchy.org/), [**GNO Recall**](https://github.com/gmickel/omarchy-gno-recall) puts the index in your bar: a quiet health widget, an anchored panel with counts and recent documents, and a keyboard-first overlay (Super+R) for search, deep search, collection browsing, and opening documents.
+
+```bash
+omarchy plugin add https://github.com/gmickel/omarchy-gno-recall --enable
+```
+
+Requires gno >= 1.36.0 on `PATH`.
+
+---
+
 ## Publish to gno.sh
 
 GNO is local-first, but sometimes you want a URL to send someone. [**gno.sh**](https://gno.sh/publish) is the hosted reader on top of GNO — a polished, reading-first page for a single note or a whole collection, without mounting your vault or syncing anything.

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

@@ -0,0 +1 @@
+497d8e90a34b7472eac55da861c3049b7453a33d9fdbd0a27e49f2ce36ccde9b  gno-browser-clipper-v1.37.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.36.0"
+  "version": "1.37.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -65,6 +65,7 @@
     "test": "bun test",
     "test:web": "bun test test/serve/public --timeout 30000",
     "test:e2e": "bun scripts/web-ui-smoke.ts",
+    "bench:webui-first-page": "bun scripts/webui-first-page-load.ts",
     "test:e2e:clipper": "bun test test/clipper/e2e.test.ts --timeout 240000",
     "test:e2e:pdf": "bun scripts/pdf-viewer-smoke.ts",
     "smoke:pdf-viewer": "bun scripts/pdf-viewer-smoke.ts",
@@ -144,8 +145,9 @@
     "website:sync-assets": "bun scripts/sync-assets.ts",
     "sync:agents": "scripts/sync-agents.sh",
     "build:css": "tailwindcss -i src/serve/public/globals.css -o src/serve/public/globals.built.css --minify",
+    "build:spa": "bun scripts/build-spa-production.ts",
     "serve": "bun src/index.ts serve",
-    "serve:dev": "NODE_ENV=development bun --hot src/index.ts serve",
+    "serve:dev": "bun --hot src/index.ts serve --dev",
     "version:patch": "npm version patch --no-git-tag-version",
     "version:minor": "npm version minor --no-git-tag-version",
     "version:major": "npm version major --no-git-tag-version",

package/spec/cli.md

@@ -3335,16 +3335,26 @@ API share the listener; use `gno daemon` for authenticated non-loopback MCP.
 **Synopsis:**
 
 ```bash
-gno serve [--port <num>] [gateway-options] [--detach] [--pid-file <path>] [--log-file <path>]
+gno serve [--port <num>] [--dev] [gateway-options] [--detach] [--pid-file <path>] [--log-file <path>]
 gno serve --status [--json]
 gno serve --stop
 ```
 
+Default `gno serve` (no `--dev`) is the production WebUI bundle, even when
+`NODE_ENV` is unset. Production serve loads the committed SPA snapshot
+(`assets/spa-production.json.gz`) so first listen does not wait on `Bun.build`.
+Refresh the snapshot with `bun scripts/build-spa-production.ts`. `--dev` is the
+operator switch for the development bundle and HMR (`serve:dev` / `bun --hot`
+remain the hot-reload path). `--dev` does not apply to `--status` or `--stop`
+(those paths do not boot the UI). A detached child inherits the same
+production default unless the parent was started with `--dev`.
+
 **Options:**
 
 | Option                 | Type    | Default                  | Description                                                      |
 | ---------------------- | ------- | ------------------------ | ---------------------------------------------------------------- |
 | `-p, --port`           | number  | 3000                     | Port to listen on                                                |
+| `--dev`                | boolean | false                    | Serve the development bundle with HMR (default is production)    |
 | `--detach`             | boolean | false                    | Self-spawn a detached child; parent prints `{pid,url}` and exits |
 | `--pid-file <path>`    | string  | `{data}/serve.pid`       | Override pid-file location (JSON metadata, absolute path)        |
 | `--log-file <path>`    | string  | `{data}/serve.log`       | Override log-file location (append mode)                         |
@@ -3423,6 +3433,7 @@ is blocked.
 ```bash
 gno serve
 gno serve --port 8080
+gno serve --dev
 
 # Backgrounding
 gno serve --detach

package/src/cli/program.ts

@@ -4164,12 +4164,29 @@ function wireServeCommand(program: Command): void {
       "internal detached-child marker"
     ).hideHelp()
   );
+  serveCmd.addOption(
+    new Option(
+      "--dev",
+      "serve the development bundle with HMR (default: production)"
+    )
+  );
 
   serveCmd.action(async (cmdOpts: Record<string, unknown>, cmd: Command) => {
     await handleServeAction(cmdOpts, cmd);
   });
 }
 
+/** CLI serve bundle mode. Default `gno serve` is production unless `--dev`. */
+export function resolveServeNodeEnv(
+  dev: boolean
+): "development" | "production" {
+  return dev ? "development" : "production";
+}
+
+function applyServeBundleEnv(dev: boolean): void {
+  process.env.NODE_ENV = resolveServeNodeEnv(dev);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Serve lifecycle branching (detach / status / stop / detached-child / fg)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -4238,6 +4255,9 @@ async function handleServeAction(
     return;
   }
 
+  const dev = cmdOpts.dev === true;
+  applyServeBundleEnv(dev);
+
   if (cmdOpts.detach) {
     const port = parsePositiveInt("port", cmdOpts.port);
     await runServeDetach({
@@ -4245,6 +4265,7 @@ async function handleServeAction(
       paths,
       spawnDetached,
       argv: resolveCliArgv(cmd),
+      nodeEnv: resolveServeNodeEnv(dev),
     });
     return;
   }
@@ -4423,6 +4444,7 @@ interface ServeDetachDeps {
    * can't taint each other's child argv.
    */
   argv: string[];
+  nodeEnv: "development" | "production";
 }
 
 async function runServeDetach(deps: ServeDetachDeps): Promise<void> {
@@ -4432,6 +4454,7 @@ async function runServeDetach(deps: ServeDetachDeps): Promise<void> {
   const result = await deps.spawnDetached({
     kind: "serve",
     argv: childArgv,
+    env: { NODE_ENV: deps.nodeEnv },
     pidFile: deps.paths.pidFile,
     logFile: deps.paths.logFile,
     port: deps.port,

package/src/core/context-evidence.ts

@@ -413,13 +413,19 @@ export const materializeContextEvidenceCandidates = async (
     const content = contentByHash.get(document.mirrorHash);
     const chunk = getChunk(document.mirrorHash, metadata.seq);
     const chunkKey = `${document.mirrorHash}:${metadata.seq}`;
+    // Display snippets may omit leading YAML frontmatter, so startLine can sit
+    // after the stored chunk start. endLine must still identify the same chunk.
+    const displayRangeWithinChunk =
+      chunk !== undefined &&
+      snippetRange.endLine === chunk.endLine &&
+      snippetRange.startLine >= chunk.startLine &&
+      snippetRange.startLine <= chunk.endLine;
     if (
       !content ||
       metadata.mirrorHash !== document.mirrorHash ||
       !chunk ||
       chunk.mirrorHash !== document.mirrorHash ||
-      snippetRange.startLine !== chunk.startLine ||
-      snippetRange.endLine !== chunk.endLine
+      !displayRangeWithinChunk
     ) {
       throw new ContextEvidenceError(
         "chunk_coordinate_mismatch",

package/src/pipeline/hybrid.ts

@@ -58,6 +58,7 @@ import {
 } from "./query-modes";
 import { rerankCandidates } from "./rerank";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   isWithinTemporalRange,
   resolveRecencyTimestamp,
@@ -1003,6 +1004,7 @@ export async function searchHybrid(
           ) ?? chunk);
 
     let snippet = snippetChunk.text;
+    let snippetStartLine = snippetChunk.startLine;
     let snippetRange: { startLine: number; endLine: number } | undefined = {
       startLine: snippetChunk.startLine,
       endLine: snippetChunk.endLine,
@@ -1021,6 +1023,18 @@ export async function searchHybrid(
         snippetRange = undefined; // Full content has no range
       }
       // Fallback to chunk text if content unavailable
+    } else {
+      const cleanedSnippet = cleanDisplaySnippet(
+        snippetChunk.text,
+        snippetChunk.text
+      );
+      snippet = cleanedSnippet.text;
+      snippetStartLine =
+        snippetChunk.startLine + cleanedSnippet.startLineOffset;
+      snippetRange = {
+        startLine: snippetStartLine,
+        endLine: snippetChunk.endLine,
+      };
     }
 
     for (const doc of candidateDocs) {
@@ -1050,7 +1064,7 @@ export async function searchHybrid(
         title: doc.title ?? undefined,
         contentType: doc.contentType ?? undefined,
         categories: doc.categories ?? undefined,
-        line: snippetChunk.startLine,
+        line: snippetStartLine,
         snippet,
         snippetLanguage: chunk.language ?? undefined,
         snippetRange,

package/src/pipeline/search.ts

@@ -30,6 +30,7 @@ import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
   resolveTemporalRange,
@@ -107,6 +108,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
   // Determine snippet content and range
   let snippet: string;
   let snippetRange: { startLine: number; endLine: number } | undefined;
+  let line = chunk?.startLine;
 
   if (options?.full && fullContent) {
     // --full: use full content, no range (full doc)
@@ -117,11 +119,18 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     snippet = chunk.text;
     snippetRange = { startLine: chunk.startLine, endLine: chunk.endLine };
   } else {
-    // Default: use FTS snippet or chunk text
-    snippet = fts.snippet ?? chunk?.text ?? "";
-    snippetRange = chunk
-      ? { startLine: chunk.startLine, endLine: chunk.endLine }
-      : undefined;
+    // Default: FTS snippet or chunk text, with leading frontmatter stripped
+    const cleaned = cleanDisplaySnippet(
+      fts.snippet ?? chunk?.text ?? "",
+      chunk?.text
+    );
+    snippet = cleaned.text;
+    if (chunk) {
+      line = chunk.startLine + cleaned.startLineOffset;
+      snippetRange = { startLine: line, endLine: chunk.endLine };
+    } else {
+      snippetRange = undefined;
+    }
   }
 
   const result: SearchResult = {
@@ -131,7 +140,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     title: fts.title,
     contentType: fts.contentType,
     categories: fts.categories,
-    line: chunk?.startLine,
+    line,
     snippet,
     snippetLanguage: chunk?.language ?? undefined,
     snippetRange,

package/src/pipeline/snippet.ts

@@ -0,0 +1,203 @@
+/**
+ * Display-layer snippet cleaning for search/query results.
+ * Strips leading YAML frontmatter so snippets prefer prose. Does not change
+ * indexed text, `--full` content, or `--line-numbers` raw chunks.
+ *
+ * @module src/pipeline/snippet
+ */
+
+import { stripFrontmatter } from "../ingestion/frontmatter";
+
+/** FTS5 highlight markers from snippet(documents_fts, ..., '<mark>', '</mark>', '...', 32). */
+const MARK_TAG_REGEX = /<\/?mark>/g;
+
+/** Leading blank lines after a closed frontmatter fence. */
+const LEADING_BLANK_LINES_REGEX = /^(?:[ \t]*\r?\n)+/;
+
+/** YAML mapping line (`key: value` or `key:`). */
+const YAML_MAPPING_LINE_REGEX = /^[\w./-]+\s*:/;
+
+/** YAML sequence item. */
+const YAML_SEQUENCE_LINE_REGEX = /^- /;
+
+export interface DisplaySnippet {
+  text: string;
+  /**
+   * Lines to add to the chunk's startLine when the emitted text is derived
+   * from stripped chunk prose (not a kept FTS window).
+   */
+  startLineOffset: number;
+  /** True when a frontmatter-dominated FTS snippet was replaced by chunk prose. */
+  usedChunkFallback: boolean;
+}
+
+/**
+ * Clean a default-path snippet: strip a leading closed YAML fence, or replace
+ * an FTS window that is only frontmatter with stripped chunk prose.
+ * Never returns an empty string when the original text had content.
+ */
+export function cleanDisplaySnippet(
+  snippet: string,
+  chunkText?: string
+): DisplaySnippet {
+  const strippedSnippet = stripLeadingFrontmatterBlock(snippet);
+  if (strippedSnippet.didStrip) {
+    return {
+      text: strippedSnippet.text,
+      startLineOffset: strippedSnippet.lineCount,
+      usedChunkFallback: false,
+    };
+  }
+
+  const afterEmbeddedFence = proseAfterEmbeddedFrontmatterFence(snippet);
+  if (afterEmbeddedFence !== undefined) {
+    const cleanedChunk =
+      chunkText === undefined
+        ? undefined
+        : stripLeadingFrontmatterBlock(chunkText);
+    return {
+      text: afterEmbeddedFence,
+      startLineOffset: cleanedChunk?.didStrip ? cleanedChunk.lineCount : 0,
+      usedChunkFallback: false,
+    };
+  }
+
+  const canFallback =
+    chunkText !== undefined &&
+    chunkText !== snippet &&
+    isFrontmatterDominatedSnippet(snippet);
+  if (canFallback) {
+    const cleanedChunk = stripLeadingFrontmatterBlock(chunkText);
+    if (cleanedChunk.text.length > 0) {
+      return {
+        text: cleanedChunk.text,
+        startLineOffset: cleanedChunk.didStrip ? cleanedChunk.lineCount : 0,
+        usedChunkFallback: true,
+      };
+    }
+  }
+
+  return {
+    text: snippet,
+    startLineOffset: 0,
+    usedChunkFallback: false,
+  };
+}
+
+/** True for FTS-style snippets that are only (or start as) YAML frontmatter. */
+export function isFrontmatterDominatedSnippet(text: string): boolean {
+  const unmarked = text.replace(MARK_TAG_REGEX, "");
+  const trimmed = unmarked.trimStart();
+  const withoutLeadingEllipsis = trimmed.startsWith("...")
+    ? trimmed.slice(3).trimStart()
+    : trimmed;
+  if (withoutLeadingEllipsis.startsWith("---")) {
+    return true;
+  }
+
+  const contentLines = unmarked.split(/\r?\n/).filter((line) => {
+    const trimmedLine = line.trim();
+    return trimmedLine.length > 0 && trimmedLine !== "...";
+  });
+  if (contentLines.length === 0) {
+    return false;
+  }
+  if (contentLines.every(isYamlFrontmatterLine)) {
+    return true;
+  }
+  return proseAfterEmbeddedFrontmatterFence(text) !== undefined;
+}
+
+/**
+ * FTS windows often straddle the closing fence (`...yaml\n---\n# Heading`).
+ * Keep the prose after that fence when the prefix looks like YAML.
+ */
+function proseAfterEmbeddedFrontmatterFence(text: string): string | undefined {
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) {
+      continue;
+    }
+    if (line.replace(MARK_TAG_REGEX, "").trim() !== "---") {
+      continue;
+    }
+    const prefixLines = lines.slice(0, i);
+    if (!prefixLooksLikeFrontmatter(prefixLines)) {
+      continue;
+    }
+    const after = lines
+      .slice(i + 1)
+      .join("\n")
+      .replace(LEADING_BLANK_LINES_REGEX, "");
+    if (after.trim().length === 0) {
+      continue;
+    }
+    return after;
+  }
+  return undefined;
+}
+
+function prefixLooksLikeFrontmatter(lines: string[]): boolean {
+  const content = lines.filter((line) => {
+    const trimmed = line.replace(MARK_TAG_REGEX, "").trim();
+    return trimmed.length > 0 && trimmed !== "...";
+  });
+  if (content.length === 0) {
+    return true;
+  }
+  return content.every((line, index) => {
+    const trimmed = line.replace(MARK_TAG_REGEX, "").trim();
+    if (index === 0 && trimmed.startsWith("...")) {
+      return true;
+    }
+    return isYamlFrontmatterLine(trimmed);
+  });
+}
+
+function stripLeadingFrontmatterBlock(text: string): {
+  text: string;
+  didStrip: boolean;
+  lineCount: number;
+} {
+  const afterFence = stripFrontmatter(text);
+  if (afterFence === text) {
+    return { text, didStrip: false, lineCount: 0 };
+  }
+
+  const withoutBlanks = afterFence.replace(LEADING_BLANK_LINES_REGEX, "");
+  if (withoutBlanks.trim().length === 0) {
+    return { text, didStrip: false, lineCount: 0 };
+  }
+
+  const prefix = text.slice(0, text.length - withoutBlanks.length);
+  return {
+    text: withoutBlanks,
+    didStrip: true,
+    lineCount: countConsumedLines(prefix),
+  };
+}
+
+function isYamlFrontmatterLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (trimmed === "---") {
+    return true;
+  }
+  if (YAML_SEQUENCE_LINE_REGEX.test(trimmed)) {
+    return true;
+  }
+  return YAML_MAPPING_LINE_REGEX.test(trimmed);
+}
+
+function countConsumedLines(prefix: string): number {
+  if (prefix.length === 0) {
+    return 0;
+  }
+  let newlineCount = 0;
+  for (const char of prefix) {
+    if (char === "\n") {
+      newlineCount += 1;
+    }
+  }
+  return prefix.endsWith("\n") ? newlineCount : newlineCount + 1;
+}

package/src/pipeline/vsearch.ts

@@ -28,6 +28,7 @@ import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
   isWithinTemporalRange,
@@ -236,6 +237,8 @@ export async function searchVectorWithEmbedding(
         continue;
       }
 
+      const cleanedSnippet = cleanDisplaySnippet(chunk.text, chunk.text);
+      const snippetStartLine = chunk.startLine + cleanedSnippet.startLineOffset;
       const scoredResult = applyContentTypeBoost(
         {
           docid: doc.docid,
@@ -244,11 +247,11 @@ export async function searchVectorWithEmbedding(
           title: doc.title ?? undefined,
           contentType: doc.contentType ?? undefined,
           categories: doc.categories ?? undefined,
-          line: chunk.startLine,
-          snippet: chunk.text,
+          line: snippetStartLine,
+          snippet: cleanedSnippet.text,
           snippetLanguage: chunk.language ?? undefined,
           snippetRange: {
-            startLine: chunk.startLine,
+            startLine: snippetStartLine,
             endLine: chunk.endLine,
           },
           source: {
@@ -338,6 +341,12 @@ export async function searchVectorWithEmbedding(
 
       const collectionPath = collectionPaths.get(doc.collection);
       const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+      const cleanedChunk = fullContent
+        ? undefined
+        : cleanDisplaySnippet(chunk.text, chunk.text);
+      const snippetStartLine = cleanedChunk
+        ? chunk.startLine + cleanedChunk.startLineOffset
+        : chunk.startLine;
 
       const result = applyContentTypeBoost(
         {
@@ -347,13 +356,13 @@ export async function searchVectorWithEmbedding(
           title: doc.title ?? undefined,
           contentType: doc.contentType ?? undefined,
           categories: doc.categories ?? undefined,
-          line: chunk.startLine,
-          snippet: fullContent ?? chunk.text,
+          line: snippetStartLine,
+          snippet: fullContent ?? cleanedChunk?.text ?? chunk.text,
           snippetLanguage: chunk.language ?? undefined,
           // --full: no snippetRange (full doc content)
           snippetRange: fullContent
             ? undefined
-            : { startLine: chunk.startLine, endLine: chunk.endLine },
+            : { startLine: snippetStartLine, endLine: chunk.endLine },
           source: {
             relPath: sourceRelPath,
             absPath: collectionPath