@gmickel/gno 1.17.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.16.0** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.18.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -104,6 +104,11 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
   Web/Desktop dashboard now share a per-folder lexical retrieval proof. Local
   semantic readiness remains independent, and installed MCP targets can run an
   explicit read-only retrieval smoke from Connectors.
+- **One resident gateway**: `gno serve` and `gno daemon` now host stateful
+  Streamable HTTP MCP at `/mcp` from the same long-lived runtime as their
+  watcher, jobs, stores, and models. The packed npm smoke proves two-client
+  parity, warm reuse, redacted lifecycle status, fail-closed security, restart,
+  and shutdown.
 - **Second-brain capture**: `gno capture`, REST `/api/capture`, SDK
   `client.capture()`, MCP `gno_capture`, and Web UI Quick Capture write
   provenance-rich notes from text, stdin, or files, including typed presets for
@@ -308,7 +313,7 @@ Use `gno daemon` when you want continuous indexing without the browser or
 desktop shell open.
 
 ```bash
-gno daemon                  # foreground (Ctrl+C to stop)
+gno daemon                  # foreground + /mcp on 127.0.0.1:3000
 gno daemon --no-sync-on-start
 gno daemon --detach         # background (macOS/Linux); auto-writes pid + log files
 gno daemon --status         # check the detached process
@@ -548,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                           |
 | :------------------- | :------------------------------------ |
@@ -566,11 +571,20 @@ 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
 tools are available only through the explicit `--enable-write` opt-in.
 
+`gno serve` and `gno daemon` also expose this surface as stateful Streamable
+HTTP at `http://127.0.0.1:3000/mcp`. HTTP stays read-only by default.
+Authenticated non-loopback access is available through the headless daemon and
+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/)
 
 ---

package/assets/skill/SKILL.md

@@ -71,8 +71,9 @@ 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`                                                          | Web UI for browsing and searching                      |
+| **Serve**    | `serve`, `daemon`                                                | One resident Web/headless gateway and watcher          |
 | **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                        |
 | **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                               |
 | **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                            |
@@ -155,12 +156,54 @@ gno multi-get gno://work/doc1.md gno://work/doc2.md
 # Search, get full content of top result
 gno query "auth" --json | jq -r '.results[0].uri' | xargs gno get
 
+# Exclude documents containing a term
+gno search "deployment" --exclude staging
+
 # Get all results
 gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-get
 ```
 
+When the user wants a synthesized answer instead of ranked evidence:
+
+```bash
+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
+with `gno serve` or `gno daemon` and connect to
+`http://127.0.0.1:3000/mcp`. Existing installed stdio entries remain valid.
+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/assets/skill/mcp-reference.md

@@ -72,6 +72,27 @@ Do not shorten a generated entry to `gno mcp`.
 gno mcp status
 ```
 
+## Resident Streamable HTTP
+
+`gno serve` and `gno daemon` expose the same read-only-by-default MCP surface at
+`http://127.0.0.1:3000/mcp`. Use this URL for clients that support Streamable
+HTTP and benefit from shared warm stores, jobs, watchers, and model leases.
+Existing `gno mcp install` stdio entries remain valid.
+
+Only `gno daemon` supports an explicit non-loopback bind. It requires a
+restrictive bearer-token file plus exact Host and Origin allowlists.
+Authentication does not grant writes; `gateway.enableWrite` or
+`--mcp-enable-write` is a separate opt-in. `gno serve` always remains
+loopback-only.
+
+Inspect the safe lifecycle without exposing paths or secrets:
+
+```bash
+curl http://127.0.0.1:3000/api/resident/status
+gno serve --status --json
+gno daemon --status --json
+```
+
 ## Retrieval Order
 
 For normal questions, start with `gno_query`, then read targeted snippets with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.17.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"
@@ -143,7 +144,7 @@
   "dependencies": {
     "@codemirror/lang-markdown": "6.5.0",
     "@codemirror/theme-one-dark": "6.1.3",
-    "@modelcontextprotocol/sdk": "1.27.1",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@radix-ui/react-collapsible": "1.1.12",
     "@radix-ui/react-dialog": "1.1.15",
     "@radix-ui/react-dropdown-menu": "2.1.16",

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 }
+      }
+    }
+  }
+}