@gmickel/gno 0.3.0

package/README.md

@@ -0,0 +1,256 @@
+# GNO: Your Local Second Brain
+
+**Index, Search, and Synthesize Your Entire Digital Life.**
+
+GNO is a **Local Knowledge Engine** designed for privacy-conscious individuals and AI agents. It indexes your notes, code, documents (Markdown, PDF, Office, and more), and meeting transcripts, providing lightning-fast semantic search and AI-powered answers—all on your machine.
+
+---
+
+## ✨ Key Features
+
+*   **Universal Indexing**: Effortlessly ingest and search across Markdown, PDF, DOCX, XLSX, PPTX, and plain text files.
+*   **Hybrid Search Pipeline**: Combines **BM25 keyword search** with **vector semantic search** and **AI re-ranking** for unparalleled retrieval accuracy.
+*   **Local LLM Integration**: Get grounded AI answers with citations using **node-llama-cpp** and auto-downloaded GGUF models. No external services, maximum privacy.
+*   **Agent-First Design (MCP)**: Seamlessly integrate GNO with AI agents via the Model Context Protocol (MCP) server.
+*   **Deterministic Output**: Stable, schema-driven JSON, file-line, and markdown outputs for reliable scripting.
+*   **Multilingual Support**: Robust handling of multiple languages in indexing and retrieval.
+*   **Privacy-Preserving**: All processing happens locally. Your data never leaves your device.
+*   **World-Class Engineering**: Spec-driven development, rigorous testing, and eval gates ensure reliability and quality.
+
+---
+
+## 🚀 Quick Start
+
+Get searching in minutes with the 3-command workflow:
+
+1.  **Initialize your knowledge base**:
+    ```sh
+    # Create a collection for your notes (adjust path and name as needed)
+    gno init ~/my-notes --name notes --pattern "**/*.md"
+
+    # Full index: sync files + generate embeddings
+    gno index
+    ```
+
+2.  **Ask a question**:
+    ```sh
+    # Get a direct, cited answer from your documents
+    gno ask "What are the best practices for API authentication?" --collection notes
+
+    # Search with keywords or natural language
+    gno query "Q4 planning meeting summary" --collection notes
+    ```
+
+3.  **Explore your data**:
+    ```sh
+    # Retrieve specific document content
+    gno get "notes/2024-01-15.md"
+
+    # Get results in a machine-readable format for agents
+    gno search "project deadlines" --json -n 10
+    ```
+
+---
+
+## 🧠 For Humans & AI Agents
+
+GNO is built for both worlds:
+
+*   **For Humans**: A powerful, yet intuitive CLI to quickly find information, get answers, and explore your local knowledge base.
+*   **For AI Agents**: Exposes a stable MCP server and structured output formats (`--json`, `--files`) for seamless integration with LLMs and agentic workflows.
+
+---
+
+## 🔎 Search Modes
+
+GNO offers multiple search strategies to suit your needs:
+
+| Command     | Mode           | Description                                                     | Best For                                         |
+| :---------- | :------------- | :-------------------------------------------------------------- | :----------------------------------------------- |
+| `gno search`| **BM25**       | Fast, keyword-based full-text search.                           | Exact phrase matching, known terms.              |
+| `gno vsearch`| **Vector**     | Semantic search based on meaning, not just keywords.            | Natural language queries, conceptual understanding. |
+| `gno query` | **Hybrid**     | Combines BM25 and Vector search with LLM reranking and fusion.  | Highest accuracy, nuanced understanding.         |
+| `gno ask`   | **RAG-focused**| Hybrid search providing a synthesized, cited answer from results. | Getting direct answers to complex questions.     |
+
+---
+
+## 🤖 Agent Integration
+
+GNO is designed to be the knowledge backbone for your AI agents.
+
+### CLI Output Formats
+
+Use `--json` or `--files` for machine-readable output:
+
+```sh
+# Get JSON results for LLM processing
+gno query "meeting notes on user feedback" --json -n 5
+
+# Get file paths and scores for agent tool use
+gno search "API design" --files --min-score 0.3
+```
+
+### Skill Installation (Recommended for Claude Code/Codex/OpenCode)
+
+Skills integrate via CLI - the agent runs GNO commands directly. No MCP overhead, no context pollution.
+
+```bash
+gno skill install --scope user    # User-wide for Claude Code
+gno skill install --target codex  # For Codex
+gno skill install --target all    # Both
+```
+
+After install, restart your agent. It will detect GNO and can search your indexed documents.
+
+### MCP Server (For Claude Desktop/Cursor)
+
+Exposes an MCP server for GUI-based AI applications.
+
+**Tools Exposed:**
+*   `gno_search` (BM25)
+*   `gno_vsearch` (Vector)
+*   `gno_query` (Hybrid)
+*   `gno_get` (Document retrieval)
+*   `gno_multi_get` (Batch retrieval)
+*   `gno_status` (Index health)
+
+**Example Claude Desktop Configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gno": {
+      "command": "gno",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+*(Adjust path and `mcpServers` key based on your agent's configuration.)*
+
+---
+
+## ⚙️ How It Works: The GNO Pipeline
+
+GNO employs a sophisticated, multi-stage retrieval process for optimal results:
+
+```mermaid
+graph TD
+    A[User Query] --> B(Query Expansion);
+    B --> C{Lexical Variants};
+    B --> D{Semantic Variants};
+    B --> E{Optional HyDE};
+    A --> F[Original Query];
+
+    C --> G(BM25 Retrieval);
+    D --> H(Vector Search);
+    E --> H;
+    F --> G;
+    F --> H;
+
+    G --> I(Ranked List 1);
+    H --> J(Ranked List 2);
+    I --> K{RRF Fusion + Bonus};
+    J --> K;
+
+    K --> L(Top Candidates);
+    L --> M(LLM Re-ranking);
+    M --> N(Position-Aware Blending);
+    N --> O(Final Results);
+
+    subgraph "Search Stages"
+        B; C; D; E; F; G; H; I; J; K; L; M; N; O;
+    end
+```
+
+### Search Pipeline Details:
+
+1.  **Query Expansion**: Generates alternative queries (lexical and semantic) and an optional synthetic "HyDE" document using a local LLM for richer retrieval.
+2.  **Parallel Retrieval**: Executes BM25 (keyword) and Vector (semantic) searches concurrently.
+3.  **Fusion**: Combines results using Reciprocal Rank Fusion (RRF) with a weighted boost for original query matches and a top-rank bonus.
+4.  **Re-ranking**: An LLM-based cross-encoder re-scores the top candidates for final relevance.
+5.  **Blending**: Dynamically adjusts the mix of retrieval vs. reranked scores based on rank position to preserve accuracy.
+
+**Score Normalization**: Raw scores from FTS, vector distance, and reranker are normalized to a 0-1 scale for consistent fusion.
+
+---
+
+## 📦 Installation
+
+Requires **Bun** >= 1.0.0.
+
+```sh
+# Install globally
+bun install -g @gmickel/gno
+```
+
+**macOS users**: For optimal vector search performance, install Homebrew SQLite:
+```sh
+brew install sqlite3
+```
+
+Verify your installation:
+```sh
+gno doctor
+```
+
+---
+
+## 🏠 Local LLM Models
+
+GNO runs embeddings, reranking, and query expansion locally using GGUF models via `node-llama-cpp`. Models are automatically downloaded and cached on first use in `~/.cache/gno/models/`.
+
+| Model                 | Purpose           | Size (approx.) |
+| :-------------------- | :---------------- | :------------- |
+| `bge-m3`              | Multilingual Embeddings | ~500MB         |
+| `bge-reranker-v2-m3`  | Cross-Encoder Re-ranking | ~700MB         |
+| `Qwen-Instruct`       | Query Expansion / HyDE | ~600MB         |
+
+*(Specific GGUF versions are pinned for stability.)*
+
+---
+
+## 📜 Architecture Overview
+
+GNO follows a layered, Ports and Adapters architecture for maintainability and testability:
+
+```
+┌───────────────────────────────────────────────────────────┐
+│                       GNO CLI / MCP                       │
+├───────────────────────────────────────────────────────────┤
+│ Ports: Converter, Store, Embedding, Generation, Rerank... │
+├───────────────────────────────────────────────────────────┤
+│ Adapters: SQLite, FTS5, sqlite-vec, node-llama-cpp, CLI   │
+├───────────────────────────────────────────────────────────┤
+│ Core Domain: Identity, Mirrors, Chunking, Retrieval       │
+└───────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 💻 Development
+
+```bash
+# Clone the repository
+git clone https://github.com/gmickel/gno.git
+cd gno
+
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Lint and format code
+bun run lint
+
+# Type check
+bun run typecheck
+```
+
+---
+
+## 📄 License
+
+[MIT License](./LICENSE)

package/assets/skill/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: gno
+description: Search local documents, files, notes, and knowledge bases. Supports PDFs, Markdown, Word docs, code files. Use when user wants to search files, find documents, query their notes, look up information in local folders, index a directory, set up document search, build a knowledge base, or needs RAG/semantic search over their files.
+allowed-tools: Bash(gno:*), Read
+---
+
+# GNO - Local Document Search
+
+Fast local semantic search for your documents. Index once, search instantly.
+
+**Role**: document search assistant
+**Goal**: help users index, search, and query their documents
+
+## When to Use This Skill
+
+- User asks to **search files, documents, or notes**
+- User wants to **find information** in local folders
+- User needs to **index a directory** for searching
+- User mentions **PDFs, markdown, docs** they want to search
+- User asks about **knowledge base** or **RAG** setup
+- User wants **semantic/vector search** over their files
+- User needs to **set up MCP** for document access
+
+## Quick Start
+
+```bash
+# 1. Initialize in any directory
+gno init
+
+# 2. Add a collection (folder of docs)
+gno collection add ~/docs --name docs
+
+# 3. Index documents
+gno index
+
+# 4. Search
+gno search "your query"
+```
+
+## Core Commands
+
+### Indexing
+
+| Command | Description |
+|---------|-------------|
+| `gno init` | Initialize GNO in current directory |
+| `gno collection add <path> --name <name>` | Add folder to index |
+| `gno index` | Full index (ingest + embed) |
+| `gno update` | Sync files without embedding |
+
+### Searching
+
+| Command | Description |
+|---------|-------------|
+| `gno search <query>` | BM25 keyword search |
+| `gno vsearch <query>` | Vector semantic search |
+| `gno query <query>` | Hybrid search (BM25 + vector + rerank) |
+| `gno ask <question>` | AI-powered Q&A with citations |
+
+### Common Options
+
+- `-n <num>` — Max results (default: 5)
+- `-c, --collection <name>` — Filter to collection
+- `--json` — JSON output
+- `--full` — Include full content (not snippets)
+
+## Usage Patterns
+
+### Search & Retrieve
+
+```bash
+# Keyword search
+gno search "termination clause" -n 10
+
+# Semantic search (similar meaning)
+gno vsearch "how to cancel contract"
+
+# Hybrid search (best quality)
+gno query "deployment process" --collection work
+
+# Get answer with citations
+gno ask "what are the payment terms"
+```
+
+### Inspect Documents
+
+```bash
+# Get document by URI
+gno get gno://docs/readme.md
+
+# Get with line numbers
+gno get "#a1b2c3d4" --line-numbers
+
+# List documents
+gno ls docs
+```
+
+### JSON Output (for scripts)
+
+```bash
+# Search results as JSON
+gno search "api" --json | jq '.[] | .uri'
+
+# Status check
+gno status --json
+```
+
+## Reference
+
+For complete CLI details, see [cli-reference.md](cli-reference.md).
+For MCP server setup, see [mcp-reference.md](mcp-reference.md).
+For usage examples, see [examples.md](examples.md).

package/assets/skill/cli-reference.md

@@ -0,0 +1,327 @@
+# GNO CLI Reference
+
+Complete command reference for GNO.
+
+## Global Flags
+
+All commands accept:
+
+| Flag | Description |
+|------|-------------|
+| `--index <name>` | Use alternate index (default: "default") |
+| `--config <path>` | Override config file path |
+| `--no-color` | Disable colored output |
+| `--verbose` | Enable verbose logging |
+| `--yes` | Non-interactive mode |
+| `--json` | JSON output (where supported) |
+
+## Initialization
+
+### gno init
+
+```bash
+gno init [<path>] [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--name <name>` | Collection name |
+| `--pattern <glob>` | File pattern (default: `**/*`) |
+| `--include <exts>` | Extension allowlist (e.g., `.md,.pdf`) |
+| `--exclude <paths>` | Exclude patterns (default: `.git,node_modules`) |
+| `--tokenizer <type>` | FTS tokenizer: unicode61, porter, trigram |
+| `--language <code>` | BCP-47 language hint |
+
+## Collections
+
+### gno collection add
+
+```bash
+gno collection add <path> --name <name> [options]
+```
+
+Options same as `init`.
+
+### gno collection list
+
+```bash
+gno collection list [--json|--md]
+```
+
+### gno collection remove
+
+```bash
+gno collection remove <name>
+```
+
+### gno collection rename
+
+```bash
+gno collection rename <old> <new>
+```
+
+## Indexing
+
+### gno update
+
+Sync files from disk (no embedding).
+
+```bash
+gno update [--git-pull]
+```
+
+### gno index
+
+Full index (update + embed).
+
+```bash
+gno index [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--collection <name>` | Scope to single collection |
+| `--no-embed` | Skip embedding |
+| `--models-pull` | Download models if missing |
+| `--git-pull` | Git pull before indexing |
+
+### gno embed
+
+Generate embeddings only.
+
+```bash
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
+```
+
+## Search Commands
+
+### gno search
+
+BM25 keyword search.
+
+```bash
+gno search <query> [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-n` | 5 | Max results |
+| `--min-score` | 0 | Minimum score (0-1) |
+| `-c, --collection` | all | Filter to collection |
+| `--full` | false | Full content (not snippets) |
+| `--line-numbers` | false | Include line numbers |
+| `--lang` | auto | Language filter |
+
+Output formats: `--json`, `--files`, `--csv`, `--md`, `--xml`
+
+### gno vsearch
+
+Vector semantic search. Same options as `search`.
+
+```bash
+gno vsearch <query> [options]
+```
+
+### gno query
+
+Hybrid search with expansion and reranking.
+
+```bash
+gno query <query> [options]
+```
+
+Additional options:
+
+| Option | Description |
+|--------|-------------|
+| `--no-expand` | Disable query expansion |
+| `--no-rerank` | Disable reranking |
+| `--explain` | Print retrieval details to stderr |
+
+### gno ask
+
+AI-powered Q&A with citations.
+
+```bash
+gno ask <question> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--answer` | Generate grounded answer |
+| `--no-answer` | Retrieval only |
+| `--max-answer-tokens <n>` | Cap answer length |
+| `--show-sources` | Show all sources |
+
+## Document Retrieval
+
+### gno get
+
+Get single document.
+
+```bash
+gno get <ref> [--from <line>] [-l <lines>] [--line-numbers] [--source]
+```
+
+Ref formats:
+- `gno://collection/path` — Full URI
+- `collection/path` — Relative path
+- `#docid` — Document ID
+- `gno://docs/file.md:120` — With line number
+
+### gno multi-get
+
+Get multiple documents.
+
+```bash
+gno multi-get <pattern> [--max-bytes <n>] [--line-numbers]
+```
+
+### gno ls
+
+List documents.
+
+```bash
+gno ls [<scope>] [--json|--files|--md]
+```
+
+## Context Management
+
+### gno context add
+
+```bash
+gno context add <scope> "<text>"
+```
+
+Scope formats:
+- `/` — Global
+- `collection:` — Collection prefix
+- `gno://collection/path` — Path prefix
+
+### gno context list
+
+```bash
+gno context list [--json|--md]
+```
+
+### gno context rm
+
+```bash
+gno context rm <scope>
+```
+
+## Models
+
+### gno models list
+
+```bash
+gno models list [--json|--md]
+```
+
+### gno models use
+
+```bash
+gno models use <preset>
+```
+
+Presets: `slim` (~1GB), `balanced` (~2GB), `quality` (~2.5GB)
+
+### gno models pull
+
+```bash
+gno models pull [--all|--embed|--rerank|--gen] [--force]
+```
+
+### gno models clear
+
+```bash
+gno models clear [--all|--embed|--rerank|--gen]
+```
+
+### gno models path
+
+```bash
+gno models path [--json]
+```
+
+## Maintenance
+
+### gno status
+
+```bash
+gno status [--json|--md]
+```
+
+### gno doctor
+
+```bash
+gno doctor [--json|--md]
+```
+
+### gno cleanup
+
+```bash
+gno cleanup
+```
+
+## MCP Server
+
+### gno mcp
+
+Start MCP server (stdio transport).
+
+```bash
+gno mcp
+```
+
+### gno mcp install
+
+Install GNO as MCP server in client configurations.
+
+```bash
+gno mcp install [options]
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-t, --target` | claude-desktop | Target: `claude-desktop`, `claude-code`, `codex` |
+| `-s, --scope` | user | Scope: `user`, `project` |
+| `-f, --force` | false | Overwrite existing config |
+| `--dry-run` | false | Preview changes |
+
+Examples:
+
+```bash
+# Claude Desktop (default)
+gno mcp install
+
+# Claude Code (user scope)
+gno mcp install -t claude-code
+
+# Claude Code (project scope)
+gno mcp install -t claude-code -s project
+```
+
+### gno mcp uninstall
+
+Remove GNO MCP server from client configuration.
+
+```bash
+gno mcp uninstall [-t <target>] [-s <scope>]
+```
+
+### gno mcp status
+
+Show MCP installation status.
+
+```bash
+gno mcp status [--json]
+```
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| 0 | Success |
+| 1 | Validation error (bad args) |
+| 2 | Runtime error (IO, DB, model) |