@gmickel/gno 0.9.4 → 0.9.6

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.
-allowed-tools: Bash(gno:*), Read
+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.4",
+  "version": "0.9.6",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

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 });