@gmickel/gno 0.9.1 → 0.9.3

package/README.md

@@ -1,13 +1,13 @@
 # GNO
 
-**Your Local Second Brain** — Index, search, and synthesize your entire digital life.
+**Your Local Second Brain**: Index, search, and synthesize your entire digital life.
 
 [![npm](./assets/badges/npm.svg)](https://www.npmjs.com/package/@gmickel/gno)
 [![MIT License](./assets/badges/license.svg)](./LICENSE)
 [![Website](./assets/badges/website.svg)](https://gno.sh)
 [![Twitter](./assets/badges/twitter.svg)](https://twitter.com/gmickel)
 
-GNO is a local knowledge engine for privacy-conscious developers and AI agents. Index your notes, code, PDFs, and Office docs. Get hybrid search (BM25 + vector + reranking) and AI-powered answers—all running 100% on your machine.
+GNO is a local knowledge engine for privacy-conscious developers and AI agents. Index your notes, code, PDFs, and Office docs. Get hybrid search (BM25 + vector + reranking) and AI-powered answers, all running 100% on your machine.
 
 ---
 
@@ -16,9 +16,9 @@ GNO is a local knowledge engine for privacy-conscious developers and AI agents.
 - [Quick Start](#quick-start)
 - [Installation](#installation)
 - [Search Modes](#search-modes)
+- [Agent Integration](#agent-integration)
 - [Web UI](#web-ui)
 - [REST API](#rest-api)
-- [Agent Integration](#agent-integration)
 - [How It Works](#how-it-works)
 - [Features](#features)
 - [Local Models](#local-models)
@@ -85,7 +85,7 @@ Check status: `gno mcp status`
 
 #### Skills (Claude Code, Codex, OpenCode)
 
-Skills integrate via CLI—no MCP overhead:
+Skills integrate via CLI with no MCP overhead:
 
 ```bash
 gno skill install --scope user       # User-wide
@@ -106,7 +106,7 @@ gno skill install --target all       # Both Claude + Codex
 | `gno query`        | Hybrid              | Best accuracy (BM25 + vector + reranking) |
 | `gno ask --answer` | RAG                 | Direct answers with citations             |
 
-**BM25** indexes full documents (not chunks) with Snowball stemming—"running" matches "run".
+**BM25** indexes full documents (not chunks) with Snowball stemming, so "running" matches "run".
 **Vector** embeds chunks with document titles for context awareness.
 
 ```bash
@@ -120,29 +120,76 @@ Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
 
 ---
 
+## Agent Integration
+
+Give your local LLM agents a long-term memory. GNO integrates as a Claude Code skill or MCP server, allowing agents to search, read, and cite your local files.
+
+### Skills
+
+Skills add GNO search to Claude Code/Codex without MCP protocol overhead:
+
+```bash
+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"_
+
+[Skill setup guide →](https://gno.sh/docs/integrations/skills/)
+
+### MCP Server
+
+Connect GNO to Claude Desktop, Cursor, Raycast, and more:
+
+![GNO MCP](./assets/screenshots/mcp.jpg)
+
+GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
+
+| Tool            | Description                 |
+| :-------------- | :-------------------------- |
+| `gno_search`    | BM25 keyword search         |
+| `gno_vsearch`   | Vector semantic search      |
+| `gno_query`     | Hybrid search (recommended) |
+| `gno_get`       | Retrieve document by ID     |
+| `gno_multi_get` | Batch document retrieval    |
+| `gno_status`    | Index health check          |
+
+**Design**: MCP tools are retrieval-only. Your AI assistant (Claude, GPT-4) synthesizes answers from retrieved context. Best retrieval (GNO) + best reasoning (your LLM).
+
+[MCP setup guide →](https://gno.sh/docs/MCP/)
+
+---
+
 ## Web UI
 
-Visual dashboard for search, browsing, editing, and AI answers—right in your browser.
+Visual dashboard for search, browsing, editing, and AI answers. Right in your browser.
 
 ```bash
 gno serve                    # Start on port 3000
 gno serve --port 8080        # Custom port
 ```
 
-![GNO Web UI](./assets/screenshots/webui-home.png)
+![GNO Web UI](./assets/screenshots/webui-home.jpg)
 
 Open `http://localhost:3000` to:
 
-- **Search** — BM25, vector, or hybrid modes with visual results
-- **Browse** — Paginated document list, filter by collection
-- **Edit** — Create, edit, and delete documents with live preview
-- **Ask** — AI-powered Q&A with citations
-- **Manage Collections** — Add, remove, and re-index collections
-- **Switch presets** — Change models live without restart
+- **Search**: BM25, vector, or hybrid modes with visual results
+- **Browse**: Paginated document list, filter by collection
+- **Edit**: Create, edit, and delete documents with live preview
+- **Ask**: AI-powered Q&A with citations
+- **Manage Collections**: Add, remove, and re-index collections
+- **Switch presets**: Change models live without restart
+
+### Search
+
+![GNO Search](./assets/screenshots/webui-search.jpg)
+
+Three retrieval modes: BM25 (keyword), Vector (semantic), or Hybrid (best of both). Adjust search depth for speed vs thoroughness.
 
 ### Document Editing
 
-![GNO Document Editor](./assets/screenshots/webui-editor.png)
+![GNO Document Editor](./assets/screenshots/webui-editor.jpg)
 
 Full-featured markdown editor with:
 
@@ -156,7 +203,7 @@ Full-featured markdown editor with:
 
 ### Collections Management
 
-![GNO Collections](./assets/screenshots/webui-collections.png)
+![GNO Collections](./assets/screenshots/webui-collections.jpg)
 
 - Add collections with folder path input
 - View document count, chunk count, embedding status
@@ -165,9 +212,9 @@ Full-featured markdown editor with:
 
 ### AI Answers
 
-![GNO AI Answers](./assets/screenshots/webui-ask-answer.png)
+![GNO AI Answers](./assets/screenshots/webui-ask-answer.jpg)
 
-Ask questions in natural language—GNO searches your documents and synthesizes answers with inline citations linking to sources.
+Ask questions in natural language. GNO searches your documents and synthesizes answers with inline citations linking to sources.
 
 Everything runs locally. No cloud, no accounts, no data leaving your machine.
 
@@ -219,41 +266,6 @@ No authentication. No rate limits. Build custom tools, automate workflows, integ
 
 ---
 
-## Agent Integration
-
-### MCP Server
-
-![GNO MCP](./assets/screenshots/mcp.jpg)
-
-GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
-
-| Tool            | Description                 |
-| :-------------- | :-------------------------- |
-| `gno_search`    | BM25 keyword search         |
-| `gno_vsearch`   | Vector semantic search      |
-| `gno_query`     | Hybrid search (recommended) |
-| `gno_get`       | Retrieve document by ID     |
-| `gno_multi_get` | Batch document retrieval    |
-| `gno_status`    | Index health check          |
-
-**Design**: MCP tools are retrieval-only. Your AI assistant (Claude, GPT-4) synthesizes answers from retrieved context—best retrieval (GNO) + best reasoning (your LLM).
-
-### Skills
-
-Skills add GNO search to Claude Code/Codex without MCP protocol overhead:
-
-```bash
-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/)
-
----
-
 ## How It Works
 
 ```mermaid
@@ -279,11 +291,11 @@ graph TD
     M --> N[Final Results]
 ```
 
-0. **Strong Signal Check** — Skip expansion if BM25 has confident match (saves 1-3s)
-1. **Query Expansion** — LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
-2. **Parallel Retrieval** — Document-level BM25 + chunk-level vector search on all variants
-3. **Fusion** — RRF with 2× weight for original query, tiered bonus for top ranks
-4. **Reranking** — Qwen3-Reranker scores full documents (32K context), blended with fusion
+0. **Strong Signal Check**: Skip expansion if BM25 has confident match (saves 1-3s)
+1. **Query Expansion**: LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
+2. **Parallel Retrieval**: Document-level BM25 + chunk-level vector search on all variants
+3. **Fusion**: RRF with 2× weight for original query, tiered bonus for top ranks
+4. **Reranking**: Qwen3-Reranker scores best chunk per document (4K), blended with fusion
 
 > **Deep dive**: [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/)
 
@@ -298,12 +310,12 @@ graph TD
 | **Web UI**          | Visual dashboard for search, browse, edit, and AI Q&A |
 | **REST API**        | HTTP API for custom tools and integrations            |
 | **Multi-Format**    | Markdown, PDF, DOCX, XLSX, PPTX, plain text           |
-| **Local LLM**       | AI answers via llama.cpp—no API keys                  |
+| **Local LLM**       | AI answers via llama.cpp, no API keys                 |
 | **Privacy First**   | 100% offline, zero telemetry, your data stays yours   |
 | **MCP Server**      | Works with Claude Desktop, Cursor, Zed, + 8 more      |
 | **Collections**     | Organize sources with patterns, excludes, contexts    |
 | **Multilingual**    | 30+ languages, auto-detection, cross-lingual search   |
-| **Incremental**     | SHA-256 tracking—only changed files re-indexed        |
+| **Incremental**     | SHA-256 tracking, only changed files re-indexed       |
 | **Keyboard First**  | ⌘N capture, ⌘K search, ⌘/ shortcuts, ⌘S save          |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -100,6 +100,7 @@
     "react-dom": "^19.2.3",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
     "shiki": "^3.20.0",
     "sqlite-vec": "^0.1.7-alpha.2",
     "streamdown": "^1.6.10",

package/src/cli/commands/completion/completion.ts

@@ -0,0 +1,201 @@
+/**
+ * Shell completion commands - output scripts or auto-install.
+ *
+ * @module src/cli/commands/completion/completion
+ */
+
+// node:fs/promises - no Bun equivalent for mkdir/appendFile/writeFile
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { CLI_NAME } from "../../../app/constants.js";
+import { CliError } from "../../errors.js";
+import {
+  getCompletionScript,
+  SUPPORTED_SHELLS,
+  type Shell,
+} from "./scripts.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface OutputOptions {
+  shell: Shell;
+}
+
+export interface InstallOptions {
+  /** Override shell detection */
+  shell?: Shell;
+  /** JSON output */
+  json?: boolean;
+}
+
+interface InstallResult {
+  shell: Shell;
+  path: string;
+  action: "installed" | "already_installed";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shell Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect user's current shell.
+ */
+function detectShell(): Shell | undefined {
+  // Check $SHELL env
+  const shellEnv = process.env.SHELL || "";
+  if (shellEnv.includes("zsh")) return "zsh";
+  if (shellEnv.includes("bash")) return "bash";
+  if (shellEnv.includes("fish")) return "fish";
+
+  // Check parent process name on Unix
+  // This is less reliable but can help
+  const parentName = process.env._ || "";
+  if (parentName.includes("zsh")) return "zsh";
+  if (parentName.includes("bash")) return "bash";
+  if (parentName.includes("fish")) return "fish";
+
+  return undefined;
+}
+
+/**
+ * Get the appropriate rc file for a shell.
+ */
+function getShellRcPath(shell: Shell): string {
+  const home = homedir();
+  switch (shell) {
+    case "bash":
+      // Prefer .bashrc, but .bash_profile on macOS
+      return process.platform === "darwin"
+        ? join(home, ".bash_profile")
+        : join(home, ".bashrc");
+    case "zsh":
+      return join(home, ".zshrc");
+    case "fish":
+      return join(home, ".config", "fish", "completions", `${CLI_NAME}.fish`);
+  }
+}
+
+/**
+ * Check if completion is already installed.
+ */
+async function isCompletionInstalled(shell: Shell): Promise<boolean> {
+  const path = getShellRcPath(shell);
+
+  // For fish, check if file exists
+  if (shell === "fish") {
+    return await Bun.file(path).exists();
+  }
+
+  // For bash/zsh, check for shell-specific patterns
+  try {
+    const content = await Bun.file(path).text();
+    // Generic header comment
+    const header = `# ${CLI_NAME}`;
+    // Bash function name
+    const bashFn = `_${CLI_NAME}_completions`;
+    // Zsh-specific patterns (function definition or completion header)
+    const zshFn = `_${CLI_NAME}()`;
+
+    if (shell === "bash") {
+      return content.includes(header) || content.includes(bashFn);
+    }
+    if (shell === "zsh") {
+      return content.includes(header) || content.includes(zshFn);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Output completion script to stdout.
+ */
+export function completionOutput(options: OutputOptions): string {
+  const { shell } = options;
+
+  if (!SUPPORTED_SHELLS.includes(shell)) {
+    throw new CliError(
+      "VALIDATION",
+      `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+    );
+  }
+
+  return getCompletionScript(shell);
+}
+
+/**
+ * Auto-install completion to user's shell config.
+ */
+export async function completionInstall(
+  options: InstallOptions
+): Promise<void> {
+  const { json = false } = options;
+  let { shell } = options;
+
+  // Auto-detect shell if not specified
+  if (!shell) {
+    shell = detectShell();
+    if (!shell) {
+      throw new CliError(
+        "VALIDATION",
+        "Could not detect shell. Please specify: gno completion install --shell <bash|zsh|fish>"
+      );
+    }
+  }
+
+  if (!SUPPORTED_SHELLS.includes(shell)) {
+    throw new CliError(
+      "VALIDATION",
+      `Unsupported shell: ${shell}. Supported: ${SUPPORTED_SHELLS.join(", ")}`
+    );
+  }
+
+  // Check if already installed
+  const alreadyInstalled = await isCompletionInstalled(shell);
+  const rcPath = getShellRcPath(shell);
+  const script = getCompletionScript(shell);
+
+  let result: InstallResult;
+
+  if (alreadyInstalled) {
+    result = { shell, path: rcPath, action: "already_installed" };
+  } else {
+    // Install completion
+    if (shell === "fish") {
+      // Fish uses a separate file in completions dir
+      const dir = join(homedir(), ".config", "fish", "completions");
+      await mkdir(dir, { recursive: true });
+      await writeFile(rcPath, script, "utf-8");
+    } else {
+      // Bash/zsh append to rc file
+      const separator = "\n\n";
+      await appendFile(rcPath, separator + script, "utf-8");
+    }
+    result = { shell, path: rcPath, action: "installed" };
+  }
+
+  // Output result
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else {
+    if (result.action === "already_installed") {
+      process.stdout.write(`Completion already installed for ${shell}.\n`);
+      process.stdout.write(`Config: ${result.path}\n`);
+    } else {
+      process.stdout.write(`Completion installed for ${shell}.\n`);
+      process.stdout.write(`Config: ${result.path}\n`);
+      process.stdout.write(`\nRestart your shell or run:\n`);
+      process.stdout.write(`  source ${result.path}\n`);
+    }
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Shell completion command - output or install completion scripts.
+ *
+ * @module src/cli/commands/completion
+ */
+
+export { completionOutput, completionInstall } from "./completion.js";
+export { SUPPORTED_SHELLS, type Shell } from "./scripts.js";