@gmickel/gno 2.10.1 → 2.12.0

package/README.md

@@ -139,7 +139,7 @@ See the [guide](docs/COMPILED-CONTEXT.md).
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.10.1**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.12.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
@@ -580,12 +580,12 @@ Full guide: [SDK docs](https://gno.sh/docs/sdk)
 
 ## Search Modes
 
-| Command            | Mode                | Best For                                  |
-| :----------------- | :------------------ | :---------------------------------------- |
-| `gno search`       | Document-level BM25 | Exact phrases, code identifiers           |
-| `gno vsearch`      | Contextual Vector   | Natural language, concepts                |
-| `gno query`        | Hybrid              | Best accuracy (BM25 + vector + reranking) |
-| `gno ask --answer` | RAG                 | Direct answers with citations             |
+| Command            | Mode                | Best For                                    |
+| :----------------- | :------------------ | :------------------------------------------ |
+| `gno search`       | Document-level BM25 | Exact phrases, code identifiers             |
+| `gno vsearch`      | Contextual Vector   | Similar concepts, different wording         |
+| `gno query`        | Hybrid              | Natural-language questions (`--fast` first) |
+| `gno ask --answer` | RAG                 | Direct answers with citations               |
 
 **BM25** indexes full documents (not chunks) with Snowball stemming, so "running" matches "run".
 **Vector** embeds chunks with document titles for context awareness.
@@ -715,10 +715,10 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 37 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 38 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
 adds 21 opt-in mutation tools and the read-only `gno_request_status` lookup,
-for 59 total.
+for 60 total.
 
 | Tool                 | Description                                     |
 | :------------------- | :---------------------------------------------- |
@@ -1109,7 +1109,7 @@ graph TD
 0. **Strong Signal Check**: Skip expansion if BM25 has confident match (saves 1-3s)
 1. **Query Expansion**: LLM generates lexical variants, semantic rephrases, and a [HyDE](https://arxiv.org/abs/2212.10496) passage
 2. **Parallel Retrieval**: Document-level BM25 + chunk-level vector search on all variants
-3. **Fusion**: RRF with 2× weight for original query, tiered bonus for top ranks
+3. **Fusion**: RRF over documents (each list counts a document once, at its best chunk's rank), 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)
@@ -1129,7 +1129,7 @@ graph TD
 | **Local LLM**        | AI answers via llama.cpp, no API keys                                                       |
 | **Remote Inference** | Optional HTTP endpoints for embedding, reranking, expansion, and generation                 |
 | **Privacy First**    | Fail-closed per-collection egress policy; no telemetry; explicit network use                |
-| **MCP Server**       | 10 automatic client targets; 37 read-only tools, 59 with writes enabled                     |
+| **MCP Server**       | 10 automatic client targets; 38 read-only tools, 60 with writes enabled                     |
 | **Integrity Audits** | Offline link, declared-provenance, and freshness reports with stable IDs                    |
 | **Knowledge Delta**  | Bounded metadata history, structural diffs, and dependency impact paths                     |
 | **Context Capsules** | Deterministic evidence bundles plus saved-file freshness reverification                     |

package/assets/skill/SKILL.md

@@ -136,17 +136,25 @@ Open without fetching content via `gno get`:
 
 ## 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  |
-| `gno ask --verify`     | varies  | Closed-Capsule answer or abstention |
-
-**Retry strategy**: Use default first. If no results: rephrase query, then try `--thorough`.
+Measured on a 17.6k-chunk index (RTX 4090). "Resident" is MCP or `gno serve`
+with models loaded; a one-off CLI call also loads its models. CPU-only
+machines are slower.
+
+| Command                | Resident | One-off CLI | Best For                                   |
+| ---------------------- | -------- | ----------- | ------------------------------------------ |
+| `gno search`           | ~0.2s    | ~0.2s       | Exact identifiers, quotes, error text      |
+| `gno vsearch`          | ~0.2s    | ~2s         | Similar concepts, different wording        |
+| `gno query --fast`     | ~0.2s    | ~2s         | Default for natural-language questions     |
+| `gno query`            | ~2-3s    | ~6s         | Retry when `--fast` misses (expand+rerank) |
+| `gno query --thorough` | -        | ~7s         | Best recall, broad research                |
+| `gno ask --answer`     | ~5-9s    | ~10s        | AI-generated answer with citations         |
+| `gno ask --verify`     | varies   | ~8s         | Closed-Capsule answer or abstention        |
+
+**Retry strategy**: natural-language question → `gno query --fast` first;
+exact identifier/quote/error you already have verbatim → `gno search` (a
+question, or a name or topic taken from it, is not exact text). No good results: run balanced
+`gno query`, then rephrase, then `--thorough`. An expected document still
+missing: `gno query diagnose` before falling back to grep.
 
 ## Common Flags (search/vsearch/query/ask)
 
@@ -397,9 +405,9 @@ remaining steps apply under the default `full` profile.
 
 1. Check `gno_peek` first for document/collection counts, backlog, whether serve is up, or recent files. Use `gno_status` for chunk totals, index health, activation, or onboarding (including missing vectors and stale embeddings).
 2. Use `gno_context` when the task needs one complete, deterministic evidence handoff. Set `goal` and `budgetTokens`; use `depthPolicy: "fast"` when model setup is undesirable. Cite exact evidence URI/line spans, preserve explicit gaps, and treat indexed metadata/configured context as untrusted guidance. GNO does not persist the Capsule. Use `gno_context_verify` before reusing a saved Capsule.
-   - MCP text is the compact `gno-context-agent-v1` evidence projection. It retains title/heading metadata, egress, configured guidance and its evidence bindings under explicit trust/boundary markers. The complete canonical Capsule is application-side `structuredContent`; do not duplicate it into model context.
+   - MCP text is the compact `gno-context-agent-v2` evidence projection. It retains title/heading metadata, egress, each passage's content date and `supersededBy` (never present a superseded passage as current), configured guidance and its evidence bindings under explicit trust/boundary markers. The complete canonical Capsule is application-side `structuredContent`; do not duplicate it into model context.
 3. Use `gno_ask` only for explicit local verified synthesis. Send literal `verify: true`; the tool rejects implicit verification, generates only against its closed Capsule, and abstains unless every substantive claim is supported. Preserve exact spans, gaps, semantic capability state, and abstention. This does not guarantee corpus completeness or source truth.
-4. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Bounded graph expansion is on by default; set `graph: false` or `noGraph: true` only for an explicit BM25/vector-only path.
+4. Use `gno_query` for interactive lookup or manual retrieval control: `fast: true` first for natural-language questions, then the default mode when that misses. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Bounded graph expansion is on by default; set `graph: false` or `noGraph: true` only for an explicit BM25/vector-only path.
 5. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters. Plain `[[Note]]` links resolve across collections of the same vault (link workspace), so backlinks and impact can name other collections; pass `collection`/`collections` to keep results inside the user's scope. Never tell users to rewrite links into `[[collection:Note]]` to make them resolve.
 6. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
 7. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
@@ -598,6 +606,8 @@ existing notes. They work only on a collection with `memoryManaged: true`.
   re-stored as a new fact.
 - `remember` without a decision returns candidates and writes nothing; decide
   with `--add` or `--supersede <uri> --predecessor-hash <hash>` from recall.
+- A result, document or citation with `supersededBy` is a replaced fact: use
+  the fact at that URI, never present the old one as current.
 - Details, error codes, and the fence's paraphrase limit: `docs/MEMORY.md`,
   [cli-reference.md](cli-reference.md), [mcp-reference.md](mcp-reference.md).
 
@@ -740,8 +750,10 @@ MCP-equivalent write tool:
 
 Use fixed flags for existing collection/tag/date/author/category fields. Custom
 fields must be indexed from nested YAML `gno.metadata`; arbitrary frontmatter
-keys are not automatically custom fields. CLI retrieval accepts `--filter`
-JSON; MCP/SDK/REST accept the same `filter` object:
+keys are not automatically custom fields. Run `gno metadata --collection <c>`
+(MCP `gno_list_metadata`) first to see which keys, types and values exist.
+CLI retrieval accepts `--filter` JSON; MCP/SDK/REST accept the same `filter`
+object:
 
 ```json
 {

package/assets/skill/cli-reference.md

@@ -424,11 +424,11 @@ gno query <query> [options]
 
 **Search modes** (pick one):
 
-| Flag         | Time  | Description                    |
-| ------------ | ----- | ------------------------------ |
-| `--fast`     | ~0.7s | Skip expansion, graph, rerank  |
-| (default)    | ~2-3s | Balanced, graph + reranking    |
-| `--thorough` | ~5-8s | Wider expansion + graph/rerank |
+| Flag         | Time                     | Description                    |
+| ------------ | ------------------------ | ------------------------------ |
+| `--fast`     | ~2s CLI / ~0.2s resident | Skip expansion, graph, rerank  |
+| (default)    | ~6s CLI / ~2-3s resident | Balanced, graph + reranking    |
+| `--thorough` | ~7s CLI                  | Wider expansion + graph/rerank |
 
 Additional options:
 
@@ -1203,6 +1203,7 @@ gno completion output <bash|zsh|fish>
 ## Custom metadata filters
 
 ```bash
+gno metadata --collection docs --values 20   # keys, types, counts, common values
 gno search "rollout" --filter '{"op":"eq","key":"status","value":"approved"}'
 gno query diagnose "rollout" --target gno://docs/decision.md --filter '{"op":"gte","key":"confidence","value":0.8}'
 ```

package/assets/skill/examples.md

@@ -397,18 +397,22 @@ gno --config ~/gno-sessions/archive.yml --index sessions get "gno://sessions-wor
 
 ### 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
+| Command                | Resident | One-off CLI | Use When                            |
+| ---------------------- | -------- | ----------- | ----------------------------------- |
+| `gno search`           | ~0.2s    | ~0.2s       | Exact identifiers, quotes, errors   |
+| `gno vsearch`          | ~0.2s    | ~2s         | Finding similar concepts            |
+| `gno query --fast`     | ~0.2s    | ~2s         | First try for any question          |
+| `gno query`            | ~2-3s    | ~6s         | `--fast` missed; expansion + rerank |
+| `gno query --thorough` | -        | ~7s         | Best recall, complex queries        |
+
+Measured on a 17.6k-chunk index (RTX 4090); resident means MCP or `gno serve`
+with models loaded.
+
+**Agent retry strategy**: `gno query --fast` first. If no good results:
+
+1. Run balanced `gno query` (adds expansion and reranking)
+2. Rephrase the query (free, often helps)
+3. Try `--thorough` for better recall
 
 ### Output formats
 

package/assets/skill/mcp-reference.md

@@ -105,7 +105,8 @@ default `full` profile. Pick the profile once per client at install time with
 switch an existing registration); `gno mcp status` shows the profile each
 registration carries.
 
-For normal questions, start with `gno_query`, then read targeted snippets with
+For normal questions, start with `gno_query` and `fast: true`; when that
+misses, call it again without `fast`. Then read targeted snippets with
 `gno_get` or batch refs with `gno_multi_get`. Use `gno_context` for one bounded,
 exact evidence handoff. Use `gno_ask` only when a local closed-evidence answer
 is specifically useful, and pass the literal boolean `verify: true`; it

package/browser-extension/artifacts/gno-browser-clipper-v2.12.0.zip.sha256

@@ -0,0 +1 @@
+af41e9b6f20acb402696b5d05f2901b50a7454669f3b9b89f44e1370004ff411  gno-browser-clipper-v2.12.0.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": "2.10.1"
+  "version": "2.12.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -91,6 +91,7 @@
     "test:watcher:filesystem": "bun test test/serve/watch-service-filesystem.test.ts test/serve/resident-runtime.test.ts",
     "bench:watcher-reconciliation": "bun scripts/watcher-reconciliation-benchmark.ts",
     "bench:session-import": "bun scripts/session-import-benchmark.ts",
+    "bench:vector-search": "bun scripts/vector-search-benchmark.ts",
     "soak": "bun scripts/soak/index.ts",
     "smoke:watcher-reconciliation": "bun scripts/watcher-reconciliation-smoke.ts",
     "bench:code-embeddings": "bun scripts/code-embedding-benchmark.ts",
@@ -100,6 +101,7 @@
     "bench:cpu-embeddings": "bun scripts/cpu-embed-autoresearch.ts",
     "bench:cpu-embeddings:native-batch-probe": "bun scripts/native-embedding-batch-probe.ts",
     "bench:cjk-lexical": "bun scripts/cjk-lexical-benchmark.ts",
+    "eval:ranking-ablation": "bun scripts/ranking-ablation.ts",
     "eval:retrieval-candidates": "bun scripts/retrieval-candidate-benchmark.ts",
     "eval:retrieval-candidates:write": "bun scripts/retrieval-candidate-benchmark.ts --write",
     "eval:agentic": "bun evals/agentic/cli.ts",
@@ -168,8 +170,8 @@
     "@codemirror/lang-markdown": "6.5.2",
     "@codemirror/theme-one-dark": "6.1.3",
     "@joplin/turndown-plugin-gfm": "1.0.67",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@radix-ui/react-collapsible": "1.1.20",
     "@radix-ui/react-dialog": "1.1.23",
     "@radix-ui/react-dropdown-menu": "2.1.24",
@@ -221,7 +223,7 @@
     "react-markdown": "10.1.0",
     "rehype-sanitize": "6.0.0",
     "remark-gfm": "4.0.1",
-    "sharp": "0.35.4",
+    "sharp": "0.35.5",
     "shiki": "4.4.3",
     "sqlite-vec": "0.1.9",
     "streamdown": "2.6.0",
@@ -258,7 +260,7 @@
     "playwright": "1.63.0",
     "pptxgenjs": "4.0.1",
     "ultracite": "7.1.5",
-    "vitest": "4.1.10",
+    "vitest": "4.1.11",
     "web-tree-sitter": "0.26.13"
   },
   "peerDependencies": {
@@ -271,6 +273,9 @@
   "engines": {
     "bun": ">=1.4.1"
   },
+  "patchedDependencies": {
+    "evalite@1.0.0-beta.16": "patches/evalite@1.0.0-beta.16.patch"
+  },
   "trustedDependencies": [
     "bun",
     "node-llama-cpp"

package/spec/cli.md

@@ -108,7 +108,7 @@ equivalent files fail closed as ambiguous.
 | models clear       | no     | no      | no    | no   | no    | terminal |
 | models path        | yes    | no      | no    | no   | no    | terminal |
 | publish export     | yes    | no      | no    | no   | no    | terminal |
-| cleanup            | no     | no      | no    | no   | no    | terminal |
+| cleanup            | yes    | no      | no    | no   | no    | terminal |
 | doctor             | yes    | no      | no    | yes  | no    | terminal |
 | mcp                | no     | no      | no    | no   | no    | stdio    |
 | mcp install        | yes    | no      | no    | no   | no    | terminal |
@@ -241,11 +241,15 @@ the model with `id`, `model`, `dimensions`, `state` (`active`|`shadow`),
 `compatibleRuntimes` (runtimes that read it) and `incompatibleRuntimes`.
 Terminal output prints a `Vector partitions:` block
 unless there is exactly one healthy partition. `collections`, `totalDocuments`
-and `totalChunks` cover configured collections only: a collection removed from
-config is not reported even while its rows remain in the index until the next
-command that syncs collections (`gno update`, `gno index`, `gno cleanup`). The
+and `totalChunks` cover configured collections only. Opening an index never
+deletes a collection that has documents: one the config does not list (removed
+by hand, or a different config opened this index) is reported in
+`staleCollections` (`name`, `documents`; omitted when empty) and under
+`Collections not in this config` in text and Markdown, and every command other
+than `status`, `doctor`, `cleanup` and `collection remove/rename` exits with an
+error naming it until it is added back or `gno cleanup` deletes it. The
 embedding backlog likewise counts chunks of configured collections only.
-`gno collection remove` syncs at once, so no rows remain. `totalChunks` counts the
+`gno collection remove` deletes the collection's documents at once. `totalChunks` counts the
 distinct chunks of active documents; chunks left by deleted documents do not
 count. Per-collection chunk totals remain deduplicated by canonical chunk;
 embedded counts require matching current inputs for every active owner within
@@ -363,6 +367,30 @@ Semantic and connector stages remain independent; passive status never starts a
 model runtime or connector process. `gno status` still exits 0 when activation
 is unhealthy so scripts can inspect the structured state.
 
+Status checks every configured collection root when it runs, so the report
+reflects the folder now, not the last sync. A root is unavailable when it
+cannot be listed (the check `gno update` uses before proving a file deleted:
+open the directory and read one entry). For `sourceAvailability: local`
+collections the root is checked without listing it (`stat` as a directory, then
+read and search permission via `access`), so status never lists, and so never
+materializes, a dataless cloud folder; a partially present
+cloud folder is not reported. The checks run concurrently and add no timeout
+of their own. An unavailable root adds `rootError` to that collection:
+
+```json
+"rootError": {
+  "code": "SOURCE_AVAILABILITY_UNKNOWN",
+  "message": "Collection root is missing or unreadable (ENOENT: no such file or directory); indexed documents were kept"
+}
+```
+
+The message names the filesystem error but never the path (`path` carries it,
+and is omitted for remote REST/HTTP MCP callers). The collection's documents
+stay indexed and counted, and `healthy` is false (terminal `Health: DEGRADED`).
+Terminal output prints `Root unavailable: <path>` and `[<code>] <message>`
+under the collection line; Markdown output adds a `Root unavailable` line after
+the collections table. The key is absent while the root is available.
+
 JSON output also includes `resident` using
 `gno://schemas/resident-status@1.0`. Direct `gno status` is intentionally
 truthful about its lifecycle: `mode:"direct-cli"`, `resident:false`, no
@@ -1498,6 +1526,16 @@ Important notes:
 - hyphenated compounds such as `real-time`, `gpt-4`, and `DEC-0054` are handled intentionally
 - malformed lexical syntax returns exit code `1`
 
+**Snippets:**
+
+Ranking never builds snippets. After the final rows are chosen, each default
+snippet is a window of about 32 words from the stored chunk that best covers
+the positive query terms (rarer terms count more; ties go to the earliest
+chunk), with matching words wrapped in `<mark>`/`</mark>` and `...` where the
+window cuts the chunk. `snippetRange` and `line` name that chunk's line span
+(after any leading frontmatter is skipped). With `--intent`, the steered chunk
+is used. `--full` and `--line-numbers` return raw text without markers.
+
 **Output (JSON):**
 See [Output Schemas](./output-schemas/search-results.schema.json)
 
@@ -1697,7 +1735,7 @@ active with `sourceCount: 1`.
 [explain] bm25: 45 candidates
 [explain] vector: 38 candidates
 [explain] graph: seeds=5, candidates=4/20, explicit=3, inferred=1, ambiguous=0, similarity=0
-[explain] fusion: RRF k=60, 52 unique candidates
+[explain] fusion: RRF k=60, 52 unique documents (best rank per list)
 [explain] rerank: top 20 reranked
 [explain] result 1: score=0.92 (bm25=0.85, vec=0.78, rerank=0.95)
 ```
@@ -2965,13 +3003,19 @@ included, is refused. JSON output is
 
 ### gno cleanup
 
-Remove documents of collections no longer in the config, then orphaned
-content, chunks, and vectors not referenced by active documents.
+Delete the documents of indexed collections the config does not list, then
+orphaned content, chunks, and vectors not referenced by active documents.
+Before deleting, cleanup writes the collections it is about to delete to
+stderr: `Deleting collections not in this config:` and one
+`<name>: <n> document(s)` line each, or `{"deleting":[{"name","documents"}]}`
+with `--json`. With `--json`, stdout is
+`{"droppedCollections":[{"name","documents"}],"orphanedContent","orphanedChunks","orphanedVectors","expiredCache"}`.
+This is the only command that deletes collections the config omits.
 
 **Synopsis:**
 
 ```bash
-gno cleanup [--lock-wait <duration>] [--no-wait]
+gno cleanup [--json] [--lock-wait <duration>] [--no-wait]
 ```
 
 **Exit Codes:**
@@ -3077,6 +3121,13 @@ start it again, or, for a resident started by another GNO version (which
 `--stop` refuses), `kill <pid>` (`taskkill /PID <pid>` on Windows) and start it
 again.
 
+The `collection-roots` check applies the `gno status` root check to every
+configured collection. It is `ok` when all roots are available and `warn`
+otherwise: the message lists the collections, and `details` holds one line
+per collection (`<name>: <path> [<code>] <message>`) plus the repair
+(reconnect or restore the folder; if it moved, change the collection's path
+and run `gno update`). The warning keeps exit 0 but makes `healthy` false.
+
 The `findings-pass` check reports the daemon's scheduled findings pass from
 its persisted run state: `ok` when disabled or the last run succeeded, `warn`
 on `skipped_lease` / `overdue` / no recorded run, `error` on `failed` or a
@@ -3462,15 +3513,22 @@ gno skill install [--scope <project|user>] [--target <claude|codex|opencode|open
 
 **Options:**
 
-| Option     | Type    | Default | Description                                                   |
-| ---------- | ------- | ------- | ------------------------------------------------------------- |
-| `--scope`  | string  | project | `project` (.claude/skills/) or `user` (~/.claude/skills/)     |
-| `--target` | string  | claude  | `claude`, `codex`, `opencode`, `openclaw`, `hermes`, or `all` |
-| `--force`  | boolean | false   | Overwrite existing skill without prompting                    |
+| Option     | Type    | Default | Description                                                                                         |
+| ---------- | ------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `--scope`  | string  | project | `project` (.claude/skills/) or `user` (~/.claude/skills/, or `$CLAUDE_CONFIG_DIR/skills/` when set) |
+| `--target` | string  | claude  | `claude`, `codex`, `opencode`, `openclaw`, `hermes`, or `all`                                       |
+| `--force`  | boolean | false   | Overwrite existing skill without prompting                                                          |
 
 **Behavior:**
 
-1. Resolves target path based on scope and target
+1. Resolves target path based on scope and target. At user scope the Claude
+   target uses `$CLAUDE_CONFIG_DIR/skills/gno` and the Codex target
+   `$CODEX_HOME/skills/gno` when the variable is set (trimmed; empty means
+   unset; a relative path is a validation error, exit 1), validated exactly
+   as `gno agents` does. `GNO_SKILLS_HOME_OVERRIDE` suppresses both variables;
+   `CLAUDE_SKILLS_DIR`/`CODEX_SKILLS_DIR` take precedence over everything.
+   The same resolution applies to `skill uninstall` and `skill paths`, and the
+   output prints the resolved directory.
 2. If skill exists and not `--force`/`--yes`: error
 3. Atomically installs skill directory (temp + rename)
 4. Copies SKILL.md, reference files, and nested recipe files
@@ -3685,6 +3743,8 @@ gno agents install [--target <claude|codex|cursor|opencode|grok|hermes|openclaw|
    same real file are written once (`covered via <target> (same file)`).
 6. `GNO_AGENTS_HOME_OVERRIDE` overrides the home directory (testing/sandboxed
    verification); any home override suppresses harness config-dir env vars.
+   `CLAUDE_CONFIG_DIR`/`CODEX_HOME` are trimmed, an empty value counts as
+   unset, and a relative path is a validation error.
 
 **Output (JSON):**
 
@@ -3716,7 +3776,8 @@ gno agents install [--target <claude|codex|cursor|opencode|grok|hermes|openclaw|
 ```
 
 `action` is one of `install`, `update`, `current`, `covered`, `not-detected`,
-`error` (and `remove`, `absent` for uninstall). A covered row's `path` is the
+`error` (and `remove` for uninstall; `absent` for update and uninstall when
+the file holds no block). A covered row's `path` is the
 file the harness actually reads (its covering target's file). With
 `--dry-run`, a `diffs` array of unified diffs is included. When
 any target failed on install/update, `manualBlock` carries the complete block
@@ -3736,8 +3797,13 @@ text to paste. Schema: `spec/output-schemas/agents-mutation.schema.json`
 ### gno agents update
 
 Refresh an installed block in place (block-version migration). Same options,
-output, and exit codes as `agents install`; both verbs converge the block to
-the current release — `update` exists for operator intent clarity.
+output, and exit codes as `agents install`, and an existing block converges
+to the current release exactly as with install. Unlike install, `update`
+never adds a block: a target whose file has no GNO agents block (or does not
+exist) is reported `absent` with the detail
+``no GNO agents block to refresh; run `gno agents install` to add one``,
+and the file is left untouched (no write, no backup, no file created). An
+`absent` row is not a failure (exit 0).
 
 ```bash
 gno agents update [--target <...>] [--extra-dir <path>]... [--dry-run] [--json]
@@ -3812,6 +3878,32 @@ gno agents uninstall [--target <...>] [--extra-dir <path>]... [--dry-run] [--jso
 
 ---
 
+### gno metadata
+
+List the typed metadata keys active documents carry.
+
+**Synopsis:**
+
+```bash
+gno metadata [-c, --collection <name>] [--values <n>] [--json] [--md]
+```
+
+**Options:**
+
+| Option             | Type    | Description                                      |
+| ------------------ | ------- | ------------------------------------------------ |
+| `-c, --collection` | string  | Only documents in this collection                |
+| `--values`         | integer | Common values listed per key (1-100, default 10) |
+| `--json`           | flag    | JSON output (`gno://schemas/metadata-summary`)   |
+| `--md`             | flag    | Markdown output                                  |
+
+**Exit Codes:**
+
+- 0: Success
+- 1: `--values` out of range
+
+---
+
 ### gno tags list
 
 List all tags with document counts.
@@ -4801,23 +4893,23 @@ Write-lease contention on `index` / `update` / `embed` does not use the generic
 
 ## Environment Variables
 
-| Variable                   | Description                                                                                                                                                                     |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GNO_CONFIG_DIR`           | Override config directory                                                                                                                                                       |
-| `GNO_DATA_DIR`             | Override data directory (DB location)                                                                                                                                           |
-| `GNO_CACHE_DIR`            | Override cache directory (models)                                                                                                                                               |
-| `NO_COLOR`                 | Disable colored output (standard)                                                                                                                                               |
-| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                                                                           |
-| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                                                                                |
-| `GNO_MEMORY_CALLER`        | Default `--caller` identity for `gno remember` / `gno recall`                                                                                                                   |
-| `GNO_MEMORY_SESSION`       | Default `--session` identity for `gno remember` / `gno recall`                                                                                                                  |
-| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                                                                                |
-| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                                                                                 |
-| `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file under it (suppressed by an explicit home override); `gno sessions discover` also checks its `projects/` |
-| `CODEX_HOME`               | Codex config dir; same rule as `CLAUDE_CONFIG_DIR`; `gno sessions discover` checks its `sessions/`                                                                              |
-| `OPENCLAW_STATE_DIR`       | OpenClaw state dir checked by `gno sessions discover` (else `$OPENCLAW_HOME/.openclaw` or `~/.openclaw`)                                                                        |
-| `HERMES_HOME`              | Hermes home checked by `gno sessions discover` (else `~/.hermes`)                                                                                                               |
-| `GNO_SESSIONS_HOOKS`       | `off` or `0` makes every installed `gno sessions hook` return immediately without admitting work                                                                                |
+| Variable                   | Description                                                                                                                                                                                                                       |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GNO_CONFIG_DIR`           | Override config directory                                                                                                                                                                                                         |
+| `GNO_DATA_DIR`             | Override data directory (DB location)                                                                                                                                                                                             |
+| `GNO_CACHE_DIR`            | Override cache directory (models)                                                                                                                                                                                                 |
+| `NO_COLOR`                 | Disable colored output (standard)                                                                                                                                                                                                 |
+| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                                                                                                                             |
+| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                                                                                                                                  |
+| `GNO_MEMORY_CALLER`        | Default `--caller` identity for `gno remember` / `gno recall`                                                                                                                                                                     |
+| `GNO_MEMORY_SESSION`       | Default `--session` identity for `gno remember` / `gno recall`                                                                                                                                                                    |
+| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                                                                                                                                  |
+| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                                                                                                                                   |
+| `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file and `gno skill --scope user` the Claude skill dir under it (suppressed by an explicit home override); `gno sessions discover` also checks its `projects/` |
+| `CODEX_HOME`               | Codex config dir; same rule as `CLAUDE_CONFIG_DIR` (instruction file and user-scope skill dir); `gno sessions discover` checks its `sessions/`                                                                                    |
+| `OPENCLAW_STATE_DIR`       | OpenClaw state dir checked by `gno sessions discover` (else `$OPENCLAW_HOME/.openclaw` or `~/.openclaw`)                                                                                                                          |
+| `HERMES_HOME`              | Hermes home checked by `gno sessions discover` (else `~/.hermes`)                                                                                                                                                                 |
+| `GNO_SESSIONS_HOOKS`       | `off` or `0` makes every installed `gno sessions hook` return immediately without admitting work                                                                                                                                  |
 
 ---
 

package/spec/evals-agentic.md

@@ -268,7 +268,9 @@ accounting, temp paths, and oracle data are excluded from both the agent history
 and its UTF-8 byte count.
 
 For Capsule evidence bundles, `content` is byte-for-byte the production MCP
-`gno-context-agent-v1` text projection. Exact evidence is not duplicated in the
+`gno-context-agent-v2` text projection. Promotion also accepts recorded
+`gno-context-agent-v1` receipts, whose evidence tuples end at the egress
+position (11 positions instead of 13). Exact evidence is not duplicated in the
 normalized evidence field. The benchmark charges the complete normalized
 agent-visible envelope containing that text once; the full canonical Capsule
 in MCP `structuredContent` is application-only and excluded. This target models