@gmickel/gno 1.29.2 → 1.29.4

package/README.md

@@ -1,6 +1,8 @@
 # GNO
 
-**Local search, retrieval, and synthesis for the files you actually work in.**
+**Search finds. GNO proves.**
+
+A local knowledge engine for your notes, code, PDFs, and Office docs — that hands agents evidence with exact line spans and content hashes, and stops when the evidence stops.
 
 [![npm](./assets/badges/npm.svg)](https://www.npmjs.com/package/@gmickel/gno)
 [![MIT License](./assets/badges/license.svg)](./LICENSE)
@@ -8,103 +10,90 @@
 [![Twitter](./assets/badges/twitter.svg)](https://twitter.com/gmickel)
 [![Discord](./assets/badges/discord.svg)](https://discord.gg/nHEmyJB5tg)
 
-> [!TIP]
-> **[gno.sh/publish](https://gno.sh/publish) is live.** Turn any GNO note or collection into a polished, reader-first URL — editorial typography, scoped search, and four visibility modes from public to encrypted-before-upload. **[See the reader →](#publish-to-gnosh)**
+![GNO](./assets/og-image.png)
 
-> **ClawdHub**: GNO skills bundled for Clawdbot — [clawdhub.com/gmickel/gno](https://clawdhub.com/gmickel/gno)
+```bash
+bun install -g @gmickel/gno
+gno setup ~/notes --name notes     # returns only after retrieval actually works
+gno mcp install --target cursor    # or claude-code, claude-desktop, zed, ...
+```
 
-![GNO](./assets/og-image.png)
+## Why not just another local RAG tool
 
-GNO is a local knowledge engine for notes, code, PDFs, Office docs, meeting transcripts, and reference material. It gives you fast keyword search, semantic retrieval, grounded answers with citations, wiki-style linking, and a real workspace UI, while keeping the whole stack local by default.
+Most retrieval tools return a ranked list and leave the rest to optimism. Four things here are different, and each one is measurable rather than adjectival:
 
-CLI retrieval also uses the current repository/workspace as a transparent soft
-ranking signal. A trusted explicit `--project-root`, nearest valid
-`.gno/index.yml`, or local cwd can add at most `+0.03` to matching collection
-results, in that precedence order; `--no-project-affinity` disables it. Profile
-defaults stay project-local and never overwrite the user default. It never overrides collection,
-tag, date, exclude, or egress filters. SDK, REST, and MCP `projectHints` are
-opaque, untrusted, limited to 16, and intentionally have zero ranking effect:
-those surfaces never probe caller or server filesystem paths. Trusted local
-diagnose output uses closed `schemaVersion: "1.1"` redacted affinity metadata;
-absent, disabled, and remote/untrusted diagnose requests preserve exact legacy
-v1.0 bytes and omit `affinity`.
+|                                                              | What it does                                                                                                                                                                   | Why it matters                                                                                                                                                                           |
+| :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Context Capsules](https://gno.sh/docs/context-capsules)** | Compiles one bounded evidence bundle per goal: exact line spans, content hashes, one global token budget, collapsed duplicates, and a written list of what it could _not_ find | Your agent reads once instead of searching five times. **48.94% fewer retrieval calls, 44.12% less model-visible context, 100% task accuracy retained** across 48 paired benchmark tasks |
+| **[Verified answers](https://gno.sh/docs/cli)**              | `gno ask --verify` generates against one closed Capsule, classifies every substantive claim, and withholds the draft below 100% support                                        | An abstention naming the failing claim beats a confident paragraph you have to fact-check by hand                                                                                        |
+| **[Verified setup](https://gno.sh/docs/project-profiles)**   | `gno setup` returns only after lexical search finds a real hit derived from _your_ corpus                                                                                      | No green checkmark over a folder that indexed but cannot be searched                                                                                                                     |
+| **[Egress policy](https://gno.sh/docs/collection-egress)**   | Per-collection fail-closed `local_only` / `lan` / `remote`, inherited by every derived Capsule, trace, and export                                                              | Mixed setups are normal. Pin the client work local while your notes use the LAN GPU box                                                                                                  |
 
-Use it when:
+Everything runs on your machine. Zero telemetry. The three network boundaries are explicit: downloading a model, configuring an HTTP inference endpoint, and uploading an artifact you exported for publishing.
 
-- your notes live in more than one folder
-- your important knowledge is split across Markdown, code, PDFs, and Office files
-- you want one retrieval layer that works from the CLI, browser, MCP, and a Bun/TypeScript SDK
-- you want better local context for agents without shipping your docs to a cloud API
+**And when it fails, that ships too.** The CJK lexical benchmark missed its own promotion gates, so the analyzer was not shipped and [the failing numbers were published](#general-multilingual-embedding-benchmark) instead.
 
-### What GNO Gives You
+## Use it when
 
-- **Fast local search**: BM25 for exact hits, vectors for concepts, hybrid for best quality
-- **Real retrieval surfaces**: CLI, Web UI, REST API, MCP, SDK
-- **Local-first answers**: grounded synthesis with citations when you want answers, raw retrieval when you do not
-- **Connected knowledge**: backlinks, related notes, graph view, cross-collection navigation
-- **Shareable, not synced**: export a note or collection to [gno.sh](https://gno.sh/publish) as a polished reader page — public, secret, invite-only, or locally encrypted before upload
-- **Operational fit**: daemon mode, model presets, remote GPU backends, safe config/state on disk
+- your knowledge is split across Markdown, code, PDFs, Office files, and exported mail or transcripts
+- you want one retrieval layer for the CLI, the browser, MCP, and a Bun/TypeScript SDK
+- you want your coding agent to have a real memory without shipping your docs to a cloud API
+- you need to prove, later, which bytes supported a conclusion
 
-### One-Minute Tour
+## Two minutes, end to end
 
 ```bash
 # Install
 bun install -g @gmickel/gno
 
-# Prove the first folder immediately; semantic work continues independently
+# Activate a folder. Returns only after BM25 proves an exact corpus-derived hit;
+# semantic embedding continues independently in the background.
 gno setup ~/notes --name notes
 
-# In a repository with .gno/index.yml: preview, apply, and prove its collection
-gno profile diff
-gno setup . --apply-profile
-
-# Add more collections with the granular commands
+# Add more sources
 gno collection add ~/work/docs --name work-docs --pattern "**/*.{md,pdf,docx}"
 gno collection add ~/work/gno/src --name gno-code --pattern "**/*.{ts,tsx,js,jsx}"
 
-# Add context so retrieval results come back with the right framing
-gno context add "notes:" "Personal notes, journal entries, and long-form ideas"
+# Tell retrieval what each collection is for
 gno context add "work-docs:" "Architecture docs, runbooks, RFCs, meeting notes"
-gno context add "gno-code:" "Source code for the GNO application"
 
-# Sync the additional collections, then embed when you want semantic retrieval
-gno update --yes
-gno embed
+gno update --yes   # sync
+gno embed          # embed when you want semantic retrieval
+
+# Pick the search that fits the question
+gno search "DEC-0054"                            # exact identifier
+gno vsearch "retry failed jobs with backoff"     # natural language
+gno query "JWT refresh token rotation" --explain # hybrid, with score traces
 
-# Search in the way that fits the question
-gno search "DEC-0054"                            # exact keyword / identifier
-gno vsearch "retry failed jobs with backoff"     # natural-language semantic lookup
-gno query "JWT refresh token rotation" --explain # hybrid retrieval with score traces
+# Compile checkable evidence for a goal, then re-check it later
+gno context build "why we dropped the queue rewrite" \
+  --collection work-docs --budget 12000 --json --output capsule.json
+gno context verify capsule.json
 
-# Retrieve documents or export context for an agent
-gno get "gno://work-docs/architecture/auth.md"
-gno multi-get "gno-code/**/*.ts" --max-bytes 30000 --md
-gno query "deployment process" --all --files --min-score 0.35
+# Generate only what that evidence supports
+gno ask "why did we drop the queue rewrite" --verify --show-sources
 
-# Run the workspace (pick one — don't run both against the same index concurrently)
-gno serve            # browser/desktop session with the Web UI
-gno daemon --detach  # headless continuous indexing (background; --status / --stop to manage)
+# Run the workspace (pick one — not both against the same index)
+gno serve            # browser/desktop Web UI
+gno daemon --detach  # headless indexing + resident MCP gateway
 ```
 
+> [!TIP]
+> **[gno.sh/publish](https://gno.sh/publish) is live.** Turn any GNO note or collection into a reader-first URL — editorial typography, scoped search, and four visibility modes from public to encrypted-before-upload. **[See the reader →](#publish-to-gnosh)**
+
+> **ClawdHub**: GNO skills bundled for Clawdbot — [clawdhub.com/gmickel/gno](https://clawdhub.com/gmickel/gno)
+
 ---
 
 ## Contents
 
-- [Quick Start](#quick-start)
-- [Installation](#installation)
-- [Daemon Mode](#daemon-mode)
-- [Search Modes](#search-modes)
-- [Agent Integration](#agent-integration)
-- [Web UI](#web-ui)
-- [Publish to gno.sh](#publish-to-gnosh)
-- [REST API](#rest-api)
-- [SDK](#sdk)
-- [How It Works](#how-it-works)
-- [Features](#features)
-- [Local Models](#local-models)
-- [Fine-Tuned Models](#fine-tuned-models)
-- [Architecture](#architecture)
-- [Development](#development)
+**Start here** · [Quick Start](#quick-start) · [Installation](#installation) · [Agent Integration](#agent-integration) · [Search Modes](#search-modes)
+
+**Surfaces** · [Web UI](#web-ui) · [REST API](#rest-api) · [SDK](#sdk) · [Daemon Mode](#daemon-mode) · [Publish to gno.sh](#publish-to-gnosh)
+
+**Under the hood** · [How It Works](#how-it-works) · [Features](#features) · [Local Models](#local-models) · [Fine-Tuned Models](#fine-tuned-models) · [Architecture](#architecture) · [Development](#development)
+
+**Deep dives on gno.sh** · [Context Capsules](https://gno.sh/docs/context-capsules) · [Knowledge Delta](https://gno.sh/docs/knowledge-delta) · [Retrieval learning](https://gno.sh/docs/retrieval-learning) · [Project profiles](https://gno.sh/docs/project-profiles) · [Egress policies](https://gno.sh/docs/collection-egress) · [Export adapters](https://gno.sh/docs/file-export-adapters)
 
 ---
 
@@ -112,7 +101,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.29.2** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.29.4** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -247,7 +236,7 @@ gno models pull --gen
 gno query "ECONNREFUSED 127.0.0.1:5432" --thorough
 ```
 
-> Full guide: [Fine-Tuned Models](https://gno.sh/docs/FINE-TUNED-MODELS/) · [Feature page](https://gno.sh/features/fine-tuned-models/)
+> Full guide: [Fine-Tuned Models](https://gno.sh/docs/fine-tuned-models) · [Feature page](https://gno.sh/features/fine-tuned-models)
 
 ---
 
@@ -365,7 +354,7 @@ gno skill install --target openclaw   # OpenClaw
 gno skill install --target all        # All targets
 ```
 
-> **Full setup guide**: [MCP Integration](https://gno.sh/docs/MCP/) · [CLI Reference](https://gno.sh/docs/CLI/)
+> **Full setup guide**: [MCP Integration](https://gno.sh/docs/mcp) · [CLI Reference](https://gno.sh/docs/cli)
 
 ---
 
@@ -387,7 +376,7 @@ headless. `--detach` / `--status` / `--stop` give you symmetric lifecycle
 controls so you don't need `nohup`, `launchd`, or `systemd` units. The same
 flag set is available on `gno serve`.
 
-[Daemon guide →](https://gno.sh/docs/DAEMON/)
+[Daemon guide →](https://gno.sh/features/daemon-mode)
 
 ---
 
@@ -479,7 +468,7 @@ Core SDK surface:
 - `update`, `embed`, `index`
 - `close`
 
-Full guide: [SDK docs](https://gno.sh/docs/SDK/)
+Full guide: [SDK docs](https://gno.sh/docs/sdk)
 
 ---
 
@@ -607,7 +596,7 @@ gno get "gno://work-docs/api-reference.md" --full
 gno multi-get "work-docs/**/*.md" --md --max-bytes 30000
 ```
 
-[Skill setup guide →](https://gno.sh/docs/integrations/skills/)
+[Skill setup guide →](https://gno.sh/docs/skills)
 
 ### MCP Server
 
@@ -655,7 +644,7 @@ requires an explicit restrictive bearer-token file plus exact Host and Origin
 allowlists; `gno serve` remains loopback-only. Authentication alone never
 enables mutation tools.
 
-[MCP setup guide →](https://gno.sh/docs/MCP/)
+[MCP setup guide →](https://gno.sh/docs/mcp)
 
 ---
 
@@ -758,7 +747,7 @@ telemetry. Network access occurs when GNO downloads models, when you configure
 an HTTP model backend, or when you explicitly upload an exported artifact to
 gno.sh.
 
-> **Detailed docs**: [Web UI Guide](https://gno.sh/docs/WEB-UI/)
+> **Detailed docs**: [Web UI Guide](https://gno.sh/docs/web-ui)
 
 ---
 
@@ -879,7 +868,7 @@ curl http://localhost:3000/api/health
 
 No authentication. No rate limits. Build custom tools, automate workflows, integrate with any language.
 
-> **Full reference**: [API Documentation](https://gno.sh/docs/API/)
+> **Full reference**: [API Documentation](https://gno.sh/docs/api)
 
 ---
 
@@ -914,7 +903,7 @@ graph TD
 3. **Fusion**: RRF with 2× weight for original query, tiered bonus for top ranks
 4. **Reranking**: Qwen3-Reranker scores best chunk per document (4K), blended with fusion
 
-> **Deep dive**: [How Search Works](https://gno.sh/docs/HOW-SEARCH-WORKS/)
+> **Deep dive**: [How Search Works](https://gno.sh/docs/how-search-works)
 
 ---
 
@@ -987,8 +976,8 @@ Hugging Face. The `gen:` role remains the standalone answer model.
 
 See:
 
-- [Fine-Tuned Models docs](https://gno.sh/docs/FINE-TUNED-MODELS/)
-- [Fine-Tuned Models feature page](https://gno.sh/features/fine-tuned-models/)
+- [Fine-Tuned Models docs](https://gno.sh/docs/fine-tuned-models)
+- [Fine-Tuned Models feature page](https://gno.sh/features/fine-tuned-models)
 
 ### HTTP Backends (Remote GPU)
 
@@ -1012,7 +1001,7 @@ The HTTP adapter expects the OpenAI-compatible endpoint shapes documented in
 chunk, or answer context sent to their configured model role; they are outside
 GNO's local trust boundary.
 
-> **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)
+> **Configuration**: [Model Setup](https://gno.sh/docs/configuration)
 
 Remote/BYOM guides:
 
@@ -1035,7 +1024,7 @@ Remote/BYOM guides:
 └─────────────────────────────────────────────────┘
 ```
 
-> **Details**: [Architecture](https://gno.sh/docs/ARCHITECTURE/)
+> **Details**: [Architecture](https://gno.sh/docs/architecture)
 
 ---
 

package/assets/skill/README.md

@@ -38,7 +38,8 @@ 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
+gno skill install --target hermes       # Hermes
+gno skill install --target all          # All supported agents
 ```
 
 Scope is configurable:
@@ -81,19 +82,25 @@ commands from the workspace. The skill docs (see [SKILL.md](SKILL.md))
 walk the model through:
 
 - initialising a new index and adding collections
+- retrieval-proven `setup` and portable project profiles
 - keyword (`search`), vector (`vsearch`), hybrid (`query`) and
   AI-answer (`ask`) search modes
+- deterministic Context Capsules and fail-closed verified answers
 - document retrieval (`get`, `multi-get`) including line ranges
 - link graph traversal (`links`, `backlinks`, `similar`, `graph`)
+- private retrieval traces/replay and Knowledge Delta inspection
+- project affinity, explainable content boosts, and collection egress policy
+- JSONL, mail, calendar, transcript, and browser-export source adapters
+- provenance-aware browser clipping and typed second-brain capture recipes
 - tagging, contexts, and per-collection embedding models
 - publishing notes as gno.sh reader snapshots (`publish export`)
-- MCP server setup for persistent agent access
+- stdio and resident Streamable HTTP MCP 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
+- [cli-reference.md](cli-reference.md) — concise CLI command reference
 - [mcp-reference.md](mcp-reference.md) — MCP tool and resource contract
 - [examples.md](examples.md) — end-to-end usage patterns
 - [recipes/](recipes/) — task-shaped second-brain workflows for lookup,

package/assets/skill/cli-reference.md

@@ -24,6 +24,27 @@ punctuation. NFC/case-equivalent spellings share one identity. See
 
 ## Initialization
 
+### gno setup
+
+Preferred activation path: add one folder, prove a real exact lexical result,
+then continue semantic indexing in the background.
+
+```bash
+gno setup <folder> --name <collection> [options]
+```
+
+| Option                    | Description                                               |
+| ------------------------- | --------------------------------------------------------- |
+| `--exclude <pattern>`     | Repeatable literal exclusion                              |
+| `--authorize-secret-risk` | Explicitly allow likely-secret files                      |
+| `--connector <id>`        | Install and smoke-test a connector; repeatable            |
+| `--apply-profile`         | Apply a valid `.gno/index.yml` before setup               |
+| `--no-semantic`           | Stop after lexical retrieval proof; start no model worker |
+| `--json`                  | Structured activation receipt                             |
+
+Setup is idempotent. Success means a corpus-derived BM25 query returned a
+cited result; it does not imply that background semantic work already finished.
+
 ### gno init
 
 ```bash
@@ -116,6 +137,25 @@ Generate embeddings only.
 gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
 ```
 
+## Project Profiles
+
+Project-local `.gno/index.yml` files describe portable collection, context,
+content-type, source-metadata, and retrieval-default intent. They never relocate
+the database into the repository and are never applied implicitly.
+
+```bash
+gno profile check [path]
+gno profile show [path]
+gno profile diff [path]
+gno profile apply [path]
+gno setup . --apply-profile
+```
+
+`check` validates only. `show` emits normalized state. `diff` compares the
+profile with local configuration. `apply` is additive/update-oriented and does
+not infer deletions. Profile project roots are trusted local affinity inputs;
+MCP/SDK/REST hints remain opaque and cannot become filesystem paths.
+
 ## Capture
 
 ### gno capture
@@ -220,10 +260,19 @@ gno ask <question> [options]
 | `--fast`                  | Skip expansion and reranking (fastest) |
 | `--thorough`              | Enable query expansion (better recall) |
 | `--answer`                | Generate grounded answer               |
+| `--verify`                | Closed-Capsule answer or abstention    |
 | `--no-answer`             | Retrieval only                         |
 | `--max-answer-tokens <n>` | Cap answer length                      |
+| `--context-budget-tokens` | Global verified-Capsule token budget   |
+| `--context-budget-bytes`  | Global verified-Capsule byte budget    |
 | `--show-sources`          | Show all sources                       |
 
+`--verify` is distinct from `--answer`: generation receives only a closed
+Context Capsule, every substantive claim is checked against exact retained
+spans, and GNO releases the answer only at 100% support coverage. Failed or
+unavailable semantic verification forces an explicit abstention. This proves
+support against retained evidence, not corpus completeness or source truth.
+
 ## Document Retrieval
 
 ### gno get
@@ -292,6 +341,113 @@ Validate context configuration.
 gno context check [--json]
 ```
 
+### gno context build
+
+Compile one deterministic, extractive evidence bundle under global token and
+byte budgets:
+
+```bash
+gno context build "<goal>" --budget 12000 --json --output capsule.json
+gno context build "compare proposals" --budget 16000 --collection work --md
+gno context build "release evidence" --budget 12000 --fast --json
+```
+
+The Capsule retains exact URI/heading/line spans, source/mirror/passage hashes,
+normalized retrieval inputs, fingerprints, capability outcomes, omissions,
+coverage, and explicit gaps. Selection collapses overlaps and rewards uncovered
+facets. `--fast` avoids model loading; `--thorough` widens retrieval. GNO writes
+only to stdout or an explicit `--output`; it never persists Capsules implicitly.
+
+### gno context verify
+
+Recheck a saved canonical JSON Capsule without rebuilding or mutating it:
+
+```bash
+gno context verify capsule.json --json
+cat capsule.json | gno context verify - --md
+```
+
+The receipt classifies evidence as unchanged, stale, or missing; ranking as
+unchanged, reranked, or unavailable; and reports fingerprint drift separately.
+Verification uses the Capsule's index and refuses an explicitly mismatched
+global `--index`.
+
+### Saved Capsule watches
+
+Register a caller-owned Capsule file for evidence-triggered reverification:
+
+```bash
+gno context watch capsule.json --question "Who owns launch?" --notify --json
+gno context watches --json
+gno context reverify <registration-id> --json
+gno context unwatch <registration-id> --json
+```
+
+GNO stores only bounded registration metadata and evidence hashes—not Capsule
+or passage bytes. `serve`/`daemon` reverify after relevant settled index
+changes. Watch lifecycle operations are CLI-only. Reverification never rebuilds
+or overwrites the saved Capsule.
+
+## Knowledge Delta
+
+Inspect retained metadata-only change history and bounded dependency impact:
+
+```bash
+gno changes --since 2026-07-20T00:00:00Z --json
+gno diff gno://notes/plan.md --json
+gno impact gno://notes/plan.md --max-depth 3 --json
+```
+
+`changes` accepts an ISO time or opaque cursor and optional collection/limit.
+`diff` reports structural headings, links, and typed-relationship changes for
+one retained change. `impact` follows inbound evidence edges with explicit
+depth/node/edge/frontier/visited bounds. Expired journal history is reported,
+not reconstructed.
+
+## Private Retrieval Traces
+
+Trace recording is local and off by default. Metadata mode excludes raw
+query/goal/filter values; replay mode is separate explicit consent.
+
+```bash
+gno trace list --json
+gno trace show <trace-id> --json
+gno trace label <trace-id> --label relevant --target <uri> \
+  --target-kind document
+gno trace export <trace-id> --format qrels --output qrels.json
+gno trace replay <export-id> --candidate hybrid --md
+gno trace delete <trace-id>
+gno trace purge
+```
+
+Only append relevance labels the user explicitly supplied. Export, delete, and
+purge are explicit mutations. Replay compares one candidate with an immutable
+local baseline and always reports `applied: false`; it never changes live
+ranking.
+
+## Collection Egress
+
+Collections can be restricted to `local_only`, `lan`, or `remote`. Egress is
+checked before non-loopback serving, remote model calls, network export, or
+publishing and remains separate from authentication or write permission.
+
+```bash
+gno collection policy get work
+gno collection policy check --action remote_model \
+  --destination remote --content-class internal -c work --explain-egress
+gno collection policy set work remote --confirm-relaxation <revision>
+gno egress-audit list
+gno egress-audit show <audit-id>
+gno egress-audit status
+gno egress-audit delete <audit-id>
+gno egress-audit purge
+```
+
+Denied egress is terminal for that route; do not retry through another network
+surface. Relaxing policy requires the current revision; tightening to
+`local_only` does not. Audit receipts are local and content-free.
+Deletion/purge must remain explicit.
+
 ## Note Linking
 
 ### gno links

package/assets/skill/examples.md

@@ -7,14 +7,11 @@ Real-world examples for common tasks.
 ### Index a folder of docs
 
 ```bash
-# Initialize
-gno init
-
-# Add your docs folder
-gno collection add ~/Documents/work --name work
+# Preferred path: add folder, index, and prove exact retrieval
+gno setup ~/Documents/work --name work
 
-# Build index
-gno index
+# Skip the background semantic worker when BM25 is sufficient
+gno setup ~/Documents/contracts --name contracts --no-semantic
 ```
 
 ### Index multiple folders
@@ -71,6 +68,9 @@ gno ask "what are the payment terms"
 
 # Get an AI-generated answer
 gno ask "what are the payment terms" --answer
+
+# Fail closed unless every substantive claim has retained evidence
+gno ask "what are the payment terms" --verify --show-sources
 ```
 
 ### Scoped answers
@@ -83,6 +83,67 @@ gno ask "termination clause" -c contracts --answer
 gno ask "summarize project goals" --answer --max-answer-tokens 200
 ```
 
+## Context Capsules
+
+### Build one bounded evidence handoff
+
+```bash
+gno context build "What changed in the launch plan?" \
+  --budget 12000 --json --output launch-capsule.json
+```
+
+The saved JSON contains exact evidence spans, hashes, coverage gaps, omissions,
+and the frozen retrieval plan. GNO does not save it unless `--output` is
+explicit.
+
+### Verify or watch saved evidence
+
+```bash
+# Check the old evidence without rebuilding it
+gno context verify launch-capsule.json --json
+
+# Reverify automatically when relevant indexed evidence changes
+gno context watch launch-capsule.json \
+  --question "What changed in the launch plan?" --notify --json
+gno context watches --json
+```
+
+`verify` and `reverify` never overwrite or silently rebuild the Capsule. Run
+`context build` again when a fresh evidence selection is required.
+
+## Project-Aware Retrieval
+
+```bash
+# Inspect portable repository intent before applying it
+gno profile check
+gno profile diff
+gno setup . --apply-profile
+
+# Override or disable trusted local project affinity for one request
+gno query "release plan" --project-root ~/work/product
+gno query "release plan" --no-project-affinity
+```
+
+Configured `contentTypes[].searchBoost` is bounded and visible with
+`--explain`; hard collection/tag/date/exclude/egress filters still win.
+
+## Changes and Retrieval Learning
+
+```bash
+# What changed, and what depends on it?
+gno changes --since 2026-07-20T00:00:00Z --json
+gno diff gno://work/launch.md --json
+gno impact gno://work/launch.md --max-depth 3 --json
+
+# Explicit local judgment -> immutable qrels -> offline comparison
+gno trace label <trace-id> --label relevant \
+  --target gno://work/launch.md --target-kind document
+gno trace export <trace-id> --format qrels --output launch-qrels.json
+gno trace replay <export-id> --candidate hybrid --md
+```
+
+Replay is advisory and never changes live ranking.
+
 ## Reading Documents
 
 ### Get full document

package/assets/skill/mcp-reference.md

@@ -119,6 +119,19 @@ Read-only MCP graph/query diagnostics include `gno_graph_query` and
 `gno_query_diagnose`. In `gno_query_diagnose`, pass `fast: true` for a BM25-only
 diagnosis that avoids embedding/rerank model initialization.
 
+Before reusing caller-saved Capsule JSON, pass the complete canonical object to
+`gno_context_verify`. It reports evidence, ranking, and fingerprint drift
+without rebuilding or persisting the Capsule. The complete `gno_context` result
+lives in `structuredContent`; its text projection is deliberately compact and
+should not be expanded back into duplicate model context.
+
+Use `gno_changes`, `gno_diff`, and `gno_impact` for retained metadata history
+and bounded dependency questions. Use `gno_trace_list` and `gno_trace_show` for
+private local diagnostics. Invoke `gno_trace_label` only when the user
+explicitly provides a relevant, irrelevant, or missing-expected judgment.
+Trace export/replay/delete/purge and saved-Capsule watch lifecycle remain
+CLI-only.
+
 ## Capture
 
 `gno_capture` is available only when MCP starts with `--enable-write` or

package/browser-extension/artifacts/gno-browser-clipper-v1.29.4.zip.sha256

@@ -0,0 +1 @@
+b639ecf7ff5ebd7aeacf1bad0fe3fe2f471a60c96bdf047d873b6bf932995161  gno-browser-clipper-v1.29.4.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.29.2"
+  "version": "1.29.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.29.2",
+  "version": "1.29.4",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/browser-extension/artifacts/gno-browser-clipper-v1.29.2.zip.sha256

@@ -1 +0,0 @@
-d693cf38e03cf3d016ac982d1ec1658e9d7b6fb8e57d83f0a051e43569a58247  gno-browser-clipper-v1.29.2.zip