@gmickel/gno 2.6.0 → 2.7.0

package/README.md

@@ -139,7 +139,7 @@ See the [guide](docs/COMPILED-CONTEXT.md).
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.6.0**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.7.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 

package/assets/skill/SKILL.md

@@ -130,8 +130,9 @@ Open without fetching content via `gno get`:
   `#anchor`). Take `serveUrl` from peek `serve.url` when `serve.running` is
   true.
 - **Source file**: peek `recent[].absPath`, or search `--json`
-  `results[].source.absPath`. If `absPath` is absent, show the URI tail and
-  do not offer file-open for that row.
+  `results[].source.absPath`. If `absPath` is absent (always for remote REST
+  and HTTP MCP callers), show the URI tail and do not offer file-open for
+  that row.
 
 ## Search Modes
 
@@ -557,7 +558,8 @@ Programmatic capture uses the same receipt contract:
 
 MCP capture writes structured `source:` frontmatter, runs under the MCP write
 lock, syncs the file for FTS, and preserves legacy MCP fields (`docid`,
-`absPath`, `overwritten`, `serverInstanceId`) alongside the shared receipt. It
+`absPath` over stdio only, `overwritten`, `serverInstanceId`) alongside the
+shared receipt. It
 does not auto-embed.
 
 For an explicit browser capture, use the local unpacked Chromium clipper with

package/assets/skill/cli-reference.md

@@ -117,9 +117,15 @@ gno collection clear-embeddings <name> [--all] [--json]
 ### gno embed
 
 ```bash
-gno embed [collection] [--collection <name>] [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
+gno embed [collection] [--collection <name>] [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--new-partition]
 ```
 
+Switching `GNO_LLAMA_GPU`, Bun version or thread count resumes the existing
+vector partition when a measured sample of stored chunks matches. If it does
+not, embed refuses to build a separate partition without `--new-partition`
+(`--yes` alone never confirms); queries from that runtime fall back to lexical
+retrieval with a `vector_runtime_incompatible` warning.
+
 ## Indexing
 
 ### gno update
@@ -150,7 +156,7 @@ gno index [options]
 Generate embeddings only.
 
 ```bash
-gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--new-partition]
 ```
 
 ## Project Profiles
@@ -857,6 +863,7 @@ Vector index maintenance. Use when `gno similar` returns empty despite embedding
 ```bash
 gno vec sync      # Fast incremental sync
 gno vec rebuild   # Full rebuild
+gno vec drop <partition>   # Drop an abandoned shadow partition (id prefix from gno status)
 ```
 
 | Option   | Description |

package/assets/skill/mcp-reference.md

@@ -156,7 +156,8 @@ CLI-only.
 `GNO_MCP_ENABLE_WRITE=1`. It writes quick notes with structured `source:`
 frontmatter and returns the same provenance receipt shape as CLI, REST, and SDK
 capture, plus legacy MCP fields (`docid`, `absPath`, `overwritten`,
-`serverInstanceId`).
+`serverInstanceId`). `absPath` is stdio-only: HTTP MCP callers never receive
+host paths and address the note by `uri` + `relPath`.
 
 `presetId` accepts `blank`, `project-note`, `research-note`, `decision-note`,
 `prompt-pattern`, `source-summary`, `idea-original`, `person`,

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

@@ -0,0 +1 @@
+2116eeada49b4479ac5967ec1bb79d1288b70529aba691b2b4ddaf33d131bc2e  gno-browser-clipper-v2.7.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.6.0"
+  "version": "2.7.0"
 }

package/package.json

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

@@ -9,13 +9,14 @@ This document specifies the command-line interface for GNO, a local knowledge in
 
 ### Exit Codes
 
-| Code | Name        | Description                                                                                                                                                                    |
-| ---- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0    | SUCCESS     | Command completed successfully                                                                                                                                                 |
-| 1    | VALIDATION  | Validation or usage error (bad args, missing required params)                                                                                                                  |
-| 2    | RUNTIME     | Runtime failure (IO, DB, conversion, model, network)                                                                                                                           |
-| 3    | NOT_RUNNING | `--status`/`--stop` found no live matching process                                                                                                                             |
-| 4    | BUSY        | Write-lease contention on `index` / `update` / `embed`; a lost `remember --supersede` race; a concurrent `sessions import`; a request ID still in progress (`REQUEST_PENDING`) |
+| Code | Name          | Description                                                                                                                                                                                                                                                                         |
+| ---- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | SUCCESS       | Command completed successfully                                                                                                                                                                                                                                                      |
+| 1    | VALIDATION    | Validation or usage error (bad args, missing required params)                                                                                                                                                                                                                       |
+| 2    | RUNTIME       | Runtime failure (IO, DB, conversion, model, network)                                                                                                                                                                                                                                |
+| 3    | NOT_RUNNING   | `--status`/`--stop` found no live matching process; `CONTEXT_STALE`: a saved Context Capsule is stale                                                                                                                                                                               |
+| 4    | BUSY          | Write-lease contention on `index` / `update` / `embed`; a lost `remember --supersede` race; a concurrent `sessions import`; a request ID still in progress (`REQUEST_PENDING`); `AUDIT_FINDINGS`: `gno audit` found findings; `CONTEXT_CONFLICT`: a saved Context Capsule conflicts |
+| 5    | AUDIT_PARTIAL | `gno audit` evidence is partial                                                                                                                                                                                                                                                     |
 
 ### Global Flags
 
@@ -226,9 +227,20 @@ setup and emits `setup-profile-result@1.0`.
 
 Display index status and health information.
 
-Embedding backlog follows the last verified partition for the selected model
-when exact-input storage is authoritative, counting pending document/chunk
-owners. Per-collection chunk totals remain deduplicated by canonical chunk;
+Embedding backlog follows the partition this runtime's retrieval reads (the
+caller's recorded identity under the shared selection rule; before any query or
+embed has resolved it, the activated runtime-independent partition) when
+exact-input storage is authoritative, counting pending document/chunk owners.
+`vectorRuntime` reports `{label, state: vectors|unavailable|unresolved,
+partition, reason?}` for the calling process.
+`vectorPartitions` (omitted when no partition exists) lists every partition of
+the model with `id`, `model`, `dimensions`, `state` (`active`|`shadow`),
+`legacy` (pre-runtime-independent key), `retrieval` (this runtime reads it),
+`droppable` (`gno vec drop` accepts it), `owners` (current chunks),
+`provenance` (building runtime, e.g. `CUDA, Bun 1.4.2`),
+`compatibleRuntimes` (runtimes that read it) and `incompatibleRuntimes`.
+Terminal output prints a `Vector partitions:` block
+unless there is exactly one healthy partition. Per-collection chunk totals remain deduplicated by canonical chunk;
 embedded counts require matching current inputs for every active owner within
 that collection. Status reads persisted identity and coverage without loading
 models. Legacy storage remains the fallback before variant authority; ambiguous
@@ -259,6 +271,21 @@ gno status [--json|--md]
   "totalDocuments": 100,
   "totalChunks": 500,
   "embeddingBacklog": 0,
+  "vectorPartitions": [
+    {
+      "id": "3f2a9c1b2d4e...",
+      "model": "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf",
+      "dimensions": 1024,
+      "state": "active",
+      "legacy": false,
+      "retrieval": true,
+      "droppable": false,
+      "owners": 500,
+      "provenance": "CUDA, Bun 1.4.2",
+      "compatibleRuntimes": ["CUDA, Bun 1.4.2", "CPU, Bun 1.3.14"],
+      "incompatibleRuntimes": []
+    }
+  ],
   "lastUpdated": "2025-12-23T10:00:00Z",
   "healthy": true,
   "activation": {
@@ -328,6 +355,32 @@ truthful about its lifecycle: `mode:"direct-cli"`, `resident:false`, no
 listener, and zero resident counters. It does not imply attachment to a live
 `serve` or `daemon`.
 
+When a detached `serve` or `daemon` (found through its pid-file) has a
+background job in trouble, JSON output adds `backgroundIssues`; the key is
+absent otherwise. Each item is a resident-status `backgroundIssue` plus the
+process that reported it:
+
+```json
+"backgroundIssues": [
+  {
+    "process": "serve",
+    "pid": 41234,
+    "job": "embed",
+    "state": "parked",
+    "consecutiveFailures": 5,
+    "runningSeconds": null
+  }
+]
+```
+
+`state` is `failing` (background embed passes failing and retrying with
+backoff), `parked` (retries stopped after 5 failed passes; pending chunks wait
+for new changes or `gno embed`), `overrunning` (one pass running longer than 15
+minutes, `runningSeconds` set), or `unresponsive` (`job:"resident"`: the process
+is alive but did not answer its status request within 500ms). Each resident is
+asked once with that 500ms budget, so `gno status` never waits on a hung
+resident. Terminal output lists the same issues under `Background issues:`.
+
 Local activation fingerprints use active-document identifiers and source/mirror
 hashes plus schema, tokenizer, and owned FTS synchronization metadata. Passive
 status never selects or compares stored markdown or FTS bodies. On a receipt
@@ -1006,7 +1059,7 @@ gno update [--git-pull] [--json] [--lock-wait <duration>] [--no-wait]
 | `--lock-wait <duration>` | duration | How long to wait for the index write lease (default: `120s`). Accepts `120`, `120s`, or `2m`. |
 | `--no-wait` | boolean | Do not wait; fail immediately if another writer holds the lease |
 
-**Concurrency:** One writer at a time on the shared index database. `update` waits up to `--lock-wait` for the lease (the same `.mcp-write.lock` MCP write tools use); `index`, `embed`, `cleanup`, `vec sync`, `vec rebuild`, `collection clear-embeddings`, `tags add`, and `tags rm` follow the same contract; `capture` takes the same lock internally, and single-row writes such as `collection policy set` are absorbed by `busy_timeout`. `--no-wait` opts out. Reads (`search`, `query`, `get`) never take the lease. External serialising wrappers are no longer required for CLI-vs-CLI and CLI-vs-MCP overlap. Residual window: a resident (`gno serve`/`gno daemon`) watch or embed flush writes without the lease; those short transactions are absorbed by the raised `busy_timeout` and the SQLITE_BUSY retry, and a deferred chunk is reported as contention, never as an embedding failure.
+**Concurrency:** One writer at a time on the shared index database. `update` waits up to `--lock-wait` for the lease (the same `.mcp-write.lock` MCP write tools use); `index`, `embed`, `cleanup`, `vec sync`, `vec rebuild`, `vec drop`, `collection clear-embeddings`, `tags add`, and `tags rm` follow the same contract; `capture` takes the same lock internally, and single-row writes such as `collection policy set` are absorbed by `busy_timeout`. `--no-wait` opts out. Reads (`search`, `query`, `get`) never take the lease. External serialising wrappers are no longer required for CLI-vs-CLI and CLI-vs-MCP overlap. A resident (`gno serve`/`gno daemon`) takes the same lease without waiting around each watcher sync, embed preparation, background-embedding page write (never around inference), and the final vector activation; when the lease is held it defers that work (watcher retry after 5s, embed pass rescheduled) instead of writing, so resident background writes never hold a SQLite write lock outside the lease. The resident's own SQLite busy wait is capped at 500ms so a stop signal is always handled within the stop grace.
 
 **Behavior:**
 
@@ -1135,9 +1188,20 @@ memory pressure prevents creating the full pool.
 **Synopsis:**
 
 ```bash
-gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--json] [--lock-wait <duration>] [--no-wait]
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--new-partition] [--json] [--lock-wait <duration>] [--no-wait]
 ```
 
+Vector partitions are keyed on model weights, formatter, dimensions, context
+size and truncation policy. Runtime details (Bun, `node-llama-cpp`, GPU/CPU
+backend, threads) are provenance. A runtime meeting a partition for the first
+time re-embeds up to 8 stored chunks; every one must reach cosine 0.99 against
+its stored vector, and the verdict is cached per (partition, runtime). A
+compatible runtime resumes the backlog in that partition. An incompatible one
+(or an ambiguous one-time re-key of pre-existing partitions) would build a
+separate partition: embed then states the full chunk count and an estimate and
+requires confirmation, interactively or with `--new-partition`. `--yes` alone
+never confirms; without confirmation embed exits 2 and writes nothing.
+
 **Options:**
 
 | Option                   | Type     | Default | Description                                                                 |
@@ -1146,7 +1210,8 @@ gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--js
 | `--model`                | string   | config  | Override embedding model URI                                                |
 | `--batch-size`           | integer  | 32      | Chunks per batch                                                            |
 | `--dry-run`              | boolean  | false   | Show what would be embedded without doing it                                |
-| `--yes`, `-y`            | boolean  | false   | Skip confirmation prompts                                                   |
+| `--yes`, `-y`            | boolean  | false   | Skip confirmation prompts (never confirms a separate vector partition)      |
+| `--new-partition`        | boolean  | false   | Confirm building a separate vector partition for an incompatible runtime    |
 | `--json`                 | boolean  | false   | Output result as JSON                                                       |
 | `--lock-wait <duration>` | duration | `120s`  | How long to wait for the index write lease. Accepts `120`, `120s`, or `2m`. |
 | `--no-wait`              | boolean  | false   | Do not wait; fail immediately if another writer holds the lease             |
@@ -1316,7 +1381,9 @@ by default when the collection root and `source.relPath` can be joined; search
 has no `--source` flag. When `absPath` is absent (unresolvable collection path,
 missing relPath, or a hit without a filesystem file), consumers display the URI
 tail and must disable file-open for that row — do not call `gno get` just to
-recover a path.
+recover a path. The CLI always runs on the owner's machine; the same result shape over
+remote REST or HTTP MCP omits `absPath` (see
+[docs/API.md](../docs/API.md#host-paths-and-remote-callers)).
 
 Every structured search result may include `context`, the matching
 user-configured guidance joined in deterministic global, collection, then
@@ -2705,6 +2772,31 @@ content, asset descriptors, source references, nor raster bytes.
 
 ---
 
+### gno vec drop
+
+Drop an abandoned shadow vector partition (legacy shadows included) the calling runtime's
+retrieval does not read, with its vectors, owners and runtime verdicts.
+
+**Synopsis:**
+
+```bash
+gno vec drop <partition> [--json] [--lock-wait <duration>] [--no-wait]
+```
+
+`<partition>` is an id prefix of at least 8 characters from `gno status`
+(`vectorPartitions[].id`). Only partitions with `droppable: true` are accepted:
+shadow partitions this runtime does not read; every active partition, legacy
+included, is refused. JSON output is
+`{"dropped": <vectorPartitions item>}`.
+
+**Exit Codes:**
+
+- 0: Dropped
+- 1: Unknown, ambiguous or protected partition
+- 4: Write lease busy with `--no-wait`
+
+---
+
 ### gno cleanup
 
 Remove orphaned content, chunks, and vectors not referenced by active documents.
@@ -4436,15 +4528,14 @@ Errors are written to stderr. With `--json` flag, errors are also returned as:
 }
 ```
 
-Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RUNNING` (exit 3), `BUSY` (exit 4).
+Error codes and their exit codes: `VALIDATION` (1), `RUNTIME` (2), `NOT_RUNNING` (3), `CONTEXT_STALE` (3), `BUSY` (4), `AUDIT_FINDINGS` (4), `CONTEXT_CONFLICT` (4), `AUDIT_PARTIAL` (5). `error.schema.json` lists exactly this set.
+`AUDIT_FINDINGS`, `AUDIT_PARTIAL`, `CONTEXT_STALE`, and `CONTEXT_CONFLICT` signal through the exit code alone, after the command's own output; they write no envelope.
 Request ID errors keep their stable request code in `details.requestCode`
 (see [gno request-status](#gno-request-status)).
 
 Write-lease contention on `index` / `update` / `embed` does not use the generic envelope. Text mode writes the dedicated "index is busy" message to stderr; `--json` writes `{ success: false, error, contention }` to stdout. Both exit 4. `gno audit` also uses exit 4 for findings.
 
-**`NOT_RUNNING` is not an error envelope.**
-
-**`NOT_RUNNING` is not an error envelope.** `gno serve|daemon --status --json` returns a `process-status`-shaped payload on stdout with exit 3 when no live matching process is found (it reports observable state, not failure). `--stop` exits 3 silently when there is nothing to stop and does not accept `--json`. The error envelope above is reserved for `VALIDATION` and `RUNTIME` failures where the command could not produce its structured output at all.
+**`NOT_RUNNING` is not a failure payload.** `gno serve|daemon --status --json` returns a `process-status`-shaped payload on stdout with exit 3 when no live matching process is found (it reports observable state, not failure); the `NOT_RUNNING` envelope goes to stderr only. `--stop` exits 3 silently when there is nothing to stop and does not accept `--json`. The error envelope above is reserved for `VALIDATION`, `RUNTIME`, and `BUSY` failures where the command could not produce its structured output at all.
 
 ---
 

package/spec/mcp.md

@@ -267,6 +267,15 @@ Because `gno serve` shares this listener with its Web UI and REST API, it
 remains loopback-only. Use the headless `gno daemon` command for an explicitly
 authenticated non-loopback MCP listener.
 
+HTTP MCP results never carry a host absolute path, whatever the peer zone:
+every `absPath` field (`source.absPath` on search/query/ask/get/multi-get
+results, top-level `absPath` on `gno_capture` and `gno_remember` receipts,
+`similar[].absPath`, peek `recent[].absPath`) is removed from both
+`structuredContent` and the text content, and a resource header's `source:`
+line names the collection-relative path. Callers address documents by `uri`
+and `relPath`. Stdio callers keep host paths. The field inventory lives in
+[docs/API.md](../docs/API.md#host-paths-and-remote-callers).
+
 HTTP MCP remains read-only unless `gateway.enableWrite: true` or
 `--mcp-enable-write` is explicitly set. Bearer authentication alone does not
 authorize mutation. Unauthorized calls to write tools fail with HTTP 403 before
@@ -1343,6 +1352,21 @@ counters; it never claims attachment to another process.
     "totalDocuments": 150,
     "totalChunks": 800,
     "embeddingBacklog": 0,
+    "vectorPartitions": [
+      {
+        "id": "3f2a9c1b2d4e...",
+        "model": "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf",
+        "dimensions": 1024,
+        "state": "active",
+        "legacy": false,
+        "retrieval": true,
+        "droppable": false,
+        "owners": 500,
+        "provenance": "CUDA, Bun 1.4.2",
+        "compatibleRuntimes": ["CUDA, Bun 1.4.2", "CPU, Bun 1.3.14"],
+        "incompatibleRuntimes": []
+      }
+    ],
     "contentTypeBoost": {
       "rulesFingerprint": "<sha256>",
       "rules": [{ "id": "decision", "searchBoost": 2 }]
@@ -1352,6 +1376,16 @@ counters; it never claims attachment to another process.
 }
 ```
 
+`vectorPartitions` (omitted when none exist) lists the embedding model's
+vector partitions; `embeddingBacklog` and per-collection embedded counts use
+the one with `retrieval: true`, the partition this server process's queries
+read under the same selection rule as retrieval (`vectorRuntime` reports
+`vectors`, `unavailable` with a reason, or `unresolved` before its first query
+or embed). `droppable` marks what `gno vec drop` accepts. Other partitions carry `state`, `owners` and a
+readable `provenance`; `compatibleRuntimes` names the runtimes that read a
+partition and `incompatibleRuntimes` names runtimes measured unable to
+reproduce the stored vectors, whose queries use lexical retrieval only.
+
 `contentTypeBoost` is a redacted ranking-status projection. It exposes only
 normalized IDs/factors plus the rules fingerprint; path prefixes are never
 returned.
@@ -1682,7 +1716,7 @@ file edits update existing notes, `gno_remember` upserts a fact.
   fact, nothing written
 - `outcome: "candidates"` — likely matches and no `decision`; `candidates[]`
   carry `similarity` and `match` (`exact` | `likely` | `weak`), nothing written
-- `outcome: "added" | "superseded"` — `record`, `absPath`, and
+- `outcome: "added" | "superseded"` — `record`, `absPath` (stdio only), and
   `sync.status` (`completed` before the call returns; the fact is lexically
   searchable)
 - `matching` — `mode` (`semantic` | `lexical`), `threshold`, and
@@ -2915,7 +2949,7 @@ Content includes optional header comment:
 |-------|-------------|
 | URI | Full gno:// URI |
 | docid | Document ID |
-| source | Absolute path to source file |
+| source | Absolute path to source file (stdio); collection-relative path over HTTP |
 | mime | Source file MIME type |
 | language | Document language hint (if available) |
 

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

@@ -322,7 +322,7 @@
           "properties": {
             "absPath": {
               "type": "string",
-              "description": "Absolute path (included with --source or in MCP)"
+              "description": "Absolute source path. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
             },
             "relPath": {
               "type": "string",

package/spec/output-schemas/capture-receipt.schema.json

@@ -43,7 +43,7 @@
     },
     "absPath": {
       "type": "string",
-      "description": "Absolute path when the local surface exposes it."
+      "description": "Absolute path of the written file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
     },
     "serverInstanceId": {
       "type": "string"

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

@@ -243,6 +243,94 @@
               "type": "string"
             }
           },
+          "vectorPartitions": {
+            "type": "array",
+            "description": "Vector partitions (vector-partitions check); `retrieval` marks the one status and search use",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "id",
+                "model",
+                "dimensions",
+                "state",
+                "legacy",
+                "retrieval",
+                "droppable",
+                "owners",
+                "provenance",
+                "compatibleRuntimes",
+                "incompatibleRuntimes"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "model": {
+                  "type": "string"
+                },
+                "dimensions": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "state": {
+                  "type": "string",
+                  "enum": ["active", "shadow"]
+                },
+                "legacy": {
+                  "type": "boolean"
+                },
+                "retrieval": {
+                  "type": "boolean"
+                },
+                "droppable": {
+                  "type": "boolean"
+                },
+                "owners": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "provenance": {
+                  "type": "string"
+                },
+                "compatibleRuntimes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "incompatibleRuntimes": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+          "vectorRuntime": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["label", "state", "partition"],
+            "description": "This process's runtime, resolved by the same selection rule its queries use",
+            "properties": {
+              "label": {
+                "type": ["string", "null"],
+                "description": "Runtime recorded by this caller's last query or embed"
+              },
+              "state": {
+                "type": "string",
+                "enum": ["vectors", "unavailable", "unresolved"],
+                "description": "vectors: queries read `partition`; unavailable: lexical retrieval only; unresolved: no query or embed has resolved this caller yet"
+              },
+              "partition": {
+                "type": ["string", "null"]
+              },
+              "reason": {
+                "type": "string"
+              }
+            }
+          },
           "embeddingFingerprint": {
             "type": "object",
             "description": "Embedding freshness fingerprint diagnostics",

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

@@ -12,8 +12,17 @@
       "properties": {
         "code": {
           "type": "string",
-          "description": "Error code matching exit code",
-          "enum": ["VALIDATION", "RUNTIME"]
+          "description": "CLI error code; each maps to one exit code (see spec/cli.md Error Output)",
+          "enum": [
+            "VALIDATION",
+            "RUNTIME",
+            "NOT_RUNNING",
+            "BUSY",
+            "AUDIT_FINDINGS",
+            "AUDIT_PARTIAL",
+            "CONTEXT_STALE",
+            "CONTEXT_CONFLICT"
+          ]
         },
         "message": {
           "type": "string",

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

@@ -62,7 +62,7 @@
       "properties": {
         "absPath": {
           "type": "string",
-          "description": "Absolute path to source file"
+          "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "relPath": {
           "type": "string",

package/spec/output-schemas/mcp-capture-result.schema.json

@@ -7,7 +7,6 @@
   "required": [
     "docid",
     "uri",
-    "absPath",
     "collection",
     "relPath",
     "created",
@@ -34,7 +33,7 @@
     },
     "absPath": {
       "type": "string",
-      "description": "Absolute path to the created file"
+      "description": "Absolute path to the created file. Stdio callers only; omitted for HTTP MCP callers, which identify the file by uri + relPath."
     },
     "collection": {
       "type": "string",

package/spec/output-schemas/memory-remember.schema.json

@@ -34,13 +34,13 @@
     {
       "type": "object",
       "additionalProperties": false,
-      "required": ["outcome", "record", "absPath", "sync", "matching"],
+      "required": ["outcome", "record", "sync", "matching"],
       "properties": {
         "outcome": { "enum": ["added", "superseded"] },
         "record": { "$ref": "#/$defs/fact" },
         "absPath": {
           "type": "string",
-          "description": "Absolute path of the fact file that was written."
+          "description": "Absolute path of the fact file that was written. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
         },
         "sync": { "$ref": "#/$defs/sync" },
         "matching": { "$ref": "#/$defs/matching" },

package/spec/output-schemas/multi-get.schema.json

@@ -40,7 +40,10 @@
             "type": "object",
             "required": ["relPath", "mime", "ext"],
             "properties": {
-              "absPath": { "type": "string" },
+              "absPath": {
+                "type": "string",
+                "description": "Absolute path to source file. Host path: local callers only (CLI, stdio MCP, same-host Web UI/REST); omitted for remote REST and HTTP MCP callers, which identify the document by uri + relPath."
+              },
               "relPath": { "type": "string" },
               "mime": { "type": "string" },
               "ext": { "type": "string", "pattern": "^\\.[a-zA-Z0-9]+$" }

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

@@ -99,14 +99,7 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": [
-          "docid",
-          "uri",
-          "title",
-          "collection",
-          "absPath",
-          "modifiedAt"
-        ],
+        "required": ["docid", "uri", "title", "collection", "modifiedAt"],
         "properties": {
           "docid": {
             "type": "string",
@@ -129,7 +122,7 @@
           "absPath": {
             "type": "string",
             "minLength": 1,
-            "description": "Absolute source path (collection root + relative path)"
+            "description": "Absolute source path (collection root + relative path). CLI and stdio MCP only; omitted for HTTP MCP callers."
           },
           "modifiedAt": {
             "type": "string",

package/spec/output-schemas/resident-status.schema.json

@@ -128,6 +128,28 @@
         "content": { "type": "integer", "minimum": 0 },
         "index": { "type": "integer", "minimum": 0 }
       }
+    },
+    "backgroundIssues": {
+      "description": "Present only while a background job is in trouble: failing passes, retries parked, a pass overrunning, or (client-side) a resident that did not answer its status request",
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/backgroundIssue" }
+    }
+  },
+  "definitions": {
+    "backgroundIssue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["job", "state", "consecutiveFailures", "runningSeconds"],
+      "properties": {
+        "job": { "type": "string", "enum": ["embed", "resident"] },
+        "state": {
+          "type": "string",
+          "enum": ["failing", "parked", "overrunning", "unresponsive"]
+        },
+        "consecutiveFailures": { "type": "integer", "minimum": 0 },
+        "runningSeconds": { "type": ["integer", "null"], "minimum": 0 }
+      }
     }
   },
   "allOf": [