Skill: gmickel/gno (version 1.2.0)

--- name: gno 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 Knowledge Engine Fast local semantic search. Index once, search instantly. No cloud, no API keys. ## 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, Word docs, code** 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 - User wants to **tag, categorize, or filter** documents - User asks about **backlinks, wiki links, or related notes** - User wants to **visualize document connections** or see a **knowledge graph** - User wants to **export a note or collection for gno.sh publishing** ## Quick Start ```bash gno init # Initialize in current directory gno collection add ~/docs --name docs # Add folder to index gno index # Build index (ingest + embed) gno search "your query" # BM25 keyword search ``` ## Command Overview | Category | Commands | Description | | ------------ | ---------------------------------------------------------------- | --------------------------------------------------------- | | **Search** | `search`, `vsearch`, `query`, `ask` | Find documents by keywords, meaning, or get AI answers | | **Links** | `links`, `backlinks`, `similar`, `graph` | Navigate document relationships and visualize connections | | **Retrieve** | `get`, `multi-get`, `ls` | Fetch document content by URI or ID | | **Index** | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index | | **Tags** | `tags`, `tags add`, `tags rm` | Organize and filter documents | | **Context** | `context add/list/rm/check` | Add hints to improve search relevance | | **Models** | `models list/use/pull/clear/path` | Manage local AI models | | **Serve** | `serve` | Web UI for browsing and searching | | **Publish** | `publish export` | Export gno.sh publish artifacts | | **MCP** | `mcp`, `mcp install/uninstall/status` | AI assistant integration | | **Skill** | `skill install/uninstall/show/paths` | Install skill for AI agents | | **Admin** | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion` | Maintenance and diagnostics | ## Search Modes | Command | Speed | Best For | | ---------------------- | ------- | ---------------------------------- | | `gno search` | instant | Exact keyword matching | | `gno vsearch` | ~0.5s | Finding similar concepts | | `gno query --fast` | ~0.7s | Quick lookups | | `gno query` | ~2-3s | Balanced (default) | | `gno query --thorough` | ~5-8s | Best recall, complex queries | | `gno ask --answer` | ~3-5s | AI-generated answer with citations | **Retry strategy**: Use default first. If no results: rephrase query, then try `--thorough`. ## Common Flags (search/vsearch/query/ask) ``` -n <num> Max results (default: 5) -c, --collection Filter to collection --tags-any <t1,t2> Has ANY of these tags --tags-all <t1,t2> Has ALL of these tags --since <date> Modified after date (ISO: 2026-03-01) --until <date> Modified before date (ISO: 2026-03-31) --exclude <terms> Exclude docs containing any term (comma-separated) --intent <text> Disambiguate ambiguous queries (e.g. "python" = language not snake) --json JSON output --files URI list output --line-numbers Include line numbers ``` ## Advanced: Structured Query Modes (query/ask only) Use `--query-mode` to combine multiple retrieval strategies in one query (repeatable): ```bash # Combine keyword + hypothetical document gno query "API rate limiting" \ --query-mode "term:rate limit" \ --query-mode "hyde:how to implement request throttling" # Add intent steering gno query "python" \ --query-mode "term:python" \ --query-mode "intent:programming language" ``` Modes: `term:<text>` (keyword), `intent:<text>` (disambiguation), `hyde:<text>` (hypothetical doc for semantic matching). Max one hyde per query. ## Document Retrieval ```bash # Full document by URI gno get gno://work/readme.md # By document ID gno get "#a1b2c3d4" # Specific line range: --from <start> -l <count> gno get gno://work/report.md --from 100 -l 20 # With line numbers gno get gno://work/report.md --line-numbers # JSON output with capabilities metadata gno get gno://work/report.md --json # Multiple documents gno multi-get gno://work/doc1.md gno://work/doc2.md ``` **Editable vs read-only**: `gno get --json` returns a `capabilities` field showing whether a document is editable at its source. Markdown and plain text files are editable in place. Converted documents (PDF, DOCX, XLSX) are read-only -- to edit their content, create a new markdown note instead of overwriting the binary source. ## Search Then Get (common pipeline) ```bash # Search, get full content of top result gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get # Get all results gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-get ``` ## Document Links & Similarity ```bash # Outgoing links from a document gno links gno://notes/readme.md # Find documents linking TO a document (backlinks) gno backlinks gno://notes/api-design.md # Find semantically similar documents gno similar gno://notes/auth.md # Similar across all collections (not just same collection) gno similar gno://notes/auth.md --cross-collection # Stricter threshold (default: 0.7) gno similar gno://notes/auth.md --threshold 0.85 # Knowledge graph gno graph --json gno graph -c notes --similar # Include similarity edges ``` ## Global Flags ``` --index <name> Alternate index (default: "default") --config <path> Override config file --verbose Verbose logging --json JSON output --yes Non-interactive mode --offline Use cached models only --no-color Disable colors --no-pager Disable paging ``` ## Important: Embedding After Changes If you edit/create files that should be searchable via vector search: ```bash gno index # Full re-index (sync + embed) # or gno embed # Embed only (if already synced) gno embed travel # Embed one collection only # or gno embed --collection travel ``` MCP `gno.sync` and `gno.capture` do NOT auto-embed. Use CLI for embedding. ## Collection-specific embedding models Collections can override the global embedding model with `models.embed`. CLI path: ```bash gno collection add ~/work/gno/src \ --name gno-code \ --embed-model "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" ``` Good default guidance: - keep the global preset for mixed notes/docs collections - use a collection-specific embed override for code-heavy collections when benchmark guidance says so - after changing an embed model on an existing populated collection, run: ```bash gno embed --collection gno-code ``` If you want to remove old vectors after switching: ```bash gno collection clear-embeddings gno-code # stale models only gno collection clear-embeddings gno-code --all # remove everything, then re-embed ``` MCP-equivalent write tool: - `gno_clear_collection_embeddings` ## Reference Documentation | Topic | File | | ----------------------------------------------------- | ------------------------------------ | | Complete CLI reference (all commands, options, flags) | [cli-reference.md](cli-reference.md) | | MCP server setup and tools | [mcp-reference.md](mcp-reference.md) | | Usage examples and patterns | [examples.md](examples.md) |

path: examples.md
content: # 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
```

## Search & Retrieve Full Content

### Pipeline: Search then get

```bash
# Find documents, get full content of top result
gno search "api design" --files | head -1 | cut -d, -f3 | xargs gno get

# JSON pipeline - get first result's full content
gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get

# Get multiple results
gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-get
```

## 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
```

## Note Linking

### View outgoing links

```bash
# List all links from a document
gno links gno://notes/readme.md

# Filter by type
gno links gno://notes/readme.md --type wiki
gno links gno://notes/readme.md --type markdown

# Show only broken links
gno links gno://notes/readme.md --broken
```

### Find backlinks

```bash
# Find all documents linking TO this one
gno backlinks gno://notes/api-design.md

# More results
gno backlinks gno://notes/api-design.md -n 50
```

### Find related notes

```bash
# Find semantically similar documents
gno similar gno://notes/auth.md

# Stricter threshold (default: 0.7)
gno similar gno://notes/auth.md --threshold 0.85

# Search across all collections
gno similar gno://notes/auth.md --cross-collection
```

### Wiki link syntax

```markdown
# In your documents:

See [[API Design]] for details.
Check [[work:Project Plan]] for cross-collection link.
Read [[Security#OAuth]] for specific section.
```

## Tagging

### List and manage tags

```bash
# List all tags with counts
gno tags

# Filter by collection
gno tags -c work

# Filter by prefix (hierarchical)
gno tags --prefix project/
```

### Add/remove tags

```bash
# Add tag to document
gno tags add gno://work/readme.md project/api

# Remove tag
gno tags rm gno://work/readme.md draft

# Tags in frontmatter are extracted automatically
cat myfile.md
# ---
# tags: [project/web, status/review]
# ---
```

### Filter search by tags

```bash
# Find docs with ANY of these tags (OR)
gno search "api" --tags-any project,work

# Find docs with ALL of these tags (AND)
gno query "auth" --tags-all security,reviewed

# Combine with other filters
gno ask "deployment steps" -c work --tags-any devops --answer
```

## Tips

### Search Modes

| Command                | Time    | Use When                     |
| ---------------------- | ------- | ---------------------------- |
| `gno search`           | instant | Exact keyword matching       |
| `gno vsearch`          | ~0.5s   | Finding similar concepts     |
| `gno query --fast`     | ~0.7s   | Quick lookups                |
| `gno query`            | ~2-3s   | Default, balanced            |
| `gno query --thorough` | ~5-8s   | Best recall, complex queries |

**Agent retry strategy**: Use default mode first. If no results:

1. Rephrase the query (free, often helps)
2. Try `--thorough` for better recall

### 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
```


path: mcp-reference.md
content: # GNO MCP Installation

GNO provides an MCP (Model Context Protocol) server for AI client integration.

> **Full reference**: See [gno.sh/docs/MCP](https://www.gno.sh/docs/MCP) for complete tool documentation.

## Quick Install

```bash
# Claude Desktop (default)
gno mcp install

# Claude Code
gno mcp install -t claude-code

# With write tools enabled
gno mcp install --enable-write
```

## Manual Setup

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gno": {
      "command": "gno",
      "args": ["mcp"]
    }
  }
}
```

Config locations:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

### Claude Code

```bash
gno mcp install -t claude-code -s user    # User scope
gno mcp install -t claude-code -s project # Project scope
```

## Check Status

```bash
gno mcp status
```

## Uninstall

```bash
gno mcp uninstall
gno mcp uninstall -t claude-code
```


path: README.md
content: # GNO — Agent Skill

Local-first semantic search for documents, notes, and knowledge bases,
packaged as a Claude Code / Codex / OpenCode / OpenClaw skill.

> **TL;DR** — this folder is a runnable agent skill. Drop it into any
> Claude Code, Codex, OpenCode, or OpenClaw workspace and the agent can
> index and search your local files through the `gno` CLI.

## Prerequisites

You need the `gno` CLI installed locally. The skill drives it; it does
not ship the binary itself.

```bash
# macOS / Linux
curl -fsSL https://gno.sh/install | bash

# npm / Bun
bun add -g @gmickel/gno        # or: npm install -g @gmickel/gno
```

Verify: `gno --version` should print `1.0.3` or later.

## Install the skill

There are two ways to install, and which one you pick depends on where
you're starting from.

### Option A — install from your local `gno` (recommended if you already have GNO)

If you already installed GNO, it ships this skill in-tree. One command
drops it into the right place for every supported agent, always in sync
with your installed GNO version:

```bash
gno skill install --target claude       # Claude Code (default)
gno skill install --target codex        # OpenAI Codex CLI
gno skill install --target opencode     # OpenCode
gno skill install --target openclaw     # OpenClaw
gno skill install --target all          # All four
```

Scope is configurable:

```bash
gno skill install --scope project       # ./.claude/skills/gno (default)
gno skill install --scope user          # ~/.claude/skills/gno
```

Inspect or uninstall:

```bash
gno skill show                          # preview what would be installed
gno skill paths                         # resolved installation paths
gno skill uninstall --target all        # remove from all agents
```

This path always gives you the skill that matches your GNO CLI — no
version drift.

### Option B — install from ClawHub (recommended if you use OpenClaw)

ClawHub is the OpenClaw skill registry. Use this when you manage
skills centrally across multiple workspaces or when you don't have GNO
installed yet.

```bash
openclaw skills install gno             # installs @gmickel/gno
openclaw skills update gno              # pull a newer version later
openclaw skills info gno                # inspect what's installed
```

You can also browse the skill at
<https://clawhub.ai/gmickel/gno> and download the folder manually.

## What the skill teaches the agent

Once installed, the agent gains a single callable capability: run `gno`
commands from the workspace. The skill docs (see [SKILL.md](SKILL.md))
walk the model through:

- initialising a new index and adding collections
- keyword (`search`), vector (`vsearch`), hybrid (`query`) and
  AI-answer (`ask`) search modes
- document retrieval (`get`, `multi-get`) including line ranges
- link graph traversal (`links`, `backlinks`, `similar`, `graph`)
- tagging, contexts, and per-collection embedding models
- publishing notes as gno.sh reader snapshots (`publish export`)
- MCP server setup for persistent agent access

The reference docs in this folder are discoverable by the agent via
progressive disclosure — the model only pulls them when it needs them:

- [SKILL.md](SKILL.md) — core instructions + frontmatter
- [cli-reference.md](cli-reference.md) — every CLI command, option and flag
- [mcp-reference.md](mcp-reference.md) — MCP tool and resource contract
- [examples.md](examples.md) — end-to-end usage patterns

## Agent tooling contract

The skill requests two tools:

```yaml
allowed-tools: Bash(gno:*) Read
```

- **`Bash(gno:*)`** — the agent can invoke `gno <anything>` on the
  host. All writes are explicit CLI calls; nothing runs implicitly.
- **`Read`** — the agent can open files the user has pointed at. No
  filesystem writes come through the skill itself.

## Versioning

The skill version is tracked separately from the GNO CLI version. When
the CLI ships a new feature worth teaching the model (new flag, new
subcommand, new sanitizer behaviour), the skill gets a point bump. See
the CHANGELOG entry on ClawHub or the `gno` repo's CHANGELOG for what
landed in each bump.

## License

MIT-0 — use it freely, with or without attribution.

## Links

- Source: <https://github.com/gmickel/gno>
- Hosted publishing: <https://gno.sh>
- OpenClaw docs: <https://docs.openclaw.ai>
- ClawHub listing: <https://clawhub.ai/gmickel/gno>


path: cli-reference.md
content: # 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)            |
| `--no-pager`      | Disable automatic paging                 |
| `--offline`       | Use cached models only                   |

## 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`, plus:

| Option                | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `--embed-model <uri>` | Initial collection-specific embedding model override |

### 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>
```

### gno collection clear-embeddings

```bash
gno collection clear-embeddings <name> [--all] [--json]
```

### gno embed

```bash
gno embed [collection] [--collection <name>] [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
```

## 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             |
| `--tags-any`       | -       | Filter: has ANY tag (comma-sep)  |
| `--tags-all`       | -       | Filter: has ALL tags (comma-sep) |
| `--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]
```

**Search modes** (pick one):

| Flag         | Time  | Description                    |
| ------------ | ----- | ------------------------------ |
| `--fast`     | ~0.7s | Skip expansion and reranking   |
| (default)    | ~2-3s | Skip expansion, with reranking |
| `--thorough` | ~5-8s | Full pipeline with expansion   |

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                            |
| ------------------------- | -------------------------------------- |
| `--fast`                  | Skip expansion and reranking (fastest) |
| `--thorough`              | Enable query expansion (better recall) |
| `--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>
```

### gno context check

Validate context configuration.

```bash
gno context check [--json]
```

## Note Linking

### gno links

List outgoing links from a document.

```bash
gno links <ref> [options]
```

| Option       | Description                          |
| ------------ | ------------------------------------ |
| `--type`     | Filter: `wiki`, `markdown`, or `all` |
| `--resolved` | Only show resolved links             |
| `--broken`   | Only show broken links               |
| `--json`     | JSON output                          |

### gno backlinks

Find documents linking TO a target.

```bash
gno backlinks <ref> [options]
```

| Option   | Description               |
| -------- | ------------------------- |
| `-n`     | Max results (default: 20) |
| `--json` | JSON output               |

### gno similar

Find semantically similar documents.

```bash
gno similar <ref> [options]
```

| Option               | Description                   |
| -------------------- | ----------------------------- |
| `-n`                 | Max results (default: 5)      |
| `--threshold`        | Min similarity (0-1)          |
| `--cross-collection` | Search across all collections |
| `--json`             | JSON output                   |

**Requirements**: Embeddings must exist for source and target documents.

### gno graph

Generate knowledge graph of document connections.

```bash
gno graph [options]
```

| Option             | Default | Description                    |
| ------------------ | ------- | ------------------------------ |
| `-c, --collection` | all     | Filter to single collection    |
| `--limit`          | 2000    | Max nodes                      |
| `--edge-limit`     | 10000   | Max edges                      |
| `--similar`        | false   | Include similarity edges       |
| `--threshold`      | 0.7     | Similarity threshold (0-1)     |
| `--linked-only`    | true    | Exclude isolated nodes         |
| `--similar-top-k`  | 5       | Similar docs per node (max 20) |
| `--json`           | -       | JSON output                    |

**Edge types**: `wiki` (wiki links), `markdown` (md links), `similar` (vector similarity).

**Web UI**: Access interactive graph at `http://localhost:3000/graph` via `gno serve`.

## Tags

### gno tags

List tags with document counts.

```bash
gno tags [options]
```

| Option             | Description           |
| ------------------ | --------------------- |
| `-c, --collection` | Filter by collection  |
| `--prefix`         | Filter by tag prefix  |
| `--json`           | JSON output           |
| `--md`             | Markdown table output |

### gno tags add

Add tag to document.

```bash
gno tags add <doc> <tag>
```

- `doc`: URI (`gno://...`) or docid (`#abc123`)
- `tag`: Tag string (lowercase, alphanumeric, hyphens, dots, `/` for hierarchy)

### gno tags rm

Remove tag from document.

```bash
gno tags rm <doc> <tag>
```

## 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
```

### gno vec

Vector index maintenance. Use when `gno similar` returns empty despite embeddings.

```bash
gno vec sync      # Fast incremental sync
gno vec rebuild   # Full rebuild
```

| Option   | Description |
| -------- | ----------- |
| `--json` | JSON output |

## 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]
```

## Web UI

### gno serve

Start web UI for browsing, searching, and querying documents.

```bash
gno serve [options]
```

| Option       | Default | Description      |
| ------------ | ------- | ---------------- |
| `-p, --port` | 3000    | Port to serve on |
| `--host`     | 0.0.0.0 | Host to bind     |

Features: Dashboard, search, browse collections, document viewer, AI Q&A with citations.

#### Long-running process flags (shared with `gno daemon`)

`gno serve` and `gno daemon` share an identical management contract.
The full spec is reproduced in this section so installed copies of this
skill stay self-contained. The canonical source in the gno repo is
`docs/CLI.md#long-running-processes` (kept in sync with this section
on every release).

| Flag                | Purpose                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `--detach`          | Self-spawn a detached child; parent prints `pid` (+ `url` for serve) and exits 0. Unix-only. |
| `--status`          | Read pid-file, check liveness, print status. Pair with `--json` for machine output.          |
| `--stop`            | SIGTERM the recorded pid, poll up to 10s, fall back to SIGKILL.                              |
| `--pid-file <path>` | Override pid-file location (defaults to `{data}/serve.pid`).                                 |
| `--log-file <path>` | Override log-file location (append-only; defaults to `{data}/serve.log`).                    |

`--detach`, `--status`, and `--stop` are mutually exclusive (Commander conflict error).

**`--json` is gated to `--status` only.** Passing `--json` with `--detach`,
`--stop`, or the foreground path produces a `VALIDATION` error (exit 1).
The literal stderr message is:

```
--json is only supported with `gno serve --status`
```

Do **not** try to parse a NOT_RUNNING envelope from stderr in this case —
it isn't there. Match on the literal string above (or just on exit code 1
plus the absence of structured output) and fall back to a status call.

**Exit codes:**

- `gno serve --status` → `0` when running, `3` (`NOT_RUNNING`) when not.
  The stdout JSON payload is still emitted in JSON mode on exit 3 so
  consumers always get a schema-shaped result; the NOT_RUNNING envelope
  rides on stderr (JSON mode only).
- `gno serve --stop` → `0` when stopped, `3` (`NOT_RUNNING`) when there
  was nothing to stop. **Silent on `3`** — no stderr envelope. Branch on
  `$?`, not stderr text. `1` when refusing to signal a foreign-version
  live pid; `2` when SIGTERM + SIGKILL both timed out.

Examples:

```bash
gno serve --detach                            # self-spawn, parent exits 0
gno serve --status                            # terminal table
gno serve --status --json                     # process-status schema
gno serve --stop                              # graceful stop
gno serve --detach --pid-file /tmp/gs.pid \
                   --log-file /tmp/gs.log
```

> **Windows note**: `--detach` returns a clean `VALIDATION` error pointing
> to WSL. `--status` / `--stop` / `--pid-file` / `--log-file` remain
> parseable but have nothing to manage in the absence of a detached child.

### gno daemon

Headless long-running watcher process. Same watch + sync + embed loop as
`gno serve`, no web UI, no port.

```bash
gno daemon [options]
```

| Option               | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `--no-sync-on-start` | Skip the initial sync pass; only watch future file changes. |

Plus the shared long-running-process flags listed in [`gno serve`](#gno-serve)
above (`--detach` / `--status` / `--stop` / `--pid-file` / `--log-file`).
Defaults: `{data}/daemon.pid`, `{data}/daemon.log` (`{data}` =
`resolveDirs().data`, honours `GNO_DATA_DIR`).

**`--json` gating** mirrors `gno serve` exactly. The literal stderr
message on a misuse is:

```
--json is only supported with `gno daemon --status`
```

**Exit codes** are identical to `gno serve` (`0` / `1` / `2` / `3`
`NOT_RUNNING`). `--stop` is silent on `3`.

Examples:

```bash
gno daemon                                    # foreground
gno daemon --no-sync-on-start                 # watcher-only
gno daemon --detach                           # self-spawn
gno daemon --detach --log-file /tmp/gd.log
gno daemon --status
gno daemon --status --json
gno daemon --stop
```

Avoid running `gno daemon` and `gno serve` against the same index at the
same time until cross-process coordination exists.

## Publish

### gno publish export

Export a note or collection as a gno.sh publish artifact JSON.

```bash
gno publish export <target> [--out <path.json>] [options]
```

| Option         | Default | Description                                                                |
| -------------- | ------- | -------------------------------------------------------------------------- |
| `--out`        | auto    | Output path, defaults to `~/Downloads/<slug>-<YYYYMMDD>.json`              |
| `--visibility` | public  | One of `public`, `secret-link`, `invite-only`, `encrypted`                 |
| `--slug`       | auto    | Override the published route slug                                          |
| `--title`      | auto    | Override the exported title                                                |
| `--summary`    | auto    | Override the exported summary                                              |
| `--passphrase` | none    | Required for `--visibility encrypted`; encrypts locally before upload      |
| `--preview`    | false   | Print sanitized markdown + preprocessor report instead of writing artifact |
| `--json`       | false   | Structured result output                                                   |

Examples:

```bash
gno publish export work-docs --out ~/Downloads/work-docs.json
gno publish export "gno://work-docs/runbooks/deploy.md" --out ~/Downloads/deploy.json

# Encrypted share — ciphertext produced locally before upload
gno publish export "gno://work-docs/offer-letter.md" \
  --visibility encrypted --passphrase "correct horse battery staple"

# Inspect what the sanitizer strips before writing anything
gno publish export "gno://vault/my-note.md" --preview
```

On success, upload the JSON file at `https://gno.sh/studio`.

**Obsidian pre-processor (v1.0.2+)**: before the artifact is written, the
export pipeline runs a sanitizer over each note's markdown. It:

- drops the navigation-sidebar idiom (`[[Hub]] | [[Related]]` immediately
  under the frontmatter)
- strips any `[[_internal/...]]` references (privacy guard — the
  `_internal/` convention is treated as never-publish)
- converts `[[Target|Alias]]` to the alias text, and `[[Target]]` to the
  tail segment of the target
- drops `![[image.png]]` embeds (attachments are not bundled yet) with a
  warning so the author can migrate to `![alt](url)` or wait for bundling
- refuses to export a note whose frontmatter contains `publish: false`
  (single-note export errors; collection export silently skips)

Every sanitizer decision surfaces in the CLI output as a "Preprocessor
notes" section, on the `--json` response under `warnings`, and on
`--preview` as a structured report — so nothing is silently lost.

## Skill Management

### gno skill install

Install GNO skill for AI coding assistants.

```bash
gno skill install [options]
```

| Option         | Default | Description                                              |
| -------------- | ------- | -------------------------------------------------------- |
| `-t, --target` | claude  | Target: `claude`, `codex`, `opencode`, `openclaw`, `all` |
| `-s, --scope`  | user    | Scope: `user`, `project`                                 |
| `-f, --force`  | false   | Overwrite existing                                       |
| `--dry-run`    | false   | Preview changes                                          |

Examples:

```bash
gno skill install --target claude --scope project
gno skill install --target codex --scope user
gno skill install --target openclaw --scope user
gno skill install --target all --force   # Install to all targets
```

### gno skill uninstall

Remove GNO skill from AI assistant.

```bash
gno skill uninstall [-t <target>] [-s <scope>]
```

### gno skill show

Preview skill files that would be installed.

```bash
gno skill show [--json]
```

### gno skill paths

Show skill installation paths for each target.

```bash
gno skill paths [--json]
```

## Additional Admin Commands

### gno reset

Delete all GNO data (database, embeddings, config). Use with caution.

```bash
gno reset [--force]
```

### gno completion

Install shell tab completion.

```bash
gno completion install [--shell <bash|zsh|fish>]
gno completion uninstall
```

## Exit Codes

| Code | Description                                                          |
| ---- | -------------------------------------------------------------------- |
| 0    | Success                                                              |
| 1    | Validation error (bad args)                                          |
| 2    | Runtime error (IO, DB, model)                                        |
| 3    | `NOT_RUNNING` — `--status` / `--stop` found no live matching process |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)