@gmickel/gno 0.9.0 → 0.9.2

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 full documents (32K context), 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.0",
+  "version": "0.9.2",
   "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/skill/paths.ts

@@ -1,6 +1,7 @@
 /**
  * Path resolution for skill installation.
  * Supports Claude Code and Codex targets with project/user scopes.
+ * Note: OpenCode and Amp use the same .claude path as Claude Code.
  *
  * @module src/cli/commands/skill/paths
  */
@@ -28,6 +29,8 @@ export const ENV_CODEX_SKILLS_DIR = "CODEX_SKILLS_DIR";
 export type SkillScope = "project" | "user";
 export type SkillTarget = "claude" | "codex";
 
+export const SKILL_TARGETS: SkillTarget[] = ["claude", "codex"];
+
 export interface SkillPathOptions {
   scope: SkillScope;
   target: SkillTarget;
@@ -53,13 +56,27 @@ export interface SkillPaths {
 /** Skill name for the gno skill directory */
 export const SKILL_NAME = "gno";
 
-/** Directory name for skills within agent config */
-const SKILLS_SUBDIR = "skills";
+/** Path configuration per target */
+interface TargetPathConfig {
+  projectBase: string; // e.g., ".claude"
+  userBase: string; // e.g., ".claude" (joined with homedir) or ".config/opencode"
+  skillsSubdir: string; // e.g., "skills" or "skill"
+  envVar: string;
+}
 
-/** Agent config directory names */
-const AGENT_DIRS: Record<SkillTarget, string> = {
-  claude: ".claude",
-  codex: ".codex",
+const TARGET_CONFIGS: Record<SkillTarget, TargetPathConfig> = {
+  claude: {
+    projectBase: ".claude",
+    userBase: ".claude",
+    skillsSubdir: "skills",
+    envVar: ENV_CLAUDE_SKILLS_DIR,
+  },
+  codex: {
+    projectBase: ".codex",
+    userBase: ".codex",
+    skillsSubdir: "skills",
+    envVar: ENV_CODEX_SKILLS_DIR,
+  },
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -71,19 +88,15 @@ const AGENT_DIRS: Record<SkillTarget, string> = {
  */
 export function resolveSkillPaths(opts: SkillPathOptions): SkillPaths {
   const { scope, target, cwd, homeDir } = opts;
+  const config = TARGET_CONFIGS[target];
 
   // Check for env overrides first
-  const envOverride =
-    target === "claude"
-      ? process.env[ENV_CLAUDE_SKILLS_DIR]
-      : process.env[ENV_CODEX_SKILLS_DIR];
+  const envOverride = process.env[config.envVar];
 
   if (envOverride) {
     // Require absolute path for security
     if (!isAbsolute(envOverride)) {
-      throw new Error(
-        `${target === "claude" ? ENV_CLAUDE_SKILLS_DIR : ENV_CODEX_SKILLS_DIR} must be an absolute path`
-      );
+      throw new Error(`${config.envVar} must be an absolute path`);
     }
     const skillsDir = normalize(envOverride);
     return {
@@ -94,18 +107,17 @@ export function resolveSkillPaths(opts: SkillPathOptions): SkillPaths {
   }
 
   // Resolve base directory
-  const agentDir = AGENT_DIRS[target];
   let base: string;
 
   if (scope === "user") {
     const home = homeDir ?? process.env[ENV_SKILLS_HOME_OVERRIDE] ?? homedir();
-    base = join(home, agentDir);
+    base = join(home, config.userBase);
   } else {
     const projectRoot = cwd ?? process.cwd();
-    base = join(projectRoot, agentDir);
+    base = join(projectRoot, config.projectBase);
   }
 
-  const skillsDir = join(base, SKILLS_SUBDIR);
+  const skillsDir = join(base, config.skillsSubdir);
   const gnoDir = join(skillsDir, SKILL_NAME);
 
   return { base, skillsDir, gnoDir };
@@ -120,8 +132,7 @@ export function resolveAllPaths(
   overrides?: { cwd?: string; homeDir?: string }
 ): Array<{ scope: SkillScope; target: SkillTarget; paths: SkillPaths }> {
   const scopes: SkillScope[] = scope === "all" ? ["project", "user"] : [scope];
-  const targets: SkillTarget[] =
-    target === "all" ? ["claude", "codex"] : [target];
+  const targets: SkillTarget[] = target === "all" ? SKILL_TARGETS : [target];
 
   const results: Array<{
     scope: SkillScope;
@@ -147,11 +158,16 @@ export function resolveAllPaths(
 // ─────────────────────────────────────────────────────────────────────────────
 
 /**
- * Expected path suffix for gno skill directory.
- * Platform-aware (handles Windows backslash).
+ * Get expected path suffixes for gno skill directory.
+ * Returns all valid suffixes since different targets use different subdir names.
  */
-function getExpectedSuffix(): string {
-  return `${sep}${SKILLS_SUBDIR}${sep}${SKILL_NAME}`;
+function getExpectedSuffixes(): string[] {
+  const subdirs = new Set(
+    Object.values(TARGET_CONFIGS).map((c) => c.skillsSubdir)
+  );
+  return Array.from(subdirs).map(
+    (subdir) => `${sep}${subdir}${sep}${SKILL_NAME}`
+  );
 }
 
 /**
@@ -164,11 +180,14 @@ export function validatePathForDeletion(
 ): string | null {
   const normalized = normalize(destDir);
   const normalizedBase = normalize(base);
-  const expectedSuffix = getExpectedSuffix();
-
-  // Must end with /skills/gno (or \skills\gno on Windows)
-  if (!normalized.endsWith(expectedSuffix)) {
-    return `Path does not end with expected suffix (${expectedSuffix})`;
+  const expectedSuffixes = getExpectedSuffixes();
+
+  // Must end with /skills/gno or /skill/gno (platform-aware)
+  const hasValidSuffix = expectedSuffixes.some((suffix) =>
+    normalized.endsWith(suffix)
+  );
+  if (!hasValidSuffix) {
+    return `Path does not end with expected suffix (${expectedSuffixes.join(" or ")})`;
   }
 
   // Minimum length sanity check

package/src/serve/public/components/editor/CodeMirrorEditor.tsx

@@ -21,6 +21,8 @@ export interface CodeMirrorEditorProps {
   initialContent: string;
   /** Called when content changes */
   onChange: (content: string) => void;
+  /** Called when scroll position changes (0-1 percentage) */
+  onScroll?: (scrollPercent: number) => void;
   /** Additional CSS classes */
   className?: string;
 }
@@ -36,21 +38,28 @@ export interface CodeMirrorEditorRef {
   wrapSelection: (prefix: string, suffix: string) => void;
   /** Insert text at cursor position */
   insertAtCursor: (text: string) => void;
+  /** Scroll to percentage position (0-1). Returns true if scroll actually changed. */
+  scrollToPercent: (percent: number) => boolean;
 }
 
 function CodeMirrorEditorInner(
-  { initialContent, onChange, className }: CodeMirrorEditorProps,
+  { initialContent, onChange, onScroll, className }: CodeMirrorEditorProps,
   ref: ForwardedRef<CodeMirrorEditorRef>
 ) {
   const containerRef = useRef<HTMLDivElement>(null);
   const viewRef = useRef<EditorView | null>(null);
   const onChangeRef = useRef(onChange);
+  const onScrollRef = useRef(onScroll);
 
-  // Keep onChange ref current to avoid recreating editor on callback change
+  // Keep callback refs current to avoid recreating editor
   useEffect(() => {
     onChangeRef.current = onChange;
   }, [onChange]);
 
+  useEffect(() => {
+    onScrollRef.current = onScroll;
+  }, [onScroll]);
+
   // Initialize CodeMirror
   useEffect(() => {
     if (!containerRef.current) return;
@@ -81,8 +90,28 @@ function CodeMirrorEditorInner(
       parent: containerRef.current,
     });
 
+    // Attach scroll listener directly to scrollDOM for reliable event capture
+    // (scroll events don't bubble, so domEventHandlers may miss them)
+    const scroller = view.scrollDOM;
+    const handleScroll = () => {
+      const maxScroll = scroller.scrollHeight - scroller.clientHeight;
+      if (maxScroll > 0 && onScrollRef.current) {
+        const percent = Math.max(
+          0,
+          Math.min(1, scroller.scrollTop / maxScroll)
+        );
+        if (Number.isFinite(percent)) {
+          onScrollRef.current(percent);
+        }
+      }
+    };
+    scroller.addEventListener("scroll", handleScroll, { passive: true });
+
     viewRef.current = view;
-    return () => view.destroy();
+    return () => {
+      scroller.removeEventListener("scroll", handleScroll);
+      view.destroy();
+    };
     // Only run on mount - initialContent should not trigger re-creation
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
@@ -134,6 +163,23 @@ function CodeMirrorEditorInner(
       });
       view.focus();
     },
+    scrollToPercent: (percent: number): boolean => {
+      const view = viewRef.current;
+      if (!view || !Number.isFinite(percent)) return false;
+
+      const clamped = Math.max(0, Math.min(1, percent));
+      const scroller = view.scrollDOM;
+      const maxScroll = scroller.scrollHeight - scroller.clientHeight;
+      if (maxScroll > 0) {
+        const targetScroll = clamped * maxScroll;
+        // Only scroll if position actually changes (avoids unnecessary events)
+        if (Math.abs(scroller.scrollTop - targetScroll) > 0.5) {
+          scroller.scrollTop = targetScroll;
+          return true;
+        }
+      }
+      return false;
+    },
   }));
 
   return <div ref={containerRef} className={className} />;