@gmickel/gno 0.9.3 → 0.9.5

package/README.md

@@ -332,14 +332,14 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 
 ### Model Presets
 
-| Preset     | Disk   | Best For               |
-| :--------- | :----- | :--------------------- |
-| `slim`     | ~1GB   | Fast, lower quality    |
-| `balanced` | ~2GB   | Good balance (default) |
-| `quality`  | ~2.5GB | Best answers           |
+| Preset     | Disk   | Best For                     |
+| :--------- | :----- | :--------------------------- |
+| `slim`     | ~1GB   | Fast, good quality (default) |
+| `balanced` | ~2GB   | Slightly larger model        |
+| `quality`  | ~2.5GB | Best answers                 |
 
 ```bash
-gno models use balanced
+gno models use slim
 gno models pull --all  # Optional: pre-download models (auto-downloads on first use)
 ```
 

package/assets/skill/SKILL.md

@@ -1,25 +1,27 @@
 ---
 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.
+description: Search local documents, files, notes, and knowledge bases. Index directories, search with BM25/vector/hybrid, get AI answers with citations. Use when user wants to search files, find documents, query notes, look up information in local folders, index a directory, set up document search, build a knowledge base, needs RAG/semantic search, or wants to start a local web UI for their docs.
 allowed-tools: Bash(gno:*), Read
 ---
 
-# GNO - Local Document Search
+# GNO - Local Knowledge Engine
 
-Fast local semantic search for your documents. Index once, search instantly.
+Fast local semantic search for your documents. Index once, search instantly. No cloud, no API keys.
 
-**Role**: document search assistant
-**Goal**: help users index, search, and query their documents
+**Role**: Document search and knowledge retrieval assistant
+**Goal**: Help users index, search, query, and get answers from their local 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 mentions **PDFs, markdown, Word docs, code** 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
+- User wants a **web UI** to browse/search documents
+- User asks to **get AI answers** from their documents
 
 ## Quick Start
 
@@ -39,6 +41,52 @@ gno search "your query"
 
 ## Core Commands
 
+### Search Commands
+
+| Command               | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `gno search <query>`  | BM25 keyword search (fast, exact terms)     |
+| `gno vsearch <query>` | Vector semantic search (meaning-based)      |
+| `gno query <query>`   | Hybrid search (BM25 + vector + rerank)      |
+| `gno ask <question>`  | Get AI answer with citations from your docs |
+
+### Search Options
+
+```bash
+# Limit results
+gno search "api" -n 10
+
+# Filter by collection
+gno query "auth" --collection work
+
+# Search modes (for query/ask)
+gno query "topic" --fast       # ~0.7s, skip expansion/rerank
+gno query "topic"              # ~2-3s, default with rerank
+gno query "topic" --thorough   # ~5-8s, full pipeline
+
+# Get AI answer
+gno ask "how does auth work" --answer
+
+# Output formats
+gno search "test" --json       # JSON for parsing
+gno search "test" --files      # URIs for piping
+```
+
+### Document Retrieval
+
+| Command                   | Description                  |
+| ------------------------- | ---------------------------- |
+| `gno get <ref>`           | Get document by URI or docid |
+| `gno multi-get <refs...>` | Get multiple documents       |
+| `gno ls [scope]`          | List indexed documents       |
+
+```bash
+gno get gno://work/readme.md
+gno get "#a1b2c3d4" --line-numbers
+gno ls notes
+gno ls --json
+```
+
 ### Indexing
 
 | Command                                   | Description                         |
@@ -47,62 +95,146 @@ gno search "your query"
 | `gno collection add <path> --name <name>` | Add folder to index                 |
 | `gno index`                               | Full index (ingest + embed)         |
 | `gno update`                              | Sync files without embedding        |
+| `gno embed`                               | Generate embeddings only            |
+
+```bash
+gno init
+gno collection add ~/notes --name notes --pattern "**/*.md"
+gno index
+gno index --collection notes  # Single collection
+```
+
+### Model Management
+
+| Command            | Description                           |
+| ------------------ | ------------------------------------- |
+| `gno models list`  | Show available model presets          |
+| `gno models use`   | Switch preset (slim/balanced/quality) |
+| `gno models pull`  | Download models                       |
+| `gno models clear` | Remove cached models                  |
+| `gno models path`  | Show model cache directory            |
+
+```bash
+gno models use slim       # Default, fast (~1GB)
+gno models use balanced   # Larger model (~2GB)
+gno models use quality    # Best answers (~2.5GB)
+gno models pull --all
+```
+
+### Context Hints
 
-### Searching
+| Command                          | Description            |
+| -------------------------------- | ---------------------- |
+| `gno context add <scope> "text"` | Add context for scope  |
+| `gno context list`               | List all contexts      |
+| `gno context check`              | Validate configuration |
+| `gno context rm <scope>`         | Remove a context       |
 
-| 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          |
+```bash
+gno context add "/" "Corporate knowledge base"
+gno context add "work:" "Work documents and contracts"
+```
 
-### Common Options
+### Web UI
 
-- `-n <num>` — Max results (default: 5)
-- `-c, --collection <name>` — Filter to collection
-- `--json` — JSON output
-- `--full` — Include full content (not snippets)
+| Command             | Description              |
+| ------------------- | ------------------------ |
+| `gno serve`         | Start web UI (port 3000) |
+| `gno serve -p 8080` | Custom port              |
 
-## Usage Patterns
+Features: Dashboard, search, browse, document editor, AI Q&A with citations.
 
-### Search & Retrieve
+### MCP Server
+
+| Command             | Description                     |
+| ------------------- | ------------------------------- |
+| `gno mcp`           | Start MCP server (stdio)        |
+| `gno mcp install`   | Install for Claude Desktop, etc |
+| `gno mcp uninstall` | Remove MCP configuration        |
+| `gno mcp status`    | Show installation status        |
 
 ```bash
-# Keyword search
-gno search "termination clause" -n 10
+gno mcp install --target claude-desktop
+gno mcp install --target cursor
+gno mcp install --target claude-code --scope project
+```
 
-# Semantic search (similar meaning)
-gno vsearch "how to cancel contract"
+### Skill Management
 
-# Hybrid search (best quality)
-gno query "deployment process" --collection work
+| Command               | Description                 |
+| --------------------- | --------------------------- |
+| `gno skill install`   | Install skill for AI agents |
+| `gno skill uninstall` | Remove skill                |
+| `gno skill show`      | Preview skill files         |
+| `gno skill paths`     | Show installation paths     |
 
-# Get answer with citations
-gno ask "what are the payment terms"
+```bash
+gno skill install --target claude --scope project
+gno skill install --target codex --scope user
 ```
 
-### Inspect Documents
+### Admin Commands
+
+| Command          | Description                   |
+| ---------------- | ----------------------------- |
+| `gno status`     | Show index status             |
+| `gno doctor`     | Check system health           |
+| `gno cleanup`    | Remove orphaned data          |
+| `gno reset`      | Delete all data (use caution) |
+| `gno completion` | Shell tab completion          |
 
 ```bash
-# Get document by URI
-gno get gno://docs/readme.md
+gno status --json
+gno doctor
+gno completion install
+```
 
-# Get with line numbers
-gno get "#a1b2c3d4" --line-numbers
+## Global Flags
 
-# List documents
-gno ls docs
 ```
+--index <name>    Use alternate index (default: "default")
+--config <path>   Override config file path
+--no-color        Disable colored output
+--no-pager        Disable automatic paging
+--verbose         Enable verbose logging
+--yes             Non-interactive mode
+--offline         Use cached models only
+--json            JSON output (where supported)
+```
+
+## Common Patterns
 
-### JSON Output (for scripts)
+### Search & Get Full Content
 
 ```bash
-# Search results as JSON
-gno search "api" --json | jq '.[] | .uri'
+# Find documents, get full content
+gno search "api design" --files | head -1 | cut -d, -f3 | xargs gno get
 
-# Status check
-gno status --json
+# JSON pipeline
+gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get
+```
+
+### AI-Powered Q&A
+
+```bash
+# Get answer with sources
+gno ask "what are the deployment steps" --answer
+
+# Show all retrieved sources
+gno ask "summarize the auth discussion" --answer --show-sources
+```
+
+### Scripting
+
+```bash
+# Check if indexed
+gno status --json | jq '.healthy'
+
+# List all URIs
+gno ls --files
+
+# Batch get
+gno multi-get abc123 def456 ghi789 --max-bytes 10000
 ```
 
 ## Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -48,6 +48,9 @@
     "test:coverage": "bun test --coverage",
     "test:coverage:html": "bun test --coverage --html",
     "test:fixtures": "bun scripts/generate-test-fixtures.ts",
+    "evals": "bun scripts/update-eval-scores.ts",
+    "eval": "bun --bun evalite",
+    "eval:watch": "bun --bun evalite watch",
     "reset": "bun run src/index.ts reset --confirm",
     "docs:verify": "bun run scripts/docs-verify.ts",
     "website:install": "cd website && bundle install",
@@ -110,6 +113,7 @@
     "zod": "^4.3.4"
   },
   "devDependencies": {
+    "@ai-sdk/openai": "^3.0.2",
     "@biomejs/biome": "2.3.10",
     "@tailwindcss/cli": "^4.1.18",
     "@types/bun": "latest",
@@ -126,7 +130,8 @@
     "oxlint-tsgolint": "^0.10.1",
     "pdf-lib": "^1.17.1",
     "pptxgenjs": "^4.0.1",
-    "ultracite": "7.0.4"
+    "ultracite": "7.0.4",
+    "vitest": "^4.0.16"
   },
   "peerDependencies": {
     "typescript": "^5"

package/src/cli/run.ts

@@ -6,6 +6,8 @@
  */
 
 import { CommanderError } from "commander";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { CLI_NAME, PRODUCT_NAME } from "../app/constants";
 import { CliError, exitCodeFor, formatErrorForOutput } from "./errors";
@@ -54,6 +56,32 @@ function isKnownValueFlag(arg: string): boolean {
   return false;
 }
 
+/**
+ * Check if --skill flag is present in argv (before end-of-options marker).
+ */
+function argvWantsSkill(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === "--") {
+      break;
+    }
+    if (arg === "--skill") {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Output SKILL.md content for agent discovery.
+ * Clean output with no extra text (suitable for piping/parsing).
+ */
+async function printSkillFile(): Promise<void> {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const skillPath = join(__dirname, "../../assets/skill/SKILL.md");
+  const content = await Bun.file(skillPath).text();
+  process.stdout.write(content);
+}
+
 /**
  * Check if argv has no subcommand (only known global flags).
  * Returns true for: gno, gno --json, gno --quiet --verbose
@@ -146,6 +174,12 @@ export async function runCli(argv: string[]): Promise<number> {
 
   const isJson = argvWantsJson(argv);
 
+  // Handle --skill flag: output SKILL.md for agent discovery
+  if (argvWantsSkill(argv)) {
+    await printSkillFile();
+    return 0;
+  }
+
   // Handle "no subcommand" case before Commander (avoids full help display)
   if (hasNoSubcommand(argv)) {
     printConciseHelp({ json: isJson });

package/src/config/types.ts

@@ -176,7 +176,7 @@ export type ModelPreset = z.infer<typeof ModelPresetSchema>;
 export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
   {
     id: "slim",
-    name: "Slim (Fast, ~1GB)",
+    name: "Slim (Default, ~1GB)",
     embed: "hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf",
     rerank:
       "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf",
@@ -184,11 +184,11 @@ export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
   },
   {
     id: "balanced",
-    name: "Balanced (Default, ~2GB)",
+    name: "Balanced (~2GB)",
     embed: "hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf",
     rerank:
       "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf",
-    gen: "hf:ggml-org/SmolLM3-3B-GGUF/SmolLM3-Q4_K_M.gguf",
+    gen: "hf:bartowski/Qwen2.5-3B-Instruct-GGUF/Qwen2.5-3B-Instruct-Q4_K_M.gguf",
   },
   {
     id: "quality",
@@ -202,7 +202,7 @@ export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
 
 export const ModelConfigSchema = z.object({
   /** Active preset ID */
-  activePreset: z.string().default("balanced"),
+  activePreset: z.string().default("slim"),
   /** Model presets */
   presets: z.array(ModelPresetSchema).default(DEFAULT_MODEL_PRESETS),
   /** Model load timeout in ms */

package/src/llm/registry.ts

@@ -19,7 +19,7 @@ import { DEFAULT_MODEL_PRESETS } from "../config/types";
  */
 export function getModelConfig(config: Config): ModelConfig {
   return {
-    activePreset: config.models?.activePreset ?? "balanced",
+    activePreset: config.models?.activePreset ?? "slim",
     presets: config.models?.presets?.length
       ? config.models.presets
       : DEFAULT_MODEL_PRESETS,

package/src/pipeline/answer.ts

@@ -13,21 +13,24 @@ import type { Citation, SearchResult } from "./types";
 // Constants
 // ─────────────────────────────────────────────────────────────────────────────
 
-const ANSWER_PROMPT = `You are answering a question using ONLY the provided context blocks.
+const ANSWER_PROMPT = `Answer the question using ONLY the context blocks below. Cite sources with [1], [2], etc.
 
-Rules you MUST follow:
-1) Use ONLY facts stated in the context blocks. Do NOT use outside knowledge.
-2) Every factual statement must include an inline citation like [1] or [2] referring to a context block.
-3) If the context does not contain enough information to answer, reply EXACTLY:
-   "I don't have enough information in the provided sources to answer this question."
-4) Do not cite sources you did not use. Do not invent citation numbers.
+Example:
+Q: What is the capital of France?
+Context:
+[1] France is a country in Western Europe. Paris is the capital and largest city.
+[2] The Eiffel Tower, built in 1889, is located in Paris.
 
-Question: {query}
+Answer: Paris is the capital of France [1]. It is home to the Eiffel Tower [2].
 
-Context blocks:
+---
+
+Q: {query}
+
+Context:
 {context}
 
-Write a concise answer (1-3 paragraphs).`;
+Answer:`;
 
 /** Abstention message when LLM cannot ground answer */
 export const ABSTENTION_MESSAGE =

package/src/pipeline/search.ts

@@ -223,7 +223,11 @@ export async function searchBm25(
 
   // For --full, fetch full content and build results
   if (options.full) {
-    for (const { fts, chunk } of bestByDocid.values()) {
+    // Sort by raw BM25 score (smaller = better) before building results
+    const sortedEntries = [...bestByDocid.values()].sort(
+      (a, b) => a.score - b.score
+    );
+    for (const { fts, chunk } of sortedEntries) {
       let fullContent: string | undefined;
       if (fts.mirrorHash) {
         const contentResult = await store.getContent(fts.mirrorHash);