@gmickel/gno 1.30.7 → 1.31.0

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.30.7** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.31.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -723,7 +723,7 @@ Full-featured markdown editor with:
 
 ![GNO Document Viewer](./assets/screenshots/webui-doc-view.jpg)
 
-View documents with full context: outgoing links, backlinks, section outline, and AI-powered related notes sidebar.
+View documents with full context: outgoing links, backlinks, section outline, and AI-powered related notes sidebar. Outline copy-link stays human-readable (`#anchor`); an optional citation link adds a bounded durable selector for conservative recovery after edits.
 
 ### Browse Workspace
 

package/assets/skill/SKILL.md

@@ -329,6 +329,7 @@ When using GNO through MCP, prefer this retrieval order:
 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.
 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.
+8. Use `gno_section` only when you need a durable section locator or must re-resolve one after edits. Prefer search → `gno_get` for ordinary retrieval. `action=create` needs `ref` plus exactly one of `anchor`|`line`; `action=resolve` needs `ref` plus `target`. Cite or open content only for `exact`/`recovered` results, then follow the tool's ready-to-use `gno_get` guidance (`fromLine = lineStart`; `lineCount = lineEnd - lineStart + 1`). Never navigate or cite `ambiguous`/`stale`/`missing`.
 
 For a caller-owned canonical Capsule that should stay fresh locally:
 
@@ -370,6 +371,7 @@ Use narrower tools when the request tells you to:
 - `gno_graph_neighbors`: relationship/corpus-navigation questions around a known document
 - `gno_graph_path`: "how are X and Y connected?" questions
 - `gno_query_diagnose`: why a named target did or did not surface for a query
+- `gno_section`: create/resolve a durable section target when citation identity matters after edits; follow navigable citations with `gno_get`. Not the default retrieval path.
 
 For ambiguous terms, pass `intent` instead of bloating the query text. For typed retrieval, use `queryModes`: `term` for lexical anchors, `intent` for disambiguation, one `hyde` for a hypothetical answer/document.
 

package/assets/skill/mcp-reference.md

@@ -107,6 +107,12 @@ Check `gno_status` first when freshness or
 embeddings may be stale. Use `gno_query_diagnose` when a known target document
 should have appeared but did not.
 
+Use `gno_section` only when durable section identity matters (create/resolve a
+`SectionTargetV1`). Prefer ordinary `gno_query` → `gno_get` retrieval first.
+Exact/recovered results include citation lines and ready-to-use `gno_get`
+guidance (`fromLine = lineStart`; `lineCount = lineEnd - lineStart + 1`). Never
+cite or navigate ambiguous/stale/missing results.
+
 Use graph tools for relationship context: `gno_graph` for corpus report/stats,
 community summaries,
 `gno_graph_query` for bounded typed-edge traversal,

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

@@ -0,0 +1 @@
+01281ef03fe26195c824909c53eed8d04ede0f9a2da72f3c4c19d7e1564e0a0c  gno-browser-clipper-v1.31.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": "1.30.7"
+  "version": "1.31.0"
 }

package/package.json

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

package/spec/mcp.md

@@ -166,6 +166,7 @@ Collection names are case-insensitive on input and normalized to lowercase in re
 - Use `gno_query_diagnose` when a specific important document is missing from results or when you need per-stage retrieval evidence before changing query strategy.
 - Use `gno_graph_query` for bounded typed-edge traversal over `doc_edges`; keep `gno_graph_neighbors`/`gno_graph_path` for the legacy graph projection.
 - After search/query returns a `line`, call `gno_get` with `fromLine` and `lineCount` before fetching whole documents.
+- Use `gno_section` to create or resolve durable section targets; only cite/navigate on exact/recovered citations, then follow with `gno_get` line ranges.
 - Use `gno_multi_get` to batch the top result refs. Keep `maxBytes` bounded to avoid flooding client context.
 - Check `gno_status` when results look stale, vector search is unavailable, or embedding backlog may explain missing results.
 
@@ -900,6 +901,67 @@ limited to 242 UTF-8 bytes so `index-<identity>.sqlite` stays within the portabl
 
 ---
 
+### gno_section
+
+Read-only create/resolve for durable `SectionTargetV1` locators against one
+indexed document. Always registered (independent of `enableWrite`). Does not
+write documents, persist targets, or fork the shared parser/resolver.
+
+Uses the active indexed store content and the shared core
+create/resolve/transport projection (same bounds, closed validation, and
+fail-closed citation semantics as REST/SDK). Canonical document URI always
+comes from the stored document — never from the caller.
+
+**Annotations (descriptive only):**
+`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`,
+`openWorldHint: false`. Authorization remains server-side; annotations do not
+grant or deny writes. `gno_section` is not in `MCP_WRITE_TOOL_NAMES`.
+
+**Input Schema (closed, action-discriminated):**
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["action", "ref"],
+  "properties": {
+    "action": { "enum": ["create", "resolve"] },
+    "ref": { "type": "string", "minLength": 1, "maxLength": 2048 },
+    "anchor": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "line": { "type": "integer", "minimum": 1 },
+    "target": { "$ref": "gno://schemas/section-target@1.0" }
+  }
+}
+```
+
+The published MCP discovery schema is one closed object because the SDK cannot
+reliably publish/validate Zod unions for tool schemas. Server-side refinements
+enforce the action branches: create requires exactly one of `anchor` or `line`
+(1-based heading line) and forbids `target`; resolve requires a closed
+`SectionTargetV1` and forbids `anchor`/`line`. Unknown fields, unknown actions,
+inverted offsets, and oversized values fail closed before core resolution or
+document reads.
+
+**Output Schema:** `gno://schemas/section@1.0`
+
+Action-discriminated structured output wrapping the shared create/resolve
+result semantics:
+
+- `action: "create"` → `{ schemaVersion:"1.0", action, uri, target }`
+- `action: "resolve"` + `exact`/`recovered` → includes `citation` with
+  canonical `uri`, current `anchor`/`title`, inclusive `lineStart`/`lineEnd`,
+  and `sourceFingerprint`
+- `action: "resolve"` + `ambiguous`/`stale`/`missing` → omits `citation`;
+  model-visible text states the result is not safe to navigate or cite
+
+Model-visible `content[0].text` includes the serialized structured JSON for
+MCP 2025-11-25 hosts that ignore `structuredContent`, plus concise `gno_get`
+`fromLine`/`lineCount` follow-up guidance when a navigable citation is present.
+
+Existing `gno_get` input/output and line-range behavior are unchanged.
+
+---
+
 ### gno_multi_get
 
 Retrieve multiple documents by pattern or list.

package/spec/output-schemas/section-target-create-result.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target-create-result@1.0",
+  "title": "GNO Section Target Create Result",
+  "description": "Response from creating a durable SectionTargetV1 against a stored document. Canonical uri always comes from the resolved document.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["uri", "target"],
+  "properties": {
+    "uri": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Canonical stored document URI"
+    },
+    "target": {
+      "$ref": "gno://schemas/section-target@1.0"
+    }
+  }
+}

package/spec/output-schemas/section-target-resolve-result.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target-resolve-result@1.0",
+  "title": "GNO Section Target Resolve Result",
+  "description": "Conservative section-target resolution result shared by REST and SDK. Citation is present only for navigable exact/recovered statuses. Diagnostics candidates are filtered/capped without truncating identity strings.",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics",
+        "citation"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["exact", "recovered"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "#/definitions/diagnostics"
+        },
+        "citation": {
+          "$ref": "#/definitions/citation"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ambiguous", "stale", "missing"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "#/definitions/diagnostics"
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "safePositiveInteger": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "safeNonNegativeInteger": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "diagnostics": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "candidates": {
+          "type": "array",
+          "maxItems": 32,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "anchor",
+              "line",
+              "title",
+              "headingPath",
+              "occurrence"
+            ],
+            "properties": {
+              "anchor": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "line": {
+                "$ref": "#/definitions/safePositiveInteger"
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512
+              },
+              "headingPath": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 6,
+                "items": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                }
+              },
+              "occurrence": {
+                "$ref": "#/definitions/safePositiveInteger"
+              }
+            }
+          }
+        },
+        "candidateCount": {
+          "$ref": "#/definitions/safeNonNegativeInteger",
+          "description": "Total candidate count before transport filtering/capping"
+        },
+        "candidatesTruncated": {
+          "type": "boolean",
+          "description": "True when any candidate was omitted by bounds filtering or the 32-item cap"
+        }
+      },
+      "dependencies": {
+        "candidates": ["candidateCount", "candidatesTruncated"],
+        "candidateCount": ["candidatesTruncated", "candidates"],
+        "candidatesTruncated": ["candidateCount", "candidates"]
+      }
+    },
+    "citation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "uri",
+        "anchor",
+        "title",
+        "lineStart",
+        "lineEnd",
+        "sourceFingerprint"
+      ],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "anchor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "lineStart": {
+          "$ref": "#/definitions/safePositiveInteger"
+        },
+        "lineEnd": {
+          "$ref": "#/definitions/safePositiveInteger"
+        },
+        "sourceFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      }
+    }
+  }
+}

package/spec/output-schemas/section-target.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section-target@1.0",
+  "title": "GNO Section Target V1",
+  "description": "Bounded, versioned, content-derived section locator for conservative citation recovery. Does not embed full section bodies.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "document",
+    "anchor",
+    "headingPath",
+    "occurrence",
+    "quote",
+    "sourceFingerprint",
+    "hints"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1",
+      "description": "Section target schema version"
+    },
+    "document": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["uri"],
+      "properties": {
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "Canonical document URI"
+        }
+      }
+    },
+    "anchor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "description": "Human-readable heading anchor at capture time"
+    },
+    "headingPath": {
+      "type": "array",
+      "description": "NFC-normalized heading ancestry including the section title",
+      "minItems": 1,
+      "maxItems": 6,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 512
+      }
+    },
+    "occurrence": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "description": "1-based occurrence among sections with the same headingPath"
+    },
+    "quote": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["exact", "prefix", "suffix"],
+      "properties": {
+        "exact": {
+          "type": "string",
+          "maxLength": 96,
+          "description": "Bounded exact quote (section body preferred, else heading title)"
+        },
+        "prefix": {
+          "type": "string",
+          "maxLength": 32,
+          "description": "Bounded prefix context immediately before exact"
+        },
+        "suffix": {
+          "type": "string",
+          "maxLength": 32,
+          "description": "Bounded suffix context immediately after exact"
+        }
+      }
+    },
+    "sourceFingerprint": {
+      "$ref": "#/definitions/sha256",
+      "description": "SHA-256 hex fingerprint of the full source document content at capture"
+    },
+    "hints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["line", "startOffset", "endOffset"],
+      "description": "Line and code-unit offset hints only; never identity",
+      "properties": {
+        "line": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "description": "1-based heading line at capture"
+        },
+        "startOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "UTF-16 code-unit start offset of the exact quote at capture"
+        },
+        "endOffset": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "UTF-16 code-unit end offset of the exact quote at capture"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  }
+}

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

@@ -0,0 +1,113 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/section@1.0",
+  "title": "GNO MCP Section Tool Result",
+  "description": "Action-discriminated MCP gno_section structured output. Create returns the shared create-result semantics; resolve returns the shared resolve-result semantics (citation only for exact/recovered).",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "action", "uri", "target"],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "create"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "action",
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics",
+        "citation"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "resolve"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["exact", "recovered"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/diagnostics"
+        },
+        "citation": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/citation"
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "action",
+        "uri",
+        "status",
+        "currentFingerprint",
+        "target",
+        "diagnostics"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": "1.0"
+        },
+        "action": {
+          "const": "resolve"
+        },
+        "uri": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ambiguous", "stale", "missing"]
+        },
+        "currentFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "target": {
+          "$ref": "gno://schemas/section-target@1.0"
+        },
+        "diagnostics": {
+          "$ref": "gno://schemas/section-target-resolve-result@1.0#/definitions/diagnostics"
+        }
+      }
+    }
+  ]
+}