@gmickel/gno 1.6.0 → 1.7.1

package/README.md

@@ -99,7 +99,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 - **Retrieval Quality Upgrade**: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
 - **Code Embedding Benchmarks**: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models
 - **Default Embed Model**: built-in presets now use `Qwen3-Embedding-0.6B-GGUF` after it beat `bge-m3` on both code and multilingual prose benchmark lanes
-- **Regression Fixes**: tightened phrase/negation/hyphen/underscore BM25 behavior, cleaned non-TTY hyperlink output, improved `gno doctor` chunking visibility, and fixed the embedding autoresearch harness
+- **Regression Fixes**: tightened phrase/negation/hyphen/underscore BM25 behavior, cleaned non-TTY hyperlink output, improved `gno doctor` chunking and embedding fingerprint visibility, and fixed the embedding autoresearch harness
 
 ### Upgrading Existing Collections
 

package/assets/skill/SKILL.md

@@ -136,7 +136,7 @@ gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-ge
 When using GNO through MCP, prefer this retrieval order:
 
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.
-2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, and often `line`; it also adds bounded one-hop graph neighbors from top seeds when graph data exists.
+2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, and often `line`; pass `graph: true` only when linked context is worth the extra latency.
 3. Use graph/link expansion for relationship context: `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer `explicit` graph edges over `inferred`, `ambiguous`, or `similarity` edges when confidence matters.
 4. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
 

package/assets/skill/cli-reference.md

@@ -154,7 +154,7 @@ gno query <query> [options]
 
 | Flag         | Time  | Description                    |
 | ------------ | ----- | ------------------------------ |
-| `--fast`     | ~0.7s | Skip expansion, graph, rerank  |
+| `--fast`     | ~0.7s | Skip expansion and rerank      |
 | (default)    | ~2-3s | Skip expansion, with reranking |
 | `--thorough` | ~5-8s | Full pipeline with expansion   |
 
@@ -164,7 +164,8 @@ Additional options:
 | ------------- | --------------------------------- |
 | `--no-expand` | Disable query expansion           |
 | `--no-rerank` | Disable reranking                 |
-| `--no-graph`  | Disable graph-neighbor candidates |
+| `--graph`     | Enable graph-neighbor candidates  |
+| `--no-graph`  | Compatibility no-op by default    |
 | `--explain`   | Print retrieval details to stderr |
 
 ### gno ask

package/assets/skill/mcp-reference.md

@@ -56,9 +56,8 @@ gno mcp status
 ## Retrieval Order
 
 For normal questions, start with `gno_query`, then read targeted snippets with
-`gno_get` or batch refs with `gno_multi_get`. `gno_query` already does bounded
-one-hop graph expansion from top seeds; pass `noGraph: true` only when comparing
-pure BM25/vector retrieval. Check `gno_status` first when freshness or
+`gno_get` or batch refs with `gno_multi_get`. Pass `graph: true` only when
+linked context is worth the extra latency. Check `gno_status` first when freshness or
 embeddings may be stale.
 
 Use graph tools for relationship context: `gno_graph` for corpus report/stats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -60,6 +60,7 @@
     "test:web": "bun test test/serve/public --timeout 30000",
     "test:e2e": "bun scripts/web-ui-smoke.ts",
     "test:e2e:install": "bunx playwright install chromium",
+    "test:package": "bun scripts/package-smoke.ts",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
     "test:coverage:html": "bun test --coverage --html",
@@ -130,7 +131,7 @@
     "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",
-    "prerelease": "bun run lint:check && bun test",
+    "prerelease": "bun run lint:check && bun test && bun run docs:verify && bun run test:package",
     "release:dry-run": "gh workflow run publish.yml -f publish=false",
     "release:trigger": "gh workflow run publish.yml -f publish=true",
     "prepare": "lefthook install"

package/src/cli/commands/doctor.ts

@@ -17,13 +17,15 @@ import { getConfigPaths, isInitialized, loadConfig } from "../../config";
 import { getCodeChunkingStatus } from "../../ingestion/chunker";
 import { ModelCache } from "../../llm/cache";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
-import { getActivePreset } from "../../llm/registry";
+import { getActivePreset, resolveModelUri } from "../../llm/registry";
+import { SqliteAdapter } from "../../store/sqlite/adapter";
 import { loadFts5Snowball } from "../../store/sqlite/fts5-snowball";
 import {
   getCustomSqlitePath,
   getExtensionLoadingMode,
   getLoadAttempts,
 } from "../../store/sqlite/setup";
+import { getStoredEmbeddingFingerprint } from "../../store/vector/freshness";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -37,6 +39,25 @@ export interface DoctorCheck {
   message: string;
   /** Additional diagnostic details (shown in verbose/json output) */
   details?: string[];
+  /** Embedding fingerprint diagnostics for machine consumers */
+  embeddingFingerprint?: EmbeddingFingerprintHealth;
+}
+
+export interface EmbeddingFingerprintGroup {
+  model: string;
+  fingerprint: string;
+  count: number;
+  current: boolean;
+  legacy: boolean;
+}
+
+export interface EmbeddingFingerprintHealth {
+  model: string;
+  currentFingerprint: string;
+  pendingChunks: number;
+  legacyChunks: number;
+  mixedGroups: number;
+  groups: EmbeddingFingerprintGroup[];
 }
 
 export interface DoctorOptions {
@@ -137,6 +158,160 @@ function checkCodeChunking(): DoctorCheck {
   };
 }
 
+const FINGERPRINT_DISPLAY_LENGTH = 12;
+
+function shortFingerprint(fingerprint: string): string {
+  return fingerprint.slice(0, FINGERPRINT_DISPLAY_LENGTH);
+}
+
+function describeFingerprintGroup(group: EmbeddingFingerprintGroup): string {
+  if (group.current) {
+    return "current";
+  }
+  if (group.legacy) {
+    return "legacy";
+  }
+  return "stale";
+}
+
+async function checkEmbeddingFingerprints(
+  config: Config
+): Promise<DoctorCheck> {
+  const dbPath = getIndexDbPath();
+  try {
+    await stat(dbPath);
+  } catch {
+    return {
+      name: "embedding-fingerprint",
+      status: "warn",
+      message: "Database not found. Run: gno init",
+    };
+  }
+
+  const store = new SqliteAdapter();
+  const paths = getConfigPaths();
+  store.setConfigPath(paths.configFile);
+
+  const openResult = await store.open(dbPath, config.ftsTokenizer);
+  if (!openResult.ok) {
+    return {
+      name: "embedding-fingerprint",
+      status: "warn",
+      message: `Fingerprint health unavailable: ${openResult.error.message}`,
+      details: ["Run: gno doctor --json", "Then run: gno embed"],
+    };
+  }
+
+  try {
+    const db = store.getRawDb();
+    const model = resolveModelUri(config, "embed");
+    const currentFingerprint = getStoredEmbeddingFingerprint(db, model);
+    const statusResult = await store.getStatus({ embedModel: model });
+    if (!statusResult.ok) {
+      return {
+        name: "embedding-fingerprint",
+        status: "warn",
+        message: `Fingerprint health unavailable: ${statusResult.error.message}`,
+        details: ["Run: gno embed"],
+      };
+    }
+
+    const legacyChunks =
+      db
+        .query<{ count: number }, [string]>(
+          `
+          SELECT COUNT(*) as count
+          FROM content_vectors v
+          JOIN content_chunks c
+            ON c.mirror_hash = v.mirror_hash
+           AND c.seq = v.seq
+          WHERE v.model = ?
+            AND v.embed_fingerprint = ''
+            AND EXISTS (
+              SELECT 1 FROM documents d
+              WHERE d.mirror_hash = c.mirror_hash
+                AND d.active = 1
+            )
+        `
+        )
+        .get(model)?.count ?? 0;
+
+    const groups = db
+      .query<{ model: string; fingerprint: string; count: number }, []>(
+        `
+        SELECT
+          v.model as model,
+          v.embed_fingerprint as fingerprint,
+          COUNT(*) as count
+        FROM content_vectors v
+        JOIN content_chunks c
+          ON c.mirror_hash = v.mirror_hash
+         AND c.seq = v.seq
+        WHERE EXISTS (
+          SELECT 1 FROM documents d
+          WHERE d.mirror_hash = c.mirror_hash
+            AND d.active = 1
+        )
+        GROUP BY v.model, v.embed_fingerprint
+        ORDER BY count DESC, v.model ASC, v.embed_fingerprint ASC
+      `
+      )
+      .all()
+      .map((group) => ({
+        model: group.model,
+        fingerprint: group.fingerprint,
+        count: group.count,
+        current:
+          group.model === model && group.fingerprint === currentFingerprint,
+        legacy: group.fingerprint === "",
+      }));
+
+    const mixedGroups = groups.length;
+    const pendingChunks = statusResult.value.embeddingBacklog;
+    const hasWarnings =
+      pendingChunks > 0 || legacyChunks > 0 || mixedGroups > 1;
+
+    const health: EmbeddingFingerprintHealth = {
+      model,
+      currentFingerprint,
+      pendingChunks,
+      legacyChunks,
+      mixedGroups,
+      groups,
+    };
+
+    const message =
+      `current ${shortFingerprint(currentFingerprint)}, ` +
+      `${pendingChunks} pending/stale, ${legacyChunks} legacy, ` +
+      `${mixedGroups} group${mixedGroups === 1 ? "" : "s"}`;
+    const details: string[] = [];
+
+    if (hasWarnings) {
+      details.push("Run: gno embed");
+      details.push("If vectors still look stale, run: gno embed --force");
+      for (const group of groups) {
+        const label = describeFingerprintGroup(group);
+        const fingerprint = group.legacy
+          ? "(empty)"
+          : shortFingerprint(group.fingerprint);
+        details.push(
+          `${label}: ${group.count} chunks model=${group.model} fingerprint=${fingerprint}`
+        );
+      }
+    }
+
+    return {
+      name: "embedding-fingerprint",
+      status: hasWarnings ? "warn" : "ok",
+      message,
+      details: details.length > 0 ? details : undefined,
+      embeddingFingerprint: health,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
 async function checkNodeLlamaCpp(config: Config): Promise<DoctorCheck> {
   const llm = new LlmAdapter(config);
   try {
@@ -341,6 +516,9 @@ export async function doctor(
   // Code chunking capability
   checks.push(checkCodeChunking());
 
+  // Embedding fingerprint freshness
+  checks.push(await checkEmbeddingFingerprints(config));
+
   // Determine overall health
   const hasErrors = checks.some((c) => c.status === "error");