@gmickel/gno 2.3.2 → 2.4.0

package/README.md

@@ -15,9 +15,15 @@ A local knowledge engine for your notes, code, PDFs, and Office docs. Hybrid sea
 ```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 skill install --target claude --scope user # choose your agent below
+gno agents install --target claude # teach retrieval and writing discipline
+gno agents verify --target claude
 ```
 
+Custom fields such as project, approval status, and numeric confidence can
+constrain retrieval with [typed metadata filters](docs/TYPED-METADATA.md),
+across CLI, MCP, SDK, REST, and the Web UI.
+
 ## What you get
 
 **One local index across everything you have.** Markdown, PDFs, Office documents, plain text, source code, and portable mail, calendar and transcript exports. Point it at a folder that mixes all of them and it handles the mix.
@@ -66,6 +72,11 @@ bun install -g @gmickel/gno
 # semantic embedding continues independently in the background.
 gno setup ~/notes --name notes
 
+# Connect your agent and teach the retrieval protocol (Claude shown)
+gno skill install --target claude --scope user
+gno agents install --target claude
+gno agents verify --target claude
+
 # 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}"
@@ -97,7 +108,9 @@ 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)
+> [!TIP]
+> **OpenClaw and Hermes Agent:** Use GNO as a second brain or LLM wiki. Install the skill and retrieval protocol together so your agent knows when to retrieve, which search path to use, and how to cite and maintain knowledge.
+> [OpenClaw setup](https://gno.sh/integrations/openclaw) · [Hermes setup](https://gno.sh/integrations/hermes) · [Shared ClawHub bundle](https://clawhub.ai/gmickel/gno)
 
 ---
 
@@ -117,7 +130,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.3.2**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.4.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
@@ -1177,7 +1190,7 @@ bun test
 bun run lint && bun run typecheck
 ```
 
-> **Contributing**: [CONTRIBUTING.md](.github/CONTRIBUTING.md)
+> **Contributing**: See [checks and release policy](.github/CONTRIBUTING.md). Documentation-only and CI-only changes do not require a product version bump or release.
 
 ### Evals and Benchmark Deltas
 
@@ -1194,6 +1207,13 @@ bun run eval:hybrid:delta
 - Benchmark guide: [evals/README.md](./evals/README.md)
 - Latest baseline snapshot: [evals/fixtures/hybrid-baseline/latest.json](./evals/fixtures/hybrid-baseline/latest.json)
 
+Document-level benchmark hits do not prove that every answer-bearing passage
+survives retrieval and a context budget. The opt-in
+[adversarial evidence gate](./evals/README.md#adversarial-evidence-coverage-development-only)
+checks complete required source spans, multi-source coverage, and fixed-reader
+abstention with replay and explicit cached-model native runs. It preserves baseline
+misses and does not change ranking defaults.
+
 ### Code Embedding Benchmark Harness
 
 GNO also has a dedicated harness for comparing alternate embedding models on code retrieval without touching product defaults:

package/assets/skill/SKILL.md

@@ -647,3 +647,33 @@ MCP-equivalent write tool:
 | 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)           |
+
+## Custom metadata filters
+
+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:
+
+```json
+{
+  "op": "and",
+  "predicates": [
+    { "op": "eq", "key": "project", "value": "atlas" },
+    { "op": "gte", "key": "confidence", "value": 0.8 }
+  ]
+}
+```
+
+Membership operators `in`, `nin`, and `all` use plural `values`, not `value`:
+`{"op":"all","key":"reviewers","values":["ana","sam"]}`.
+Other leaves use singular `value`. `not` uses `predicate`; `and/or` use `predicates`.
+
+Strings are case-sensitive and never coerced to numbers or booleans. `eq/ne`
+accept scalars, ordering accepts numbers, `in/nin` test scalar/array membership,
+`all` requires an array, and `exists` takes a boolean. `ne/nin` require presence;
+`not(eq)`/`not(in)` can include missing fields. Invalid metadata is excluded even
+under negation. Never silently remove a requested filter. If coverage is
+incomplete, inspect warnings and diagnose the expected target with the same
+filter before relaxing it; correct source metadata and run `gno update` when
+repair is authorized. Preserve collection, authority, and memory scope.

package/assets/skill/cli-reference.md

@@ -1062,3 +1062,15 @@ gno completion output <bash|zsh|fish>
 | 1    | Validation error (bad args)                                          |
 | 2    | Runtime error (IO, DB, model)                                        |
 | 3    | `NOT_RUNNING` — `--status` / `--stop` found no live matching process |
+
+## Custom metadata filters
+
+```bash
+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}'
+```
+
+The same `--filter` JSON works on `vsearch`, `query`, `ask`, and `context build`.
+Use only indexed `gno.metadata` fields. See SKILL.md for strict types,
+missing-field semantics, and diagnose-before-relaxing guidance. Repair metadata
+with `gno update` when authorized; no predicate expands existing scope.

package/assets/skill/examples.md

@@ -467,3 +467,18 @@ Press **N** in `gno serve`, write the note, and open **Source** only when you
 need provenance fields such as URL, author, observed date, or external id. The
 success view reports the write result, FTS sync state, and embed state
 separately.
+
+## Custom metadata filters
+
+Find Atlas decisions reviewed by both Ana and Sam:
+
+```bash
+gno query "rollout decision" --filter '{"op":"and","predicates":[{"op":"eq","key":"project","value":"atlas"},{"op":"all","key":"reviewers","values":["ana","sam"]}]}'
+```
+
+This requires indexed nested `gno.metadata` with `project: atlas` and a
+`reviewers` string array. To include documents without a status, use
+`{"op":"not","predicate":{"op":"eq","key":"status","value":"archived"}}`.
+To require a present non-archived string status, use
+`{"op":"ne","key":"status","value":"archived"}`. Invalid metadata matches
+neither; check coverage and diagnose before relaxing the query.

package/assets/skill/mcp-reference.md

@@ -201,3 +201,19 @@ transport session, never from tool arguments.
 gno mcp uninstall
 gno mcp uninstall -t claude-code
 ```
+
+## Custom metadata filters
+
+`gno_search`, `gno_vsearch`, `gno_query`, `gno_ask`, and `gno_context` accept
+`filter` alongside their existing scope fields:
+
+```json
+{
+  "query": "rollout",
+  "filter": { "op": "gte", "key": "confidence", "value": 0.8 }
+}
+```
+
+Pass the object, not a JSON-encoded string. Preserve the filter on retries;
+inspect coverage warnings rather than silently broadening retrieval. See
+SKILL.md for strict types and missing-field semantics.

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

@@ -0,0 +1 @@
+ae739d8da342a7f932f8097e1d4d852ff7c46b722b8e979303b1213eaf2d76a5  gno-browser-clipper-v2.4.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.3.2"
+  "version": "2.4.0"
 }

package/package.json

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

package/spec/cli.md

@@ -4171,3 +4171,33 @@ because reindexing is temporarily unavailable
 - [MCP Specification](./mcp.md)
 - [Output Schemas](./output-schemas/)
 - [PRD](../docs/prd.md)
+
+### Typed metadata predicates
+
+Retrieval commands accept `--filter '<JSON>'`. The same `filter` object is
+accepted by SDK, MCP and REST retrieval inputs. Metadata comes from the nested
+YAML `gno.metadata` map; ordinary frontmatter keys remain unchanged.
+
+The bounded recursive contract is:
+
+- `{op:"and"|"or", predicates: Predicate[]}` (nonempty).
+- `{op:"not", predicate: Predicate}`.
+- `{op:"eq"|"ne", key:string, value:string|number|boolean}`.
+- `{op:"gt"|"gte"|"lt"|"lte", key:string, value:number}`.
+- `{op:"in"|"nin"|"all", key:string, values:Scalar[]}` (nonempty, homogeneous).
+- `{op:"exists", key:string, value:boolean}`.
+
+Comparison is type-strict and text is exact/case-sensitive. Positive comparisons,
+`ne` and `nin` require a present field. Logical `not` negates the complete child,
+so missing fields satisfy `not(eq(...))`. `eq/ne` require scalar fields; `in/nin`
+accept scalar or array fields; `all` requires an array. Invalid metadata and
+documents awaiting ingestion repair are ineligible for every typed predicate,
+including negation. Filtered queries report incomplete coverage until repaired.
+Limits: 64 metadata keys, 128-character keys, 4096-character strings, 128 array
+members, 64 KiB serialized metadata/filter, 128 predicate nodes, depth 8.
+Keys `__proto__`, `prototype`, and `constructor` are reserved.
+
+For executable examples and the missing-field truth table, see
+[Typed metadata filters](../docs/TYPED-METADATA.md). `ne` additionally requires
+the field's scalar type to match the operand; `nin` matches a present scalar or
+array with no exact typed member match. Ordering never coerces strings.

package/spec/db/schema.sql

@@ -121,6 +121,8 @@ CREATE TABLE IF NOT EXISTS contexts (
 -- ─────────────────────────────────────────────────────────────────────────────
 
 CREATE TABLE IF NOT EXISTS documents (
+  typed_metadata TEXT, -- validated gno.metadata, NULL until extraction
+  metadata_error TEXT, -- bounded path-only extraction diagnostic
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   collection TEXT NOT NULL,
   rel_path TEXT NOT NULL,

package/spec/evals.md

@@ -1110,3 +1110,51 @@ ordering, and rerank interaction without LLM or fixture drift.
    - CONTRIBUTING.md updated with DoD eval requirements
    - This spec (spec/evals.md) matches implementation
 ````
+
+## Adversarial evidence gate (development only)
+
+`bun evals/acceptance/evidence-cli.ts --input <observations.json> --output <report.json>`
+validates and scores a frozen `gno-evidence-run-v1` observation bundle. Native
+collection is explicit (`--native --output <new-directory>`), uses only cached
+models and isolated synthetic indexes, and compares current defaults with
+`noExpand: true`. This is not a public GNO command or a default CI eval.
+
+The fixture contract `gno-evidence-fixtures-v1` contains documents (URI, title,
+exact content and SHA-256), verified required spans (stable ID, source hash,
+1-based inclusive line range and span hash), and cases. Cases pin query/intent,
+collection, family, usable token budget, independent UTF-8 byte cap, acceptable
+alternative sets of required span IDs, answerability, expected literal answer
+values, and a must-cover flag. Empty answerable evidence sets, invalid ranges,
+duplicate IDs, stale hashes, unknown span references and answer-bearing names
+in synthetic paths are rejected. Fixture bytes are pinned separately; baseline
+pins are never regenerated to hide a failure.
+
+Every observation names a case, arm (`current` or `noExpand`), fixture digest,
+runtime/model/settings identity, native coverage and invalid-run reasons. Its
+stages (`retrieval`, `fusion`, `rerank_input`, `delivery`) contain observed
+passages with URI, source hash, UTF-16 source offsets, exact text and an input
+identity. Stages not captured are null, not empty successful stages. Clipping
+metadata retains the original selected extent when known. Passage validity is
+checked against the pinned source. A required span survives only when verified
+passages in one actual input together cover every character; separate reranker
+inputs cannot pool coverage. Partial, clipped, split-across-inputs, missing and
+unknown outcomes remain distinct. Duplicate appearances cannot add coverage.
+
+The `gno-evidence-report-v1` output retains per-span/stage outcomes, all-required
+and any-required evidence coverage, first observed loss stage, fixed-reader
+answer/abstention outcome, UTF-8 bytes, declared-estimator token cost, exact native
+tokenization observations when available, elapsed time and resource samples.
+Actual tokenizer observations are not mislabeled as total inference billing;
+missing observations remain null. Reader outcomes use delivered verified spans,
+expected fixture values and the actual answer verification result, not document
+hits or reconstructed snippets. Retrieval-only runs have a null reader outcome.
+
+Comparison requires exactly one observation per case/arm, matching fixture,
+model/runtime identity and budgets; only the declared noExpand setting differs.
+Native fallback or missing required model execution invalidates a native pair.
+Replay success never certifies native execution. Both arms and baseline misses
+are retained. Candidate adoption requires all deterministic guard cases and
+must-cover cases, no reduction in held-out complete evidence or fixed-reader
+success, and valid comparisons. A baseline miss is a finding; this gate does not
+change ranking defaults to make itself green. The exact strict JSON schemas
+ship beside the other evaluation output schemas.

package/spec/mcp.md

@@ -3054,3 +3054,15 @@ Schemas: `collection-egress-policy.schema.json`,
 - [CLI Specification](./cli.md)
 - [Output Schemas](./output-schemas/)
 - [MCP Protocol Specification](https://modelcontextprotocol.io/specification/)
+
+### Typed metadata retrieval filter
+
+Applicable retrieval tools accept the same bounded `filter` predicate documented
+in `spec/cli.md`. Invalid filters fail validation with a field path. Predicates
+intersect caller scope before candidate limits and never expand authority.
+
+`gno_search`, `gno_vsearch`, `gno_query`, `gno_ask`, and `gno_context` expose
+`filter`. The strict discriminated contract is recorded in
+[metadata-predicate.schema.json](output-schemas/metadata-predicate.schema.json).
+See [Typed metadata filters](../docs/TYPED-METADATA.md) for exact membership,
+missing-field, invalid-document, and bounded-input semantics.

package/spec/output-schemas/ask.schema.json

@@ -28,6 +28,18 @@
             "type": "object",
             "required": ["verificationRequested", "abstained"],
             "properties": {
+              "warnings": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["code", "message"],
+                  "properties": {
+                    "code": { "type": "string" },
+                    "message": { "type": "string" }
+                  }
+                }
+              },
               "verificationRequested": { "const": true },
               "abstained": {}
             }