@gmickel/gno 1.30.7 → 1.32.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.32.0** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 
@@ -694,7 +694,7 @@ Open `http://localhost:3000` to:
   configured MCP retrieval without changing client config. Skill installation
   is visible, but client runtime execution cannot be proven automatically
 - **Manage files safely**: Rename, reveal, or move editable files to Trash with explicit index-vs-disk semantics
-- **Refactor files safely**: Move, duplicate, and organize editable notes with reference warnings
+- **Refactor files safely**: Preview and atomically rename or move editable notes while GNO rewrites supported wiki and Markdown references; stale or unsafe plans fail closed
 - **Switch presets**: Change models live without restart
 - **Command palette**: Jump, create, refactor, and section-navigate from one keyboard-first surface
 
@@ -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
 
@@ -863,9 +863,10 @@ curl http://localhost:3000/api/health
 | `/api/docs`                   | GET    | List documents               |
 | `/api/docs`                   | POST   | Create document              |
 | `/api/docs/:id`               | PUT    | Update document content      |
-| `/api/docs/:id/move`          | POST   | Move editable document       |
+| `/api/docs/:id/rename`        | POST   | Apply confirmed safe rename  |
+| `/api/docs/:id/move`          | POST   | Apply confirmed safe move    |
 | `/api/docs/:id/duplicate`     | POST   | Duplicate editable document  |
-| `/api/docs/:id/refactor-plan` | POST   | Preview file-op warnings     |
+| `/api/docs/:id/refactor-plan` | POST   | Preview reference-safe plan  |
 | `/api/docs/:id/deactivate`    | POST   | Remove from index            |
 | `/api/doc`                    | GET    | Get document content         |
 | `/api/doc/:id/sections`       | GET    | Get document sections        |

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.
 
@@ -497,6 +499,29 @@ search must include the new note. Browser provenance fields are
 `extractionHash`, `finalBodyHash`, `clipIdentity`, and `previewDigest`—do not
 invent `sourceHash`.
 
+## Reference-Safe Rename and Move
+
+When MCP writes are enabled and the user asks to rename or move an editable
+note, always use the operation-specific two-step tool. Never invent a digest or
+collapse preview and apply into one call.
+
+1. Call `gno_rename_note` or `gno_move_note` with `action: "preview"` and the
+   exact source/destination.
+2. Inspect `canApply`, `safety.blockingReasons`, and `examinedReferences`.
+   Stop and report ambiguous, malformed, unsupported, read-only, occupied,
+   cross-collection, or truncated plans.
+3. Only after explicit user approval, call the same tool with `action: "apply"`,
+   the preview's exact `schemaVersion` and `planDigest`, `confirmation: "apply"`,
+   and `confirm: true`.
+4. Treat `applied_with_sync_pending` as a committed filesystem refactor whose
+   index still needs `gno_sync` or `gno_index`; do not retry the file mutation.
+   For `stale_plan`, preview again instead of reusing the old digest.
+
+Supported wiki and Markdown destinations are rewritten in the same
+all-or-rollback filesystem transaction as the source move. Duplicate and
+create-folder do not retarget inbound references. Authentication alone never
+enables these MCP writes.
+
 ## Collection-specific embedding models
 
 Collections can override the global embedding model with `models.embed`.

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.32.0.zip.sha256

@@ -0,0 +1 @@
+cb5c4bba8cf1252da4e4fc89f1dc01a8df306851cccb50f636d89a6ef3133cff  gno-browser-clipper-v1.32.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.32.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.30.7",
+  "version": "1.32.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

@@ -3448,6 +3448,25 @@ Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RU
 
 ---
 
+## Workspace file refactors (non-CLI)
+
+Reference-safe note rename and same-collection move use a transport-neutral
+preview/apply contract defined in `src/core/file-refactors.ts` and frozen as:
+
+- `gno://schemas/file-refactor-preview@1.0`
+- `gno://schemas/file-refactor-apply-result@1.0`
+
+Surfaces that adapt the contract are REST/Web UI, SDK, and write-gated MCP
+(`gno_rename_note`, `gno_move_note`). This specification intentionally does
+**not** add a CLI command family or generic action bus for refactors.
+Duplicate-note and create-folder keep their existing shipped semantics and do
+not retarget inbound references.
+
+The contract separates durable filesystem commit/rollback from post-commit
+index convergence. A successful filesystem refactor is never rolled back solely
+because reindexing is temporarily unavailable
+(`applied_with_sync_pending`).
+
 ## See Also
 
 - [MCP Specification](./mcp.md)

package/spec/db/schema.sql

@@ -21,6 +21,7 @@
 --   retrieval_trace_exports/export_traces - Export manifests and trace joins
 --   document_changes - Bounded metadata-only document lifecycle journal
 --   document_change_journal_state - Monotonic cursor/retention boundary
+--   file_refactor_recovery_journal - Content-free rename/move recovery receipts
 
 -- ─────────────────────────────────────────────────────────────────────────────
 -- Schema Metadata
@@ -742,3 +743,57 @@ CREATE TABLE IF NOT EXISTS clipper_capture_idempotency (
 
 CREATE INDEX IF NOT EXISTS idx_clipper_idempotency_created
   ON clipper_capture_idempotency(created_at_ms, grant_id, key_hash);
+
+-- ─────────────────────────────────────────────────────────────────────────────
+-- File refactor recovery journal (content-free)
+-- ─────────────────────────────────────────────────────────────────────────────
+
+-- Durable receipts for multi-file rename/move apply. Stores IDs, digests,
+-- collection/relpaths, phase/state, timestamps, and fingerprints/status only.
+-- Never stores note bodies or replacement content.
+-- Bounded: create prunes oldest terminal receipts (converged/rolled_back/aborted)
+-- under FILE_REFACTOR_JOURNAL_MAX_RECEIPTS; never prunes recovery_required.
+
+CREATE TABLE IF NOT EXISTS file_refactor_recovery_journal (
+  journal_id TEXT PRIMARY KEY,
+  plan_digest TEXT NOT NULL,
+  collection TEXT NOT NULL,
+  operation TEXT NOT NULL
+    CHECK (operation IN ('rename', 'move')),
+  source_rel_path TEXT NOT NULL,
+  target_rel_path TEXT NOT NULL,
+  phase TEXT NOT NULL
+    CHECK (phase IN (
+      'prepared', 'staging', 'committing', 'committed', 'sync_pending',
+      'converged', 'rolling_back', 'rolled_back', 'recovery_required',
+      'aborted'
+    )),
+  phase_ordinal INTEGER NOT NULL CHECK (phase_ordinal >= 0),
+  filesystem_state TEXT NOT NULL
+    CHECK (filesystem_state IN (
+      'unchanged', 'committed', 'rolled_back', 'recovery_required'
+    )),
+  index_state TEXT NOT NULL
+    CHECK (index_state IN (
+      'not_attempted', 'pending', 'converged', 'skipped'
+    )),
+  file_entries_json TEXT NOT NULL
+    CHECK (length(CAST(file_entries_json AS BLOB)) <= 65536),
+  created_at_ms INTEGER NOT NULL CHECK (created_at_ms >= 0),
+  updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= 0),
+  CHECK (length(CAST(journal_id AS BLOB)) BETWEEN 1 AND 128),
+  CHECK (
+    length(plan_digest) = 64
+    AND plan_digest NOT GLOB '*[^0-9a-f]*'
+  ),
+  CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+  CHECK (length(CAST(source_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+  CHECK (length(CAST(target_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+  CHECK (updated_at_ms >= created_at_ms)
+);
+
+CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_plan_digest
+  ON file_refactor_recovery_journal(plan_digest, updated_at_ms DESC, journal_id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_file_refactor_journal_collection
+  ON file_refactor_recovery_journal(collection, updated_at_ms DESC);

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.
@@ -1736,39 +1798,140 @@ Create a folder inside an existing collection (write-enabled).
 
 Rename an editable note in place (write-enabled).
 
+Same-collection rename is covered by the transport-neutral reference-safe
+refactor contract (`src/core/file-refactors.ts`). Preview and apply share one
+versioned schema pair across MCP, REST/SDK, and UI adapters:
+
+- Preview plan: `gno://schemas/file-refactor-preview@1.0`
+- Apply result: `gno://schemas/file-refactor-apply-result@1.0`
+
+The preview enumerates examined wiki/Markdown references with classifications
+and stable reason codes, destination-only edit spans, precondition fingerprints,
+a deterministic `planDigest`, safety summary, and `canApply`. Apply requires the
+exact `planDigest`, confirmation token `apply`, `confirm: true`, and
+`schemaVersion: "1.0"`. Apply never silently preview-and-confirms. Terminal
+statuses are `applied`, `applied_with_sync_pending`, `conflict`, `stale_plan`,
+`unsupported`, and `failed_rolled_back`.
+
+Filesystem commit (moved note + accepted reference rewrites) is an atomic
+all-or-rollback boundary. Index/link convergence runs only after a durable
+filesystem commit and is **not** the same transaction; reindex failure returns
+`applied_with_sync_pending` without rolling back committed files.
+
+MCP annotations remain hints, not authorization. Write gating (`--enable-write`)
+and destructive confirmation (`confirm: true` + `confirmation: "apply"`) still
+apply. No generic action-bus tool is introduced.
+
 **Input Schema:**
 
 ```json
 {
   "type": "object",
-  "properties": {
-    "ref": { "type": "string" },
-    "name": { "type": "string" }
-  },
-  "required": ["ref", "name"]
+  "oneOf": [
+    {
+      "properties": {
+        "action": { "const": "preview" },
+        "ref": { "type": "string" },
+        "name": { "type": "string" }
+      },
+      "required": ["action", "ref", "name"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "action": { "const": "apply" },
+        "ref": { "type": "string" },
+        "name": { "type": "string" },
+        "schemaVersion": { "const": "1.0" },
+        "planDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "confirmation": { "const": "apply" },
+        "confirm": { "const": true }
+      },
+      "required": [
+        "action",
+        "ref",
+        "name",
+        "schemaVersion",
+        "planDigest",
+        "confirmation",
+        "confirm"
+      ],
+      "additionalProperties": false
+    }
+  ]
 }
 ```
 
+**Output Schema:**
+
+- `action=preview` → `gno://schemas/file-refactor-preview@1.0` (content-free plan)
+- `action=apply` → `gno://schemas/file-refactor-apply-result@1.0` (content-free receipt)
+
+Missing or incorrect apply confirmation fails before mutation.
+
 ---
 
 ### gno_move_note
 
 Move an editable note to another folder in the same collection (write-enabled).
 
+Cross-collection moves are out of scope and fail closed with
+`cross_collection_unsupported`. Preview/apply semantics, destination-only edit
+spans, stale-plan protection, and the filesystem-vs-index mutation boundary match
+`gno_rename_note` and use the same schemas:
+
+- Preview plan: `gno://schemas/file-refactor-preview@1.0`
+- Apply result: `gno://schemas/file-refactor-apply-result@1.0`
+
 **Input Schema:**
 
 ```json
 {
   "type": "object",
-  "properties": {
-    "ref": { "type": "string" },
-    "folderPath": { "type": "string" },
-    "name": { "type": "string" }
-  },
-  "required": ["ref", "folderPath"]
+  "oneOf": [
+    {
+      "properties": {
+        "action": { "const": "preview" },
+        "ref": { "type": "string" },
+        "folderPath": { "type": "string" },
+        "name": { "type": "string" }
+      },
+      "required": ["action", "ref", "folderPath"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "action": { "const": "apply" },
+        "ref": { "type": "string" },
+        "folderPath": { "type": "string" },
+        "name": { "type": "string" },
+        "schemaVersion": { "const": "1.0" },
+        "planDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "confirmation": { "const": "apply" },
+        "confirm": { "const": true }
+      },
+      "required": [
+        "action",
+        "ref",
+        "folderPath",
+        "schemaVersion",
+        "planDigest",
+        "confirmation",
+        "confirm"
+      ],
+      "additionalProperties": false
+    }
+  ]
 }
 ```
 
+**Output Schema:**
+
+- `action=preview` → `gno://schemas/file-refactor-preview@1.0` (content-free plan)
+- `action=apply` → `gno://schemas/file-refactor-apply-result@1.0` (content-free receipt)
+
+Missing or incorrect apply confirmation fails before mutation.
+
 ---
 
 ### gno_duplicate_note
@@ -2181,6 +2344,8 @@ Output schemas include version in `$id`:
 
 - `gno://schemas/search-result@1.0`
 - `gno://schemas/capture-receipt@1.0`
+- `gno://schemas/file-refactor-preview@1.0`
+- `gno://schemas/file-refactor-apply-result@1.0`
 
 Clients should check schema version for compatibility.