@gmickel/gno 1.2.0 → 1.3.0

package/README.md

@@ -778,7 +778,7 @@ graph TD
 
 ## Local Models
 
-Models auto-download on first use to `~/.cache/gno/models/`. For deterministic startup, set `GNO_NO_AUTO_DOWNLOAD=1` and use `gno models pull` explicitly. Alternatively, offload to a GPU server on your network using HTTP backends.
+Models auto-download on first use to `~/.cache/gno/models/`. GNO validates cached GGUF files before loading and removes intercepted HTML/non-GGUF cache entries with a clear recovery error. For deterministic startup, set `GNO_NO_AUTO_DOWNLOAD=1` and use `gno models pull` explicitly. Alternatively, offload to a GPU server on your network using HTTP backends.
 
 | Model                  | Purpose                               | Size         |
 | :--------------------- | :------------------------------------ | :----------- |

package/assets/skill/SKILL.md

@@ -167,6 +167,9 @@ gno graph -c notes --similar   # Include similarity edges
 --no-pager        Disable paging
 ```
 
+Non-default index search results may include `?index=<name>` on `gno://` URIs.
+Keep that query string when passing the URI to `gno get`.
+
 ## Important: Embedding After Changes
 
 If you edit/create files that should be searchable via vector search:

package/assets/skill/cli-reference.md

@@ -196,6 +196,7 @@ gno get <ref> [--from <line>] [-l <lines>] [--line-numbers] [--source]
 Ref formats:
 
 - `gno://collection/path` — Full URI
+- `gno://collection/path?index=name` — Full URI emitted from a non-default index
 - `collection/path` — Relative path
 - `#docid` — Document ID
 - `gno://docs/file.md:120` — With line number
@@ -378,6 +379,10 @@ Presets: `slim` (~1GB), `balanced` (~2GB), `quality` (~2.5GB)
 gno models pull [--all|--embed|--rerank|--gen] [--force]
 ```
 
+Cached/local model files are validated as GGUF before use. If the cache contains
+HTML or another non-GGUF response, rerun with `--force` after fixing network
+access.
+
 ### gno models clear
 
 ```bash

package/assets/skill/examples.md

@@ -90,6 +90,7 @@ gno ask "summarize project goals" --answer --max-answer-tokens 200
 ```bash
 # By URI
 gno get gno://work/readme.md
+gno get "gno://work/readme.md?index=research"
 
 # By document ID
 gno get "#a1b2c3d4"
@@ -204,6 +205,7 @@ gno models use quality
 
 # Download models
 gno models pull
+gno models pull --force
 ```
 
 ## Note Linking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/src/app/constants.ts

@@ -244,22 +244,39 @@ export function getModelsCachePath(dirs: ResolvedDirs = resolveDirs()): string {
 /**
  * Build a gno:// URI from collection and relative path.
  */
-export function buildUri(collection: string, relativePath: string): string {
+export interface BuildUriOptions {
+  indexName?: string;
+}
+
+export interface ParsedGnoUri {
+  collection: string;
+  path: string;
+  indexName?: string;
+}
+
+export function buildUri(
+  collection: string,
+  relativePath: string,
+  options: BuildUriOptions = {}
+): string {
   // URL-encode special chars in path segments but preserve slashes
   const encodedPath = relativePath
     .split("/")
     .map((segment) => encodeURIComponent(segment))
     .join("/");
-  return `${URI_PREFIX}${collection}/${encodedPath}`;
+  const uri = `${URI_PREFIX}${collection}/${encodedPath}`;
+  const indexName = options.indexName?.trim();
+  if (!indexName || indexName === DEFAULT_INDEX_NAME) {
+    return uri;
+  }
+  return `${uri}?index=${encodeURIComponent(indexName)}`;
 }
 
 /**
  * Parse a gno:// URI into collection and path components.
  * Returns null if not a valid gno:// URI or if decoding fails.
  */
-export function parseUri(
-  uri: string
-): { collection: string; path: string } | null {
+export function parseUri(uri: string): ParsedGnoUri | null {
   if (!uri.startsWith(URI_PREFIX)) {
     return null;
   }
@@ -269,20 +286,59 @@ export function parseUri(
 
   if (slashIndex === -1) {
     // gno://collection (no path)
-    return { collection: rest, path: "" };
+    const [collectionWithQuery, query = ""] = rest.split("?", 2);
+    const indexName = new URLSearchParams(query).get("index")?.trim();
+    return indexName
+      ? {
+          collection: collectionWithQuery ?? rest,
+          path: "",
+          indexName,
+        }
+      : { collection: collectionWithQuery ?? rest, path: "" };
   }
 
   const collection = rest.slice(0, slashIndex);
+  const pathAndQuery = rest.slice(slashIndex + 1);
+  const queryIndex = pathAndQuery.indexOf("?");
+  const encodedPath =
+    queryIndex === -1 ? pathAndQuery : pathAndQuery.slice(0, queryIndex);
+  const query = queryIndex === -1 ? "" : pathAndQuery.slice(queryIndex + 1);
 
   // decodeURIComponent throws on malformed percent-encoding
   try {
-    const path = decodeURIComponent(rest.slice(slashIndex + 1));
-    return { collection, path };
+    const path = decodeURIComponent(encodedPath);
+    const indexName = new URLSearchParams(query).get("index")?.trim();
+    return indexName ? { collection, path, indexName } : { collection, path };
   } catch {
     return null;
   }
 }
 
+/**
+ * Add output-only index metadata to a canonical gno:// URI.
+ */
+export function decorateUriForIndex(uri: string, indexName?: string): string {
+  const parsed = parseUri(uri);
+  const normalizedIndex = indexName?.trim();
+  if (!parsed || !normalizedIndex || normalizedIndex === DEFAULT_INDEX_NAME) {
+    return stripUriIndex(uri);
+  }
+  return buildUri(parsed.collection, parsed.path, {
+    indexName: normalizedIndex,
+  });
+}
+
+/**
+ * Remove output-only index metadata from a gno:// URI.
+ */
+export function stripUriIndex(uri: string): string {
+  const parsed = parseUri(uri);
+  if (!parsed) {
+    return uri;
+  }
+  return buildUri(parsed.collection, parsed.path);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // docid Utilities
 // ─────────────────────────────────────────────────────────────────────────────

package/src/cli/commands/embed.ts

@@ -45,6 +45,8 @@ import {
 export interface EmbedOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Restrict embedding work to a single collection */
   collection?: string;
   /** Override model URI */
@@ -417,6 +419,7 @@ interface EmbedContext {
  */
 async function initEmbedContext(
   configPath?: string,
+  indexName?: string,
   collection?: string,
   model?: string
 ): Promise<({ ok: true } & EmbedContext) | { ok: false; error: string }> {
@@ -440,9 +443,9 @@ async function initEmbedContext(
   const modelUri = resolveModelUri(config, "embed", model, collection);
 
   const store = new SqliteAdapter();
-  const dbPath = getIndexDbPath();
+  const dbPath = getIndexDbPath(indexName);
   const paths = getConfigPaths();
-  store.setConfigPath(paths.configFile);
+  store.setConfigPath(configPath ?? paths.configFile);
 
   const openResult = await store.open(dbPath, config.ftsTokenizer);
   if (!openResult.ok) {
@@ -467,6 +470,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
   // Initialize config and store
   const initResult = await initEmbedContext(
     options.configPath,
+    options.indexName,
     options.collection,
     options.model
   );

package/src/cli/commands/get.ts

@@ -8,6 +8,7 @@
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 import type { ParsedRef } from "./ref-parser";
 
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import {
   getDocumentCapabilities,
   type DocumentCapabilities,
@@ -22,6 +23,8 @@ import { initStore } from "./shared";
 export interface GetCommandOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** --from <line>, overrides :line suffix */
   from?: number;
   /** -l <lines> */
@@ -109,9 +112,13 @@ export async function get(
   if ("error" in parsed) {
     return { success: false, error: parsed.error, isValidation: true };
   }
+  const explicitIndexName =
+    parsed.type === "uri" ? parseUri(parsed.value)?.indexName : undefined;
+  const indexName = explicitIndexName ?? options.indexName;
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName,
     syncConfig: false,
   });
   if (!initResult.ok) {
@@ -120,7 +127,7 @@ export async function get(
   const { store, config } = initResult;
 
   try {
-    return await fetchDocument(store, parsed, options, config);
+    return await fetchDocument(store, parsed, options, config, indexName);
   } finally {
     await store.close();
   }
@@ -152,7 +159,8 @@ async function fetchDocument(
   store: StorePort,
   parsed: ParsedRef,
   options: GetCommandOptions,
-  config: ConfigLike
+  config: ConfigLike,
+  indexName?: string
 ): Promise<GetResult> {
   const docResult = await lookupDocument(store, parsed);
   if (!docResult.ok) {
@@ -182,6 +190,7 @@ async function fetchDocument(
     parsed,
     options,
     config,
+    indexName,
   });
 }
 
@@ -191,10 +200,11 @@ interface BuildResponseContext {
   parsed: ParsedRef;
   options: GetCommandOptions;
   config: ConfigLike;
+  indexName?: string;
 }
 
 function buildResponse(ctx: BuildResponseContext): GetResult {
-  const { doc, fullContent, parsed, options, config } = ctx;
+  const { doc, fullContent, parsed, options, config, indexName } = ctx;
   const lines = fullContent.split("\n");
   const totalLines = lines.length;
 
@@ -204,7 +214,7 @@ function buildResponse(ctx: BuildResponseContext): GetResult {
       success: true,
       data: {
         docid: doc.docid,
-        uri: doc.uri,
+        uri: decorateUriForIndex(doc.uri, indexName),
         title: doc.title ?? undefined,
         content: "",
         totalLines,
@@ -232,7 +242,7 @@ function buildResponse(ctx: BuildResponseContext): GetResult {
     success: true,
     data: {
       docid: doc.docid,
-      uri: doc.uri,
+      uri: decorateUriForIndex(doc.uri, indexName),
       title: doc.title ?? undefined,
       content,
       totalLines,

package/src/cli/commands/index-cmd.ts

@@ -14,6 +14,8 @@ import { formatSyncResultLines, initStore } from "./shared";
 export interface IndexOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Scope to single collection */
   collection?: string;
   /** Run ingestion only, skip embedding */
@@ -46,6 +48,7 @@ export type IndexResult =
 export async function index(options: IndexOptions = {}): Promise<IndexResult> {
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: options.indexName,
     collection: options.collection,
   });
   if (!initResult.ok) {
@@ -71,6 +74,7 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
       const { embed } = await import("./embed");
       const result = await embed({
         configPath: options.configPath,
+        indexName: options.indexName,
         collection: options.collection,
         verbose: options.verbose,
       });

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

@@ -10,6 +10,7 @@ import { minimatch } from "minimatch";
 import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 import type { ParsedRef } from "./ref-parser";
 
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { isGlobPattern, parseRef, splitRefs } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -20,6 +21,8 @@ import { initStore } from "./shared";
 export interface MultiGetCommandOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Max bytes per document (default 10240) */
   maxBytes?: number;
   /** Include line numbers */
@@ -170,6 +173,7 @@ function truncateContent(
 interface FetchContext {
   store: StorePort;
   config: ConfigLike;
+  indexName?: string;
   maxBytes: number;
   documents: MultiGetDocument[];
   skipped: SkippedDoc[];
@@ -222,7 +226,7 @@ async function fetchSingleDocument(
 
   ctx.documents.push({
     docid: doc.docid,
-    uri: doc.uri,
+    uri: decorateUriForIndex(doc.uri, ctx.indexName),
     title: doc.title ?? undefined,
     content,
     truncated: truncated || undefined,
@@ -249,9 +253,18 @@ export async function multiGet(
 ): Promise<MultiGetResult> {
   const maxBytes = options.maxBytes ?? 10_240;
   const allRefs = splitRefs(refs);
+  const indexResolution = resolveMultiGetIndex(allRefs, options.indexName);
+  if (!indexResolution.ok) {
+    return {
+      success: false,
+      error: indexResolution.error,
+      isValidation: true,
+    };
+  }
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: indexResolution.indexName,
     syncConfig: false,
   });
   if (!initResult.ok) {
@@ -267,6 +280,7 @@ export async function multiGet(
     const ctx: FetchContext = {
       store,
       config,
+      indexName: indexResolution.indexName,
       maxBytes,
       documents: [],
       skipped: [],
@@ -301,6 +315,53 @@ export async function multiGet(
   }
 }
 
+function resolveMultiGetIndex(
+  refs: string[],
+  globalIndexName?: string
+): { ok: true; indexName?: string } | { ok: false; error: string } {
+  const explicitIndexes = new Set<string>();
+  let hasUnindexedRef = false;
+
+  for (const ref of refs) {
+    const parsed = parseRef(ref);
+    if ("error" in parsed || parsed.type !== "uri") {
+      hasUnindexedRef = true;
+      continue;
+    }
+    const indexName = parseUri(parsed.value)?.indexName;
+    if (indexName) {
+      explicitIndexes.add(indexName);
+    } else {
+      hasUnindexedRef = true;
+    }
+  }
+
+  if (explicitIndexes.size === 0) {
+    return { ok: true, indexName: globalIndexName };
+  }
+  if (explicitIndexes.size > 1) {
+    return {
+      ok: false,
+      error: `multi-get cannot mix explicit indexes: ${[...explicitIndexes].sort().join(", ")}`,
+    };
+  }
+
+  const explicitIndex = [...explicitIndexes][0];
+  if (
+    hasUnindexedRef &&
+    globalIndexName &&
+    explicitIndex &&
+    globalIndexName !== explicitIndex
+  ) {
+    return {
+      ok: false,
+      error: `multi-get cannot mix indexed refs (${explicitIndex}) with unindexed refs while --index is ${globalIndexName}`,
+    };
+  }
+
+  return { ok: true, indexName: explicitIndex ?? globalIndexName };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Formatter
 // ─────────────────────────────────────────────────────────────────────────────

package/src/cli/commands/query.ts

@@ -25,7 +25,7 @@ import {
   createProgressRenderer,
   createThrottledProgressRenderer,
 } from "../progress";
-import { initStore } from "./shared";
+import { decorateSearchResultsForIndex, initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -34,6 +34,8 @@ import { initStore } from "./shared";
 export type QueryCommandOptions = HybridSearchOptions & {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Override embedding model */
   embedModel?: string;
   /** Override expansion model */
@@ -83,6 +85,7 @@ export async function query(
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: options.indexName,
     collection: options.collection,
     syncConfig: false,
   });
@@ -208,7 +211,10 @@ export async function query(
       return { success: false, error: result.error.message };
     }
 
-    return { success: true, data: result.value };
+    return {
+      success: true,
+      data: decorateSearchResultsForIndex(result.value, options.indexName),
+    };
   } finally {
     if (embedPort) {
       await embedPort.dispose();

package/src/cli/commands/search.ts

@@ -12,7 +12,7 @@ import {
   type FormatOptions,
   formatSearchResults,
 } from "../format/search-results";
-import { initStore } from "./shared";
+import { decorateSearchResultsForIndex, initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -21,6 +21,8 @@ import { initStore } from "./shared";
 export type SearchCommandOptions = SearchOptions & {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Output as JSON */
   json?: boolean;
   /** Output as Markdown */
@@ -57,6 +59,7 @@ export async function search(
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: options.indexName,
     collection: options.collection,
     syncConfig: false,
   });
@@ -83,7 +86,10 @@ export async function search(
       };
     }
 
-    return { success: true, data: result.value };
+    return {
+      success: true,
+      data: decorateSearchResultsForIndex(result.value, options.indexName),
+    };
   } finally {
     await store.close();
   }

package/src/cli/commands/shared.ts

@@ -7,8 +7,9 @@
 
 import type { Collection, Config } from "../../config/types";
 import type { SyncResult } from "../../ingestion";
+import type { SearchResults } from "../../pipeline/types";
 
-import { getIndexDbPath } from "../../app/constants";
+import { decorateUriForIndex, getIndexDbPath } from "../../app/constants";
 import { getConfigPaths, isInitialized, loadConfig } from "../../config";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
 
@@ -122,6 +123,22 @@ export async function initStore(
   return { ok: true, store, config, collections, actualConfigPath };
 }
 
+export function decorateSearchResultsForIndex(
+  data: SearchResults,
+  indexName?: string
+): SearchResults {
+  if (!indexName) {
+    return data;
+  }
+  return {
+    ...data,
+    results: data.results.map((result) => ({
+      ...result,
+      uri: decorateUriForIndex(result.uri, indexName),
+    })),
+  };
+}
+
 /**
  * Format sync result lines (shared between update and index commands).
  */

package/src/cli/commands/status.ts

@@ -18,6 +18,8 @@ import { SqliteAdapter } from "../../store/sqlite/adapter";
 export interface StatusOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Output as JSON */
   json?: boolean;
   /** Output as Markdown */
@@ -137,11 +139,11 @@ export async function status(
 
   // Open database
   const store = new SqliteAdapter();
-  const dbPath = getIndexDbPath();
+  const dbPath = getIndexDbPath(options.indexName);
   const paths = getConfigPaths();
 
   // Set configPath for status output
-  store.setConfigPath(paths.configFile);
+  store.setConfigPath(options.configPath ?? paths.configFile);
 
   const openResult = await store.open(dbPath, config.ftsTokenizer);
   if (!openResult.ok) {

package/src/cli/commands/update.ts

@@ -14,6 +14,8 @@ import { formatSyncResultLines, initStore } from "./shared";
 export interface UpdateOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Run git pull in git repositories before scanning */
   gitPull?: boolean;
   /** Verbose output */
@@ -33,7 +35,10 @@ export type UpdateResult =
 export async function update(
   options: UpdateOptions = {}
 ): Promise<UpdateResult> {
-  const initResult = await initStore({ configPath: options.configPath });
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+  });
   if (!initResult.ok) {
     return { success: false, error: initResult.error };
   }

package/src/cli/commands/vsearch.ts

@@ -19,7 +19,7 @@ import {
   type FormatOptions,
   formatSearchResults,
 } from "../format/search-results";
-import { initStore } from "./shared";
+import { decorateSearchResultsForIndex, initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -28,6 +28,8 @@ import { initStore } from "./shared";
 export type VsearchCommandOptions = SearchOptions & {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Override model URI */
   model?: string;
   /** Output as JSON */
@@ -66,6 +68,7 @@ export async function vsearch(
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: options.indexName,
     collection: options.collection,
     syncConfig: false,
   });
@@ -137,7 +140,10 @@ export async function vsearch(
         return { success: false, error: result.error.message };
       }
 
-      return { success: true, data: result.value };
+      return {
+        success: true,
+        data: decorateSearchResultsForIndex(result.value, options.indexName),
+      };
     } finally {
       await embedPort.dispose();
     }

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

@@ -119,7 +119,7 @@ function formatTerminalUri(
 
   const target = buildTerminalLinkTarget(
     result.source.absPath,
-    result.snippetRange?.startLine,
+    result.line ?? result.snippetRange?.startLine,
     links.editorUriTemplate ?? undefined
   );