@gmickel/gno 1.18.0 → 1.19.0

package/README.md

@@ -94,7 +94,7 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.17.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.18.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -553,9 +553,9 @@ Connect GNO to Claude Desktop, Cursor, Raycast, and more:
 
 ![GNO MCP](./assets/screenshots/mcp.jpg)
 
-GNO exposes 19 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
+GNO exposes 21 tools by default via [Model Context Protocol](https://modelcontextprotocol.io),
 including the core retrieval tools below. Starting MCP with `--enable-write`
-adds 11 opt-in mutation tools, for 30 total.
+adds 15 opt-in mutation tools, for 36 total.
 
 | Tool                 | Description                           |
 | :------------------- | :------------------------------------ |
@@ -571,6 +571,8 @@ adds 11 opt-in mutation tools, for 30 total.
 | `gno_similar`        | Find semantically similar documents   |
 | `gno_graph`          | Get knowledge graph (nodes and edges) |
 | `gno_status`         | Index health check                    |
+| `gno_trace_list`     | List private local retrieval receipts |
+| `gno_trace_show`     | Inspect one bounded trace receipt     |
 
 **Design**: Default MCP mode is read-only: retrieval, graph, status, and job
 inspection. Your AI assistant synthesizes answers from retrieved context. Write

package/assets/skill/SKILL.md

@@ -71,6 +71,7 @@ Recipe rules:
 | **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/build/verify`                         | Configure guidance or compile/verify evidence Capsules |
+| **Traces**   | `trace list/show/label/export/replay/delete/purge`               | Manage and replay private retrieval receipts           |
 | **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                 |
 | **Serve**    | `serve`, `daemon`                                                | One resident Web/headless gateway and watcher          |
 | **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                        |
@@ -168,6 +169,24 @@ When the user wants a synthesized answer instead of ranked evidence:
 gno ask "What changed in the deployment process?" --answer
 ```
 
+Trace recording is local and off by default. `metadata` mode is diagnostic-only
+and omits raw query/goal/filter values; `replay` is separate explicit consent
+to retain those bounded inputs under configured local retention limits. No
+receipt is uploaded automatically, and disabling capture does not disable
+inspection or deletion of existing receipts.
+
+For an explicitly labeled, replay-mode receipt, export content-free qrels and
+compare one candidate without changing the live ranking setup:
+
+```bash
+gno trace export <trace-id> --format qrels --output qrels.json
+gno trace replay <qrels-export-id> --candidate hybrid --md
+```
+
+Treat replay as evidence for a human promotion decision. It always reports
+`applied: false`; never claim that replay changed boosts, prompts, models,
+configuration, traces, or source files.
+
 ## MCP Retrieval Strategy
 
 For a long-lived client that supports Streamable HTTP, start one resident owner
@@ -177,6 +196,14 @@ Serve is always loopback-only. Only daemon accepts an explicit non-loopback bind
 and only with a restrictive bearer-token file plus exact Host/Origin allowlists.
 Authentication never enables writes by itself.
 
+For explicit retrieval feedback, use `gno_trace_list` and `gno_trace_show` to
+inspect local receipts. Never infer irrelevance from a missing click, a failed
+request, or a partial/cancelled outcome. Use write-enabled
+`gno_trace_label` only when the user explicitly supplies a
+relevant/irrelevant/missing-expected judgment. Trace export/delete/purge are
+also write tools and require separate write enablement; bearer authentication
+alone is insufficient.
+
 When using GNO through MCP, prefer this retrieval order:
 
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -28,6 +28,7 @@
   "files": [
     "assets",
     "bunfig.toml",
+    "spec",
     "src",
     "THIRD_PARTY_NOTICES.md",
     "vendor"

package/spec/AGENTS.md

@@ -0,0 +1,83 @@
+# Specifications
+
+Interface contracts and schemas for GNO.
+
+## Structure
+
+```
+spec/
+├── cli.md              # CLI commands, flags, exit codes
+├── mcp.md              # MCP tools, resources, schemas
+├── evals.md            # Evaluation framework spec
+├── db/
+│   └── schema.sql      # Database schema
+└── output-schemas/     # JSON schemas for all outputs
+    ├── search-results.schema.json
+    ├── ask.schema.json
+    ├── status.schema.json
+    └── ...
+```
+
+## Spec-First Workflow
+
+When adding/modifying commands or outputs:
+
+1. **Update spec first** - Define the interface before implementation
+2. **Add/update JSON schema** - If output shape changes
+3. **Add contract tests** - In `test/spec/schemas/`
+4. **Implement** - Code to match spec
+5. **Verify** - `bun test` passes
+
+## JSON Schemas
+
+Schemas define the structure of all JSON outputs:
+
+- Validated by contract tests
+- Used for documentation
+- Enable type generation
+
+### Schema Naming
+
+- `<command>.schema.json` - Single command output
+- `<noun>-<verb>.schema.json` - Compound names
+
+### Adding a New Schema
+
+1. Create `spec/output-schemas/<name>.schema.json`
+2. Add contract test in `test/spec/schemas/`
+3. Reference in spec document
+
+## Contract Tests
+
+Tests in `test/spec/schemas/` validate outputs against schemas:
+
+```typescript
+import schema from "../../spec/output-schemas/search-results.schema.json";
+
+test("search --json matches schema", async () => {
+  const result = await runSearch("query", { json: true });
+  expect(() => validate(schema, result)).not.toThrow();
+});
+```
+
+## Spec Documents
+
+### cli.md
+
+- Exit codes and meanings
+- Global flags
+- Output format support matrix
+- All commands with options
+
+### mcp.md
+
+- Server capabilities
+- Tool schemas and responses
+- Resource URI schemes
+- Error codes
+
+### evals.md
+
+- Evaluation metrics
+- Test case format
+- Scoring methodology

package/spec/CLAUDE.md

@@ -0,0 +1,83 @@
+# Specifications
+
+Interface contracts and schemas for GNO.
+
+## Structure
+
+```
+spec/
+├── cli.md              # CLI commands, flags, exit codes
+├── mcp.md              # MCP tools, resources, schemas
+├── evals.md            # Evaluation framework spec
+├── db/
+│   └── schema.sql      # Database schema
+└── output-schemas/     # JSON schemas for all outputs
+    ├── search-results.schema.json
+    ├── ask.schema.json
+    ├── status.schema.json
+    └── ...
+```
+
+## Spec-First Workflow
+
+When adding/modifying commands or outputs:
+
+1. **Update spec first** - Define the interface before implementation
+2. **Add/update JSON schema** - If output shape changes
+3. **Add contract tests** - In `test/spec/schemas/`
+4. **Implement** - Code to match spec
+5. **Verify** - `bun test` passes
+
+## JSON Schemas
+
+Schemas define the structure of all JSON outputs:
+
+- Validated by contract tests
+- Used for documentation
+- Enable type generation
+
+### Schema Naming
+
+- `<command>.schema.json` - Single command output
+- `<noun>-<verb>.schema.json` - Compound names
+
+### Adding a New Schema
+
+1. Create `spec/output-schemas/<name>.schema.json`
+2. Add contract test in `test/spec/schemas/`
+3. Reference in spec document
+
+## Contract Tests
+
+Tests in `test/spec/schemas/` validate outputs against schemas:
+
+```typescript
+import schema from "../../spec/output-schemas/search-results.schema.json";
+
+test("search --json matches schema", async () => {
+  const result = await runSearch("query", { json: true });
+  expect(() => validate(schema, result)).not.toThrow();
+});
+```
+
+## Spec Documents
+
+### cli.md
+
+- Exit codes and meanings
+- Global flags
+- Output format support matrix
+- All commands with options
+
+### mcp.md
+
+- Server capabilities
+- Tool schemas and responses
+- Resource URI schemes
+- Error codes
+
+### evals.md
+
+- Evaluation metrics
+- Test case format
+- Scoring methodology

package/spec/bench-fixture.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GNO Bench Fixture",
+  "type": "object",
+  "required": ["version", "queries"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "tags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "collection": { "type": "string", "minLength": 1 },
+    "topK": { "type": "integer", "minimum": 1 },
+    "candidateLimit": { "type": "integer", "minimum": 1 },
+    "modes": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "enum": [
+              "bm25",
+              "vector",
+              "hybrid",
+              "fast",
+              "no-rerank",
+              "thorough"
+            ]
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "type": {
+                "type": "string",
+                "enum": ["bm25", "vector", "hybrid"]
+              },
+              "mode": {
+                "type": "string",
+                "enum": [
+                  "bm25",
+                  "vector",
+                  "hybrid",
+                  "fast",
+                  "no-rerank",
+                  "thorough"
+                ]
+              },
+              "noExpand": { "type": "boolean" },
+              "noRerank": { "type": "boolean" },
+              "candidateLimit": { "type": "integer", "minimum": 1 },
+              "limit": { "type": "integer", "minimum": 1 },
+              "queryModes": {
+                "type": "array",
+                "items": { "$ref": "#/definitions/queryMode" }
+              }
+            }
+          }
+        ]
+      }
+    },
+    "queries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "query"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "query": { "type": "string", "minLength": 1 },
+          "expected": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expectedDocuments": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expectedUris": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "judgments": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["relevance"],
+              "additionalProperties": false,
+              "properties": {
+                "docid": { "type": "string", "minLength": 1 },
+                "doc": { "type": "string", "minLength": 1 },
+                "uri": { "type": "string", "minLength": 1 },
+                "relevance": { "type": "number", "minimum": 0 }
+              },
+              "anyOf": [
+                { "required": ["docid"] },
+                { "required": ["doc"] },
+                { "required": ["uri"] }
+              ]
+            }
+          },
+          "collection": { "type": "string", "minLength": 1 },
+          "topK": { "type": "integer", "minimum": 1 },
+          "queryModes": {
+            "type": "array",
+            "items": { "$ref": "#/definitions/queryMode" }
+          }
+        },
+        "anyOf": [
+          { "required": ["expected"] },
+          { "required": ["expectedDocuments"] },
+          { "required": ["expectedUris"] },
+          { "required": ["judgments"] }
+        ]
+      }
+    }
+  },
+  "definitions": {
+    "queryMode": {
+      "type": "object",
+      "required": ["mode", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "type": "string", "enum": ["term", "intent", "hyde"] },
+        "text": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}