@gmickel/gno 0.3.4 → 0.4.0

package/README.md

@@ -2,10 +2,12 @@
 
 **Your Local Second Brain** — Index, search, and synthesize your entire digital life.
 
-[![npm version](https://img.shields.io/npm/v/@gmickel/gno.svg)](https://www.npmjs.com/package/@gmickel/gno)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![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 individuals and AI agents. Index your notes, code, PDFs, and Office docs. Get lightning-fast semantic search and AI-powered answers—all 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.
 
 ---
 
@@ -14,8 +16,11 @@ GNO is a local knowledge engine for privacy-conscious individuals and AI agents.
 - [Quick Start](#quick-start)
 - [Installation](#installation)
 - [Search Modes](#search-modes)
+- [Web UI](#web-ui)
+- [REST API](#rest-api)
 - [Agent Integration](#agent-integration)
 - [How It Works](#how-it-works)
+- [Features](#features)
 - [Local Models](#local-models)
 - [Architecture](#architecture)
 - [Development](#development)
@@ -25,21 +30,18 @@ GNO is a local knowledge engine for privacy-conscious individuals and AI agents.
 ## Quick Start
 
 ```bash
-# Initialize with your notes folder
-gno init ~/notes --name notes
-
-# Index documents (BM25 + vectors)
-gno index
-
-# Search
-gno query "authentication best practices"
-gno ask "summarize the API discussion" --answer
+gno init ~/notes --name notes    # Point at your docs
+gno index                        # Build search index
+gno query "auth best practices"  # Hybrid search
+gno ask "summarize the API" --answer  # AI answer with citations
 ```
 
 ---
 
 ## Installation
 
+### Install GNO
+
 Requires [Bun](https://bun.sh/) >= 1.0.0.
 
 ```bash
@@ -47,59 +49,160 @@ bun install -g @gmickel/gno
 ```
 
 **macOS**: Vector search requires Homebrew SQLite:
+
 ```bash
 brew install sqlite3
 ```
 
-Verify:
+Verify everything works:
+
 ```bash
 gno doctor
 ```
 
+### Connect to AI Agents
+
+#### MCP Server (Claude Desktop, Cursor, Zed, etc.)
+
+One command to add GNO to your AI assistant:
+
+```bash
+gno mcp install                      # Claude Desktop (default)
+gno mcp install --target cursor      # Cursor
+gno mcp install --target claude-code # Claude Code CLI
+gno mcp install --target zed         # Zed
+gno mcp install --target windsurf    # Windsurf
+gno mcp install --target codex       # OpenAI Codex CLI
+gno mcp install --target opencode    # OpenCode
+gno mcp install --target amp         # Amp
+gno mcp install --target lmstudio    # LM Studio
+gno mcp install --target librechat   # LibreChat
+```
+
+Check status: `gno mcp status`
+
+#### Skills (Claude Code, Codex, OpenCode)
+
+Skills integrate via CLI—no MCP overhead:
+
+```bash
+gno skill install --scope user       # User-wide
+gno skill install --target codex     # Codex
+gno skill install --target all       # Both Claude + Codex
+```
+
+> **Full setup guide**: [MCP Integration](https://gno.sh/docs/MCP/) · [CLI Reference](https://gno.sh/docs/CLI/)
+
 ---
 
 ## Search Modes
 
 | Command | Mode | Best For |
 |:--------|:-----|:---------|
-| `gno search` | BM25 | Exact phrases, known terms |
+| `gno search` | BM25 | Exact phrases, code identifiers |
 | `gno vsearch` | Vector | Natural language, concepts |
-| `gno query` | Hybrid | Highest accuracy (BM25 + Vector + reranking) |
-| `gno ask` | RAG | Direct answers with citations |
+| `gno query` | Hybrid | Best accuracy (BM25 + vector + reranking) |
+| `gno ask --answer` | RAG | Direct answers with citations |
+
+```bash
+gno search "handleAuth"              # Find exact matches
+gno vsearch "error handling patterns" # Semantic similarity
+gno query "database optimization"    # Full pipeline
+gno ask "what did we decide" --answer # AI synthesis
+```
+
+Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
 
 ---
 
-## Agent Integration
+## Web UI
 
-### For Claude Code / Codex / OpenCode
+Visual dashboard for search, browsing, and AI answers—right in your browser.
 
 ```bash
-gno skill install --scope user    # Claude Code
-gno skill install --target codex  # Codex
-gno skill install --target all    # Both
+gno serve                    # Start on port 3000
+gno serve --port 8080        # Custom port
 ```
 
-### For Claude Desktop / Cursor
+Open `http://localhost:3000` to:
+
+- **Search** — BM25, vector, or hybrid modes with visual results
+- **Browse** — Paginated document list, filter by collection
+- **Ask** — AI-powered Q&A with citations
+- **Switch presets** — Change models live without restart
+
+Everything runs locally. No cloud, no accounts, no data leaving your machine.
+
+> **Detailed docs**: [Web UI Guide](https://gno.sh/docs/WEB-UI/)
+
+---
+
+## REST API
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Programmatic access to all GNO features via HTTP.
 
-```json
-{
-  "mcpServers": {
-    "gno": { "command": "gno", "args": ["mcp"] }
-  }
-}
+```bash
+# Hybrid search
+curl -X POST http://localhost:3000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"query": "authentication patterns", "limit": 10}'
+
+# AI answer
+curl -X POST http://localhost:3000/api/ask \
+  -H "Content-Type: application/json" \
+  -d '{"query": "What is our deployment process?"}'
+
+# Index status
+curl http://localhost:3000/api/status
 ```
 
-**MCP Tools**: `gno_search`, `gno_vsearch`, `gno_query`, `gno_get`, `gno_multi_get`, `gno_status`
+| Endpoint | Method | Description |
+|:---------|:-------|:------------|
+| `/api/query` | POST | Hybrid search (recommended) |
+| `/api/search` | POST | BM25 keyword search |
+| `/api/ask` | POST | AI-powered Q&A |
+| `/api/docs` | GET | List documents |
+| `/api/doc` | GET | Get document content |
+| `/api/status` | GET | Index statistics |
+| `/api/presets` | GET/POST | Model preset management |
+| `/api/models/pull` | POST | Download models |
+| `/api/models/status` | GET | Download progress |
+
+No authentication. No rate limits. Build custom tools, automate workflows, integrate with any language.
+
+> **Full reference**: [API Documentation](https://gno.sh/docs/API/)
+
+---
+
+## Agent Integration
+
+### MCP Server
+
+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 |
 
-### CLI Output Formats
+**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 query "meeting notes" --json -n 5      # JSON for LLMs
-gno search "API design" --files            # File paths only
+gno skill install --scope user
 ```
 
+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
@@ -110,30 +213,46 @@ graph TD
     B --> C{Lexical Variants}
     B --> D{Semantic Variants}
     B --> E{HyDE Passage}
-    A --> F[Original Query]
 
     C --> G(BM25 Search)
     D --> H(Vector Search)
     E --> H
-    F --> G
-    F --> H
+    A --> G
+    A --> H
 
-    G --> I(Ranked List 1)
-    H --> J(Ranked List 2)
+    G --> I(Ranked Results)
+    H --> J(Ranked Results)
     I --> K{RRF Fusion}
     J --> K
 
-    K --> L(Top Candidates)
+    K --> L(Top 20 Candidates)
     L --> M(Cross-Encoder Rerank)
     M --> N[Final Results]
 ```
 
-1. **Query Expansion** — LLM generates lexical variants, semantic variants, and [HyDE](https://arxiv.org/abs/2212.10496) passage
-2. **Parallel Retrieval** — BM25 + Vector search run concurrently on all variants
+1. **Query Expansion** — LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
+2. **Parallel Retrieval** — BM25 + vector search run concurrently on all variants
 3. **Fusion** — Reciprocal Rank Fusion merges results with position-based scoring
-4. **Re-ranking** — Cross-encoder rescores top 20, blended with fusion scores
+4. **Reranking** — Cross-encoder rescores top 20, blended with fusion scores
+
+> **Deep dive**: [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/)
+
+---
 
-See [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/) for full pipeline details.
+## Features
+
+| Feature | Description |
+|:--------|:------------|
+| **Hybrid Search** | BM25 + vector + RRF fusion + cross-encoder reranking |
+| **Web UI** | Visual dashboard for search, browse, 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 |
+| **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 |
 
 ---
 
@@ -143,9 +262,24 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 
 | Model | Purpose | Size |
 |:------|:--------|:-----|
-| bge-m3 | Embeddings | ~500MB |
-| bge-reranker-v2-m3 | Re-ranking | ~700MB |
-| Qwen-Instruct | Query expansion | ~600MB |
+| bge-m3 | Embeddings (1024-dim, multilingual) | ~500MB |
+| bge-reranker-v2-m3 | Cross-encoder reranking | ~700MB |
+| Qwen/SmolLM | Query expansion + AI answers | ~600MB-1.2GB |
+
+### Model Presets
+
+| Preset | Disk | Best For |
+|:-------|:-----|:---------|
+| `slim` | ~1GB | Fast, lower quality |
+| `balanced` | ~2GB | Good balance (default) |
+| `quality` | ~2.5GB | Best answers |
+
+```bash
+gno models use balanced
+gno models pull --all
+```
+
+> **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)
 
 ---
 
@@ -153,16 +287,18 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 
 ```
 ┌─────────────────────────────────────────────────┐
-│                  GNO CLI / MCP                  │
+│            GNO CLI / MCP / Web UI / API         │
 ├─────────────────────────────────────────────────┤
-│  Ports: Converter, Store, Embedding, Rerank     │
+│  Ports: Converter, Store, Embedding, Rerank    │
 ├─────────────────────────────────────────────────┤
-│  Adapters: SQLite, FTS5, sqlite-vec, llama-cpp  │
+│  Adapters: SQLite, FTS5, sqlite-vec, llama-cpp │
 ├─────────────────────────────────────────────────┤
-│  Core: Identity, Mirrors, Chunking, Retrieval   │
+│  Core: Identity, Mirrors, Chunking, Retrieval  │
 └─────────────────────────────────────────────────┘
 ```
 
+> **Details**: [Architecture](https://gno.sh/docs/ARCHITECTURE/)
+
 ---
 
 ## Development
@@ -171,14 +307,19 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 git clone https://github.com/gmickel/gno.git && cd gno
 bun install
 bun test
-bun run lint
-bun run typecheck
+bun run lint && bun run typecheck
 ```
 
-See [Contributing](.github/CONTRIBUTING.md) for CI matrix, caching, and release process.
+> **Contributing**: [CONTRIBUTING.md](.github/CONTRIBUTING.md)
 
 ---
 
 ## License
 
 [MIT](./LICENSE)
+
+---
+
+<p align="center">
+  made with ❤️ by <a href="https://twitter.com/gmickel">@gmickel</a>
+</p>

package/assets/badges/license.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="85" height="28" viewBox="0 0 85 28">
+  <defs>
+    <linearGradient id="bg-lic" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#0f0f1a"/>
+    </linearGradient>
+  </defs>
+  <rect width="85" height="28" rx="6" fill="url(#bg-lic)"/>
+  <rect x="1" y="1" width="83" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
+  <text x="10" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#94a3b8">MIT</text>
+  <text x="34" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#2dd4bf">License</text>
+</svg>

package/assets/badges/npm.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="66" height="28" viewBox="0 0 66 28">
+  <defs>
+    <linearGradient id="bg-npm" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#0f0f1a"/>
+    </linearGradient>
+  </defs>
+  <rect width="66" height="28" rx="6" fill="url(#bg-npm)"/>
+  <rect x="1" y="1" width="64" height="26" rx="5" fill="none" stroke="#cb3837" stroke-opacity="0.4"/>
+  <rect x="8" y="7" width="32" height="14" rx="3" fill="#cb3837"/>
+  <text x="13" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="10" font-weight="700" fill="#fff">npm</text>
+  <text x="46" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" fill="#e2e8f0">↗</text>
+</svg>

package/assets/badges/twitter.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="130" height="28" viewBox="0 0 130 28">
+  <defs>
+    <linearGradient id="bg2" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#0f0f1a"/>
+    </linearGradient>
+    <filter id="glow2">
+      <feGaussianBlur stdDeviation="0.5" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+  <rect width="130" height="28" rx="6" fill="url(#bg2)"/>
+  <rect x="1" y="1" width="128" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
+  <!-- X logo -->
+  <g transform="translate(10, 7)" fill="#e2e8f0">
+    <path d="M10.5 1.5L6.75 6.5L10.75 12.5H8.5L5.75 8.5L2.5 12.5H0.25L4.25 7L0.5 1.5H2.75L5.25 5.25L8.25 1.5H10.5Z" transform="scale(1.1)"/>
+  </g>
+  <text x="32" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" font-weight="500" fill="#e2e8f0" filter="url(#glow2)">@gmickel</text>
+</svg>

package/assets/badges/website.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="120" height="28" viewBox="0 0 120 28">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#0f0f1a"/>
+    </linearGradient>
+    <filter id="glow">
+      <feGaussianBlur stdDeviation="1" result="coloredBlur"/>
+      <feMerge>
+        <feMergeNode in="coloredBlur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+  <rect width="120" height="28" rx="6" fill="url(#bg)"/>
+  <rect x="1" y="1" width="118" height="26" rx="5" fill="none" stroke="#2dd4bf" stroke-opacity="0.3"/>
+  <text x="10" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="11" fill="#2dd4bf" filter="url(#glow)">❯</text>
+  <text x="24" y="18" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,monospace" font-size="12" font-weight="600" fill="#e2e8f0">gno.sh</text>
+  <rect x="74" y="9" width="2" height="12" fill="#2dd4bf" opacity="0.8">
+    <animate attributeName="opacity" values="0.8;0.2;0.8" dur="1.2s" repeatCount="indefinite"/>
+  </rect>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "search",
@@ -56,6 +56,8 @@
     "website:dev": "cd website && make serve",
     "website:build": "cd website && make build",
     "website:demos": "cd website/demos && ./build-demos.sh",
+    "serve": "bun src/index.ts serve",
+    "serve:dev": "NODE_ENV=development bun --hot src/index.ts serve",
     "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",
@@ -65,18 +67,44 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "ai": "^6.0.5",
+    "bun-plugin-tailwind": "^0.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
     "commander": "^14.0.2",
+    "embla-carousel-react": "^8.6.0",
     "franc": "^6.2.0",
+    "lucide-react": "^0.562.0",
     "markitdown-ts": "^0.0.8",
+    "nanoid": "^5.1.6",
     "node-llama-cpp": "^3.14.5",
     "officeparser": "^5.2.2",
     "picocolors": "^1.1.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "shiki": "^3.20.0",
     "sqlite-vec": "^0.1.7-alpha.2",
+    "streamdown": "^1.6.10",
+    "tailwind-merge": "^3.4.0",
+    "use-stick-to-bottom": "^1.1.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.10",
     "@types/bun": "latest",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@typescript/native-preview": "^7.0.0-dev.20251215.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -87,6 +115,7 @@
     "oxlint-tsgolint": "^0.10.0",
     "pdf-lib": "^1.17.1",
     "pptxgenjs": "^4.0.1",
+    "tailwindcss": "^4.1.18",
     "ultracite": "^6.5.0"
   },
   "peerDependencies": {