@gmickel/gno 0.3.0

package/assets/skill/examples.md

@@ -0,0 +1,234 @@
+# GNO Usage Examples
+
+Real-world examples for common tasks.
+
+## Getting Started
+
+### Index a folder of docs
+
+```bash
+# Initialize
+gno init
+
+# Add your docs folder
+gno collection add ~/Documents/work --name work
+
+# Build index
+gno index
+```
+
+### Index multiple folders
+
+```bash
+gno init
+gno collection add ~/notes --name notes --pattern "**/*.md"
+gno collection add ~/work/contracts --name contracts --pattern "**/*.{pdf,docx}"
+gno index
+```
+
+## Searching
+
+### Find by keywords
+
+```bash
+# Simple search
+gno search "quarterly report"
+
+# More results
+gno search "budget" -n 20
+
+# Filter to collection
+gno search "NDA" -c contracts
+```
+
+### Find by meaning (semantic)
+
+```bash
+# Semantic search finds related concepts
+gno vsearch "how to cancel subscription"
+
+# Even if docs say "terminate agreement"
+gno vsearch "end contract early"
+```
+
+### Best quality search
+
+```bash
+# Hybrid combines keywords + semantics + reranking
+gno query "deployment process"
+
+# See how results were found
+gno query "deployment" --explain
+```
+
+## Getting Answers
+
+### Q&A with citations
+
+```bash
+# Just retrieve relevant chunks
+gno ask "what are the payment terms"
+
+# Get an AI-generated answer
+gno ask "what are the payment terms" --answer
+```
+
+### Scoped answers
+
+```bash
+# Search only contracts
+gno ask "termination clause" -c contracts --answer
+
+# Limit answer length
+gno ask "summarize project goals" --answer --max-answer-tokens 200
+```
+
+## Reading Documents
+
+### Get full document
+
+```bash
+# By URI
+gno get gno://work/readme.md
+
+# By document ID
+gno get "#a1b2c3d4"
+
+# With line numbers
+gno get gno://notes/meeting.md --line-numbers
+```
+
+### Get specific lines
+
+```bash
+# Start at line 50
+gno get gno://work/report.md --from 50
+
+# Get 20 lines starting at 100
+gno get gno://work/report.md --from 100 -l 20
+```
+
+### List documents
+
+```bash
+# All documents
+gno ls
+
+# In a collection
+gno ls work
+
+# As JSON
+gno ls --json
+```
+
+## JSON Output (Scripting)
+
+### Search results to JSON
+
+```bash
+# Get URIs of matches
+gno search "api endpoint" --json | jq '.[] | .uri'
+
+# Get snippets
+gno search "config" --json | jq '.[] | {uri, snippet}'
+```
+
+### Check index health
+
+```bash
+# Get stats
+gno status --json | jq '{docs: .totalDocuments, chunks: .totalChunks}'
+
+# Run diagnostics
+gno doctor --json
+```
+
+### Batch processing
+
+```bash
+# Export all document IDs
+gno ls --json | jq -r '.[].docid' > doc-ids.txt
+
+# Search and process results
+gno search "error" --json | jq -r '.[] | .uri' | while read uri; do
+  echo "Processing: $uri"
+  gno get "$uri" > "output/$(basename $uri)"
+done
+```
+
+## Maintenance
+
+### Update index after changes
+
+```bash
+# Sync files from disk
+gno update
+
+# Full re-index
+gno index
+```
+
+### Git integration
+
+```bash
+# Pull and re-index
+gno index --git-pull
+
+# Useful for docs repos
+gno update --git-pull
+```
+
+### Model management
+
+```bash
+# List models and status
+gno models list
+
+# Switch to quality preset
+gno models use quality
+
+# Download models
+gno models pull
+```
+
+## Tips
+
+### Speed vs Quality
+
+| Command | Speed | Quality | Use When |
+|---------|-------|---------|----------|
+| `gno search` | Fast | Good for keywords | Exact phrase matching |
+| `gno vsearch` | Medium | Good for concepts | Finding similar meaning |
+| `gno query` | Slower | Best | Important queries |
+
+### Output formats
+
+```bash
+# Human readable (default)
+gno search "query"
+
+# JSON (scripting)
+gno search "query" --json
+
+# File list (for piping)
+gno search "query" --files
+
+# CSV (spreadsheets)
+gno search "query" --csv
+
+# Markdown (docs)
+gno search "query" --md
+```
+
+### Large result sets
+
+```bash
+# Increase limit
+gno search "common term" -n 50
+
+# Filter by score
+gno search "common term" --min-score 0.7
+
+# Get full content
+gno search "term" --full
+```

package/assets/skill/mcp-reference.md

@@ -0,0 +1,159 @@
+# GNO MCP Reference
+
+GNO provides an MCP (Model Context Protocol) server for AI integration.
+
+## Setup
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gno": {
+      "command": "gno",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Config location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### Start Server
+
+```bash
+gno mcp
+```
+
+Runs JSON-RPC 2.0 over stdio.
+
+## Tools
+
+### gno.search
+
+BM25 keyword search.
+
+```json
+{
+  "query": "search terms",
+  "collection": "optional-collection",
+  "limit": 5,
+  "minScore": 0.5,
+  "lang": "en"
+}
+```
+
+### gno.vsearch
+
+Vector semantic search. Same parameters as `gno.search`.
+
+### gno.query
+
+Hybrid search (best quality).
+
+```json
+{
+  "query": "search terms",
+  "collection": "optional-collection",
+  "limit": 5,
+  "expand": true,
+  "rerank": true
+}
+```
+
+### gno.get
+
+Retrieve document by reference.
+
+```json
+{
+  "ref": "gno://collection/path or #docid",
+  "fromLine": 1,
+  "lineCount": 100,
+  "lineNumbers": true
+}
+```
+
+### gno.multi_get
+
+Retrieve multiple documents.
+
+```json
+{
+  "refs": ["gno://work/doc1.md", "#a1b2c3d4"],
+  "maxBytes": 10240,
+  "lineNumbers": true
+}
+```
+
+Or by pattern:
+
+```json
+{
+  "pattern": "work/**/*.md",
+  "maxBytes": 10240
+}
+```
+
+### gno.status
+
+Get index status.
+
+```json
+{}
+```
+
+## Resources
+
+Documents accessible as MCP resources:
+
+```
+gno://{collection}/{path}
+```
+
+Examples:
+- `gno://work/contracts/nda.docx`
+- `gno://notes/2025/01/meeting.md`
+
+Returns Markdown content with line numbers.
+
+## Response Format
+
+All tools return:
+
+```json
+{
+  "content": [
+    { "type": "text", "text": "Human-readable summary" }
+  ],
+  "structuredContent": {
+    "results": [...],
+    "meta": { "query": "...", "mode": "hybrid" }
+  }
+}
+```
+
+## Error Handling
+
+Errors return:
+
+```json
+{
+  "isError": true,
+  "content": [
+    { "type": "text", "text": "Error: Document not found" }
+  ]
+}
+```
+
+## Graceful Degradation
+
+`gno.query` degrades gracefully:
+- No vectors → BM25 only
+- No expansion model → skips expansion
+- No rerank model → skips reranking

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@gmickel/gno",
+  "version": "0.3.0",
+  "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
+  "keywords": [
+    "search",
+    "semantic-search",
+    "rag",
+    "vector-search",
+    "embeddings",
+    "local-first",
+    "mcp",
+    "llm"
+  ],
+  "author": "Gordon Mickel <gordon@mickel.tech>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gmickel/gno.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gmickel/gno/issues"
+  },
+  "homepage": "https://gno.sh",
+  "type": "module",
+  "module": "src/index.ts",
+  "bin": {
+    "gno": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "assets"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run --hot src/index.ts",
+    "build": "bun build src/index.ts",
+    "start": "bun run src/index.ts",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:coverage:html": "bun test --coverage --html",
+    "typecheck": "tsgo --noEmit",
+    "lint:typeaware": "bun x oxlint --type-aware",
+    "reset": "bun run src/index.ts reset --confirm",
+    "docs:verify": "bun run scripts/docs-verify.ts",
+    "website:install": "cd website && bundle install",
+    "website:dev": "cd website && make serve",
+    "website:build": "cd website && make build",
+    "website:demos": "cd website/demos && ./build-demos.sh",
+    "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",
+    "prerelease": "bun run lint && bun run typecheck && bun test",
+    "release:dry-run": "gh workflow run publish.yml -f publish=false",
+    "release:trigger": "gh workflow run publish.yml -f publish=true"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "commander": "^14.0.2",
+    "franc": "^6.2.0",
+    "markitdown-ts": "^0.0.8",
+    "node-llama-cpp": "^3.14.5",
+    "officeparser": "^5.2.2",
+    "picocolors": "^1.1.1",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@types/bun": "latest",
+    "@typescript/native-preview": "^7.0.0-dev.20251215.1",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "evalite": "^1.0.0-beta.15",
+    "lefthook": "^2.0.12",
+    "oxlint-tsgolint": "^0.10.0",
+    "ultracite": "^6.5.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}