@gmickel/gno 0.6.0 → 0.6.1

package/README.md

@@ -36,6 +36,8 @@ gno query "auth best practices"  # Hybrid search
 gno ask "summarize the API" --answer  # AI answer with citations
 ```
 
+![GNO CLI](./assets/screenshots/cli.jpg)
+
 ---
 
 ## Installation
@@ -127,6 +129,8 @@ gno serve                    # Start on port 3000
 gno serve --port 8080        # Custom port
 ```
 
+![GNO Web UI](./assets/screenshots/webui-home.jpg)
+
 Open `http://localhost:3000` to:
 
 - **Search** — BM25, vector, or hybrid modes with visual results
@@ -181,6 +185,8 @@ No authentication. No rate limits. Build custom tools, automate workflows, integ
 
 ### MCP Server
 
+![GNO MCP](./assets/screenshots/mcp.jpg)
+
 GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
 
 | Tool | Description |
@@ -202,6 +208,8 @@ Skills add GNO search to Claude Code/Codex without MCP protocol overhead:
 gno skill install --scope user
 ```
 
+![GNO Skill in Claude Code](./assets/screenshots/claudecodeskill.jpg)
+
 Then ask your agent: *"Search my notes for the auth discussion"*
 
 > **Detailed docs**: [MCP Integration](https://gno.sh/docs/MCP/) · [Use Cases](https://gno.sh/docs/USE-CASES/)
@@ -280,7 +288,7 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 
 ```bash
 gno models use balanced
-gno models pull --all
+gno models pull --all  # Optional: pre-download models (auto-downloads on first use)
 ```
 
 > **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)

package/package.json

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

package/src/cli/commands/ask.ts

@@ -6,6 +6,7 @@
  */
 
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type {
   EmbeddingPort,
@@ -22,6 +23,11 @@ import {
   createVectorIndexPort,
   type VectorIndexPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 import { initStore } from './shared';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -82,9 +88,26 @@ export async function ask(
     const preset = getActivePreset(config);
     const llm = new LlmAdapter(config);
 
+    // Resolve download policy from env/flags
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model downloads (throttled)
+    const showProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     // Create embedding port
     const embedUri = options.embedModel ?? preset.embed;
-    const embedResult = await llm.createEmbeddingPort(embedUri);
+    const embedResult = await llm.createEmbeddingPort(embedUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (embedResult.ok) {
       embedPort = embedResult.value;
     }
@@ -94,7 +117,12 @@ export async function ask(
     const needsGen = !options.noExpand || options.answer;
     if (needsGen) {
       const genUri = options.genModel ?? preset.gen;
-      const genResult = await llm.createGenerationPort(genUri);
+      const genResult = await llm.createGenerationPort(genUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('gen', progress)
+          : undefined,
+      });
       if (genResult.ok) {
         genPort = genResult.value;
       }
@@ -103,12 +131,22 @@ export async function ask(
     // Create rerank port (unless --fast or --no-rerank)
     if (!options.noRerank) {
       const rerankUri = options.rerankModel ?? preset.rerank;
-      const rerankResult = await llm.createRerankPort(rerankUri);
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('rerank', progress)
+          : undefined,
+      });
       if (rerankResult.ok) {
         rerankPort = rerankResult.value;
       }
     }
 
+    // Clear progress line if shown
+    if (showProgress && downloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Create vector index
     let vectorIndex: VectorIndexPort | null = null;
     if (embedPort) {

package/src/cli/commands/embed.ts

@@ -9,6 +9,7 @@ import type { Database } from 'bun:sqlite';
 import { getIndexDbPath } from '../../app/constants';
 import { getConfigPaths, isInitialized, loadConfig } from '../../config';
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type { EmbeddingPort } from '../../llm/types';
 import { formatDocForEmbedding } from '../../pipeline/contextual';
@@ -23,6 +24,11 @@ import {
   type VectorRow,
   type VectorStatsPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -274,14 +280,35 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       };
     }
 
-    // Create LLM adapter and embedding port
+    // Create LLM adapter and embedding port with auto-download
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model download (throttled to avoid spam)
+    const showDownloadProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showDownloadProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     const llm = new LlmAdapter(config);
-    const embedResult = await llm.createEmbeddingPort(modelUri);
+    const embedResult = await llm.createEmbeddingPort(modelUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (!embedResult.ok) {
       return { success: false, error: embedResult.error.message };
     }
     embedPort = embedResult.value;
 
+    // Clear download progress line if shown
+    if (showDownloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Discover dimensions via probe embedding
     const probeResult = await embedPort.embed('dimension probe');
     if (!probeResult.ok) {

package/src/cli/commands/models/index.ts

@@ -4,6 +4,7 @@
  * @module src/cli/commands/models
  */
 
+export { createProgressRenderer } from '../../progress';
 export {
   formatModelsClear,
   type ModelsClearOptions,
@@ -23,7 +24,6 @@ export {
   modelsPath,
 } from './path';
 export {
-  createProgressRenderer,
   formatModelsPull,
   type ModelPullResult,
   type ModelsPullOptions,

package/src/cli/commands/models/pull.ts

@@ -185,20 +185,3 @@ export function formatModelsPull(result: ModelsPullResult): string {
 
   return lines.join('\n');
 }
-
-/**
- * Create a terminal progress renderer.
- */
-export function createProgressRenderer(): (
-  type: ModelType,
-  progress: DownloadProgress
-) => void {
-  return (type, progress) => {
-    const percent = progress.percent.toFixed(1);
-    const downloaded = (progress.downloadedBytes / 1024 / 1024).toFixed(1);
-    const total = (progress.totalBytes / 1024 / 1024).toFixed(1);
-    process.stderr.write(
-      `\r${type}: ${percent}% (${downloaded}/${total} MB)    `
-    );
-  };
-}

package/src/cli/commands/query.ts

@@ -6,6 +6,7 @@
  */
 
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type {
   EmbeddingPort,
@@ -18,6 +19,11 @@ import {
   createVectorIndexPort,
   type VectorIndexPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 import { initStore } from './shared';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -90,9 +96,26 @@ export async function query(
     const preset = getActivePreset(config);
     const llm = new LlmAdapter(config);
 
+    // Resolve download policy from env/flags
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model downloads (throttled)
+    const showProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     // Create embedding port (for vector search)
     const embedUri = options.embedModel ?? preset.embed;
-    const embedResult = await llm.createEmbeddingPort(embedUri);
+    const embedResult = await llm.createEmbeddingPort(embedUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (embedResult.ok) {
       embedPort = embedResult.value;
     }
@@ -100,7 +123,12 @@ export async function query(
     // Create generation port (for expansion) - optional
     if (!options.noExpand) {
       const genUri = options.genModel ?? preset.gen;
-      const genResult = await llm.createGenerationPort(genUri);
+      const genResult = await llm.createGenerationPort(genUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('gen', progress)
+          : undefined,
+      });
       if (genResult.ok) {
         genPort = genResult.value;
       }
@@ -109,12 +137,22 @@ export async function query(
     // Create rerank port - optional
     if (!options.noRerank) {
       const rerankUri = options.rerankModel ?? preset.rerank;
-      const rerankResult = await llm.createRerankPort(rerankUri);
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('rerank', progress)
+          : undefined,
+      });
       if (rerankResult.ok) {
         rerankPort = rerankResult.value;
       }
     }
 
+    // Clear progress line if shown
+    if (showProgress && downloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Create vector index (optional)
     let vectorIndex: VectorIndexPort | null = null;
     if (embedPort) {

package/src/cli/context.ts

@@ -5,6 +5,7 @@
  * @module src/cli/context
  */
 
+import { envIsSet } from '../llm/policy';
 import { setColorsEnabled } from './colors';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -19,6 +20,7 @@ export interface GlobalOptions {
   yes: boolean;
   quiet: boolean;
   json: boolean;
+  offline: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -40,6 +42,13 @@ export function parseGlobalOptions(
 
   const colorEnabled = !(noColorEnv || noColorFlag);
 
+  // Offline mode: --offline flag or HF_HUB_OFFLINE/GNO_OFFLINE env var
+  // Use envIsSet for consistent truthiness (treats "1", "true", "yes" as true)
+  const offlineEnv =
+    envIsSet(env, 'HF_HUB_OFFLINE') || envIsSet(env, 'GNO_OFFLINE');
+  const offlineFlag = Boolean(raw.offline);
+  const offlineEnabled = offlineEnv || offlineFlag;
+
   return {
     index: (raw.index as string) ?? 'default',
     config: raw.config as string | undefined,
@@ -48,6 +57,7 @@ export function parseGlobalOptions(
     yes: Boolean(raw.yes),
     quiet: Boolean(raw.quiet),
     json: Boolean(raw.json),
+    offline: offlineEnabled,
   };
 }
 

package/src/cli/program.ts

@@ -132,7 +132,8 @@ export function createProgram(): Command {
     .option('--verbose', 'verbose logging')
     .option('--yes', 'non-interactive mode')
     .option('-q, --quiet', 'suppress non-essential output')
-    .option('--json', 'JSON output (for errors and supported commands)');
+    .option('--json', 'JSON output (for errors and supported commands)')
+    .option('--offline', 'offline mode (use cached models only)');
 
   // Resolve globals ONCE before any command runs (ensures consistency)
   program.hook('preAction', (thisCommand) => {

package/src/cli/progress.ts

@@ -0,0 +1,88 @@
+/**
+ * Progress rendering utilities for CLI.
+ * Kept in CLI layer to avoid layer violations.
+ *
+ * @module src/cli/progress
+ */
+
+import type { DownloadProgress, ModelType } from '../llm/types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ProgressCallback<T = ModelType> = (
+  type: T,
+  progress: DownloadProgress
+) => void;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Progress Renderers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a terminal progress renderer for model downloads.
+ * Writes progress to stderr with carriage return for in-place updates.
+ */
+export function createProgressRenderer(): ProgressCallback {
+  return (type, progress) => {
+    const percent = progress.percent.toFixed(1);
+    const downloaded = (progress.downloadedBytes / 1024 / 1024).toFixed(1);
+    const total = (progress.totalBytes / 1024 / 1024).toFixed(1);
+    process.stderr.write(
+      `\r${type}: ${percent}% (${downloaded}/${total} MB)    `
+    );
+  };
+}
+
+/**
+ * Create a throttled progress renderer.
+ * Emits at most once per interval, plus always on completion.
+ *
+ * @param renderer - Underlying renderer to throttle
+ * @param intervalMs - Minimum interval between emissions (default: 100ms)
+ */
+export function createThrottledProgressRenderer(
+  renderer: ProgressCallback,
+  intervalMs = 100
+): ProgressCallback {
+  let lastEmit = 0;
+
+  return (type, progress) => {
+    const now = Date.now();
+
+    // Always emit on completion (100%) or error
+    const isComplete = progress.percent >= 100;
+
+    // Emit if enough time passed or completing
+    if (isComplete || now - lastEmit >= intervalMs) {
+      renderer(type, progress);
+      lastEmit = now;
+    }
+  };
+}
+
+/**
+ * Create a non-TTY progress renderer (periodic line output).
+ * For non-interactive contexts like CI or logs.
+ */
+export function createNonTtyProgressRenderer(
+  intervalMs = 5000
+): ProgressCallback {
+  let lastEmit = 0;
+
+  return (type, progress) => {
+    const now = Date.now();
+    const isComplete = progress.percent >= 100;
+
+    if (isComplete || now - lastEmit >= intervalMs) {
+      const percent = progress.percent.toFixed(1);
+      const downloaded = (progress.downloadedBytes / 1024 / 1024).toFixed(1);
+      const total = (progress.totalBytes / 1024 / 1024).toFixed(1);
+      process.stderr.write(
+        `${type}: ${percent}% (${downloaded}/${total} MB)\n`
+      );
+      lastEmit = now;
+    }
+  };
+}

package/src/cli/run.ts

@@ -35,6 +35,7 @@ const KNOWN_BOOL_FLAGS = new Set([
   '-q',
   '--quiet',
   '--json',
+  '--offline',
 ]);
 
 // Known global flags that take values (--flag value or --flag=value)