@gmickel/gno 1.37.1 → 1.39.0

package/assets/skill/README.md

@@ -42,6 +42,8 @@ gno skill install --target hermes       # Hermes
 gno skill install --target all          # All supported agents
 ```
 
+As of their current releases, `--target claude` also serves Grok Build and Cursor via automatic `.claude/skills` discovery, `--target codex` is also read by Cursor, and other skill-capable clients can copy the files listed by `gno skill paths`.
+
 Scope is configurable:
 
 ```bash

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

@@ -0,0 +1 @@
+b3b2f2609cfe5c821eb9d22d76832b6ad329afa7496c0792e0dd4f5bd0f74fbc  gno-browser-clipper-v1.39.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.37.1"
+  "version": "1.39.0"
 }

package/package.json

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

@@ -15,6 +15,7 @@ This document specifies the command-line interface for GNO, a local knowledge in
 | 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`        |
 
 ### Global Flags
 
@@ -112,6 +113,10 @@ equivalent files fail closed as ambiguous.
 | skill uninstall    | yes    | no      | no    | no   | no    | terminal |
 | skill show         | no     | no      | no    | no   | no    | terminal |
 | skill paths        | yes    | no      | no    | no   | no    | terminal |
+| agents install     | yes    | no      | no    | no   | no    | terminal |
+| agents update      | yes    | no      | no    | no   | no    | terminal |
+| agents verify      | yes    | no      | no    | no   | no    | terminal |
+| agents uninstall   | yes    | no      | no    | no   | no    | terminal |
 | tags list          | yes    | no      | no    | yes  | no    | terminal |
 | tags add           | yes    | no      | no    | no   | no    | terminal |
 | tags rm            | yes    | no      | no    | no   | no    | terminal |
@@ -957,7 +962,7 @@ Sync files from disk into the index (ingestion without embedding).
 **Synopsis:**
 
 ```bash
-gno update [--git-pull] [--json]
+gno update [--git-pull] [--json] [--lock-wait <duration>] [--no-wait]
 ```
 
 **Options:**
@@ -965,6 +970,10 @@ gno update [--git-pull] [--json]
 |--------|------|-------------|
 | `--git-pull` | boolean | Run `git pull` in git repositories before scanning |
 | `--json` | boolean | Emit the complete deterministic sync result on stdout |
+| `--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.
 
 **Behavior:**
 
@@ -986,6 +995,7 @@ record failure was reported. Human progress and diagnostics remain on stderr.
 
 - 0: Success (conversion warnings do not affect exit code)
 - 2: DB failure or critical IO error
+- 4: Write lease busy (contention after `--lock-wait`, or immediately with `--no-wait`)
 
 ---
 
@@ -996,7 +1006,7 @@ Build or update the index end-to-end (update + embed).
 **Synopsis:**
 
 ```bash
-gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes]
+gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes] [--lock-wait <duration>] [--no-wait]
 ```
 
 **Options:**
@@ -1008,24 +1018,29 @@ gno index [collection] [--no-embed] [--models-pull] [--git-pull] [--json] [--yes
 | `--git-pull` | boolean | Run `git pull` in git repositories |
 | `--json` | boolean | Emit the complete deterministic sync and embedding result on stdout |
 | `--yes` | boolean | Accept defaults, no prompts |
+| `--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 |
 
 **Behavior:**
 
 - Runs `update` then `embed` by default
 - With `--no-embed`, runs `update` only
+- Waits by default for the shared write lease; `--no-wait` fails immediately with exit 4
 
 **JSON output:** Emits `{ syncResult, embedSkipped, embedResult? }`.
 `syncResult.collections[].files[].recordImport`, when present, conforms to
 [`record-import@1.0`](./output-schemas/record-import.schema.json) with the same
 deterministic ordering, bounds, truncation disclosure, and partial-snapshot
 warnings as `gno update --json`. Human progress and diagnostics remain on
-stderr.
+stderr. On lease timeout, stdout is one object `{ success: false, error, contention }`
+and the process exits 4.
 
 **Exit Codes:**
 
 - 0: Success
-- 1: Invalid collection name
+- 1: Invalid collection name or invalid `--lock-wait`
 - 2: DB or model failure
+- 4: Write lease busy (contention, not corruption)
 
 **Examples:**
 
@@ -1060,25 +1075,30 @@ memory pressure prevents creating the full pool.
 **Synopsis:**
 
 ```bash
-gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--json]
+gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run] [--yes] [--json] [--lock-wait <duration>] [--no-wait]
 ```
 
 **Options:**
 
-| Option         | Type    | Default | Description                                   |
-| -------------- | ------- | ------- | --------------------------------------------- |
-| `--force`      | boolean | false   | Re-embed all chunks (ignore existing vectors) |
-| `--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                     |
-| `--json`       | boolean | false   | Output result as JSON                         |
+| Option                   | Type     | Default | Description                                                                 |
+| ------------------------ | -------- | ------- | --------------------------------------------------------------------------- |
+| `--force`                | boolean  | false   | Re-embed all chunks (ignore existing vectors)                               |
+| `--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                                                   |
+| `--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             |
+
+Waits by default for the same write lease as `index` / `update` / MCP writers. `--no-wait` opts out.
 
 **Exit Codes:**
 
 - 0: Success
-- 1: User cancelled
+- 1: User cancelled or invalid `--lock-wait`
 - 2: Model not available or embedding failure
+- 4: Write lease busy (contention, not corruption)
 
 **JSON Output:**
 
@@ -2566,6 +2586,8 @@ gno skill install [--scope <project|user>] [--target <claude|codex|opencode|open
 3. Atomically installs skill directory (temp + rename)
 4. Copies SKILL.md, reference files, and nested recipe files
 
+**Compatibility:** As of their current releases, Grok Build (the xAI grok CLI) automatically reads Claude skill directories (`.claude/skills/` and `~/.claude/skills/`) with no extra configuration, and Cursor loads agent skills from `.claude/skills/` and `.codex/skills/` (project and user scope) in addition to its own `.cursor/skills/`. `--target claude` therefore covers Grok Build and Cursor; `--target codex` is also read by Cursor. Other skill-capable clients can copy the installed files; `gno skill paths` prints their locations. Dedicated `grok` and `cursor` installer targets are not shipped: they would duplicate the claude/codex paths those tools already read. Revisit only if users keep `~/.grok/skills` or `~/.cursor/skills` separate and ask for first-class targets.
+
 **Output (JSON):**
 
 ```json
@@ -2607,7 +2629,7 @@ Remove GNO agent skill.
 gno skill uninstall [--scope <project|user>] [--target <claude|codex|opencode|openclaw|hermes|all>] [--json]
 ```
 
-**Options:** Same as `skill install` (except `--force`)
+**Options:** Same as `skill install` (except `--force`).
 
 **Safety Checks:**
 
@@ -2712,6 +2734,195 @@ gno skill paths [--scope <project|user>] [--target <claude|codex|opencode|opencl
 
 ---
 
+### gno agents install
+
+Install the compact, versioned GNO protocol block into the global (user-scope)
+instruction files of every detected harness. The block is bounded by stable
+markers (`<!-- gno:agents:begin -->` / `<!-- gno:agents:end -->`); install and
+update touch ONLY the owned block — content outside the markers stays
+byte-identical. The block content is static (identical on every machine), so
+a block is current exactly when its stamp version and hash match the installed
+release.
+
+**Synopsis:**
+
+```bash
+gno agents install [--target <claude|codex|cursor|opencode|grok|hermes|openclaw|all>] [--extra-dir <path>]... [--dry-run] [--json]
+```
+
+**Options:**
+
+| Option        | Type    | Default | Description                                                                                     |
+| ------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- |
+| `--target`    | string  | all     | Harness to install for; `all` = every harness detected on this machine                          |
+| `--extra-dir` | string  | —       | Additional instruction dir (repeatable, for nonstandard/multi-instance layouts). Never guessed. |
+| `--dry-run`   | boolean | false   | Print per-target unified diffs; write nothing                                                   |
+
+**Harness matrix (standard documented locations):**
+
+| Target     | Instruction file                                        | Detection root          | Notes                                                                               |
+| ---------- | ------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- |
+| `claude`   | `$CLAUDE_CONFIG_DIR/CLAUDE.md` or `~/.claude/CLAUDE.md` | `~/.claude`             | Honors `CLAUDE_CONFIG_DIR`                                                          |
+| `codex`    | `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md`         | `~/.codex`              | Honors `CODEX_HOME`                                                                 |
+| `cursor`   | `~/AGENTS.md`                                           | `~/.cursor`             | Cursor Agent walks cwd → home for AGENTS.md                                         |
+| `opencode` | `~/.config/opencode/AGENTS.md`                          | `~/.config/opencode`    |                                                                                     |
+| `grok`     | — (import chain)                                        | `~/.grok`               | Reads the Claude global file; reported `covered via claude`, never double-installed |
+| `hermes`   | `~/.hermes/SOUL.md`                                     | `~/.hermes`             |                                                                                     |
+| `openclaw` | `~/.openclaw/workspace/AGENTS.md`                       | `~/.openclaw/workspace` |                                                                                     |
+
+**Behavior:**
+
+1. Detects harnesses (config dir exists); undetected targets are reported
+   `not-detected` and skipped — the installer never fabricates harness dirs
+   (creating the instruction FILE inside a detected dir is fine). An explicit
+   detected covered target (e.g. `--target grok`) also resolves its covering
+   target so the file it actually reads converges; when the explicit target is
+   absent, the covering chain never activates.
+2. Backup-first, atomic: an existing file is copied to
+   `<file>.gno-agents.bak.<timestamp>` (same permission mode as the source),
+   then the new content is written to a sibling temp file and renamed over the
+   destination, so a failed write leaves the live file unchanged. A fresh
+   install appends the block after one blank line (a file without a final
+   newline gets that newline first).
+3. Idempotent: a current block is a `current` no-op (no write, no backup).
+4. Fail-closed: malformed or duplicate markers, a file that is not valid
+   UTF-8, or any read/write failure produce a per-target `error` row, nothing
+   is written to that file, and — for install/update — the command prints the
+   complete block (`manualBlock` in JSON) so the operator can apply it by
+   hand. Other targets in the same run still proceed. A leading UTF-8 BOM is
+   preserved across every operation.
+5. Symlink-aware: writes go through the resolved real file (an operator's
+   canonical-file-linked-everywhere scheme survives); targets resolving to the
+   same real file are written once (`covered via <target> (same file)`).
+6. `GNO_AGENTS_HOME_OVERRIDE` overrides the home directory (testing/sandboxed
+   verification); any home override suppresses harness config-dir env vars.
+
+**Output (JSON):**
+
+```json
+{
+  "command": "install",
+  "blockVersion": 2,
+  "dryRun": false,
+  "results": [
+    {
+      "target": "claude",
+      "label": "Claude Code",
+      "path": "/home/user/.claude/CLAUDE.md",
+      "action": "install",
+      "detected": true,
+      "backup": null
+    },
+    {
+      "target": "grok",
+      "label": "Grok Build",
+      "path": "/home/user/.claude/CLAUDE.md",
+      "action": "covered",
+      "detected": true,
+      "via": "claude",
+      "detail": "covered via claude"
+    }
+  ]
+}
+```
+
+`action` is one of `install`, `update`, `current`, `covered`, `not-detected`,
+`error` (and `remove`, `absent` for uninstall). A covered row's `path` is the
+file the harness actually reads (its covering target's file). With
+`--dry-run`, a `diffs` array of unified diffs is included. When
+any target failed on install/update, `manualBlock` carries the complete block
+text to paste. Schema: `spec/output-schemas/agents-mutation.schema.json`
+(shared by install, update, and uninstall).
+
+**Exit Codes:**
+
+- 0: Success (including no-op)
+- 1: Validation failure (unknown target, missing `--extra-dir`, malformed
+  markers, non-UTF-8 file)
+- 2: Runtime failure — every failing target hit an I/O error (unreadable file,
+  backup or write failed); the receipt still lists every target's outcome
+
+---
+
+### gno agents update
+
+Refresh an installed block in place (block-version migration). Same options,
+output, and exit codes as `agents install`; both verbs converge the block to
+the current release — `update` exists for operator intent clarity.
+
+```bash
+gno agents update [--target <...>] [--extra-dir <path>]... [--dry-run] [--json]
+```
+
+---
+
+### gno agents verify
+
+Deterministic per-target verification of installed blocks. Fresh-session
+behavioral canaries are an operator practice, not automated here.
+
+**Synopsis:**
+
+```bash
+gno agents verify [--target <...>] [--extra-dir <path>]... [--json]
+```
+
+**Checks per target:**
+
+- Exactly one marker block (`malformed` otherwise)
+- Block stamp hash matches the block body (tamper detection)
+- Block version and content match the installed release (`outdated` otherwise)
+- The block carries no filesystem references by construction, so the spec's
+  link-resolution check is vacuously satisfied
+- Targets resolving to the same real file are verified once, using install's
+  ownership order; the rest report `covered via <target> (same file)`
+
+**Output (JSON):**
+
+```json
+{
+  "command": "verify",
+  "blockVersion": 2,
+  "ok": true,
+  "results": [
+    {
+      "target": "claude",
+      "label": "Claude Code",
+      "path": "/home/user/.claude/CLAUDE.md",
+      "status": "ok",
+      "detected": true,
+      "blockVersion": 2,
+      "hashOk": true
+    }
+  ]
+}
+```
+
+`status` is one of `ok`, `outdated`, `missing`, `malformed`, `error`,
+`covered`, `not-detected`. `error` means the file exists but could not be read
+— a "could not check", never a content verdict. Schema:
+`spec/output-schemas/agents-verify.schema.json`.
+
+**Exit Codes:**
+
+- 0: All verified targets ok (covered / not-detected do not fail)
+- 1: One or more targets `outdated`, `missing`, or `malformed`
+- 2: Every failing target is an `error` (I/O) row
+
+---
+
+### gno agents uninstall
+
+Remove the block, its markers, and the blank line install added above it;
+everything else stays byte-identical. Same options, output shape
+(`action: remove|absent|...`), and exit codes as `agents install`.
+
+```bash
+gno agents uninstall [--target <...>] [--extra-dir <path>]... [--dry-run] [--json]
+```
+
+---
+
 ### gno tags list
 
 List all tags with document counts.
@@ -3615,7 +3826,11 @@ 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).
+Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RUNNING` (exit 3), `BUSY` (exit 4).
+
+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.
 
@@ -3623,16 +3838,18 @@ Error codes match exit codes: `VALIDATION` (exit 1), `RUNTIME` (exit 2), `NOT_RU
 
 ## Environment Variables
 
-| Variable                   | Description                                                           |
-| -------------------------- | --------------------------------------------------------------------- |
-| `GNO_CONFIG_DIR`           | Override config directory                                             |
-| `GNO_DATA_DIR`             | Override data directory (DB location)                                 |
-| `GNO_CACHE_DIR`            | Override cache directory (models)                                     |
-| `NO_COLOR`                 | Disable colored output (standard)                                     |
-| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows) |
-| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                      |
-| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                      |
-| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                       |
+| Variable                   | Description                                                                                                                |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `GNO_CONFIG_DIR`           | Override config directory                                                                                                  |
+| `GNO_DATA_DIR`             | Override data directory (DB location)                                                                                      |
+| `GNO_CACHE_DIR`            | Override cache directory (models)                                                                                          |
+| `NO_COLOR`                 | Disable colored output (standard)                                                                                          |
+| `PAGER`                    | Pager for long output (default: less -R on Unix, built-in on Windows)                                                      |
+| `GNO_SKILLS_HOME_OVERRIDE` | Override home dir for skill user scope (testing)                                                                           |
+| `CLAUDE_SKILLS_DIR`        | Override Claude skills directory                                                                                           |
+| `CODEX_SKILLS_DIR`         | Override Codex skills directory                                                                                            |
+| `CLAUDE_CONFIG_DIR`        | Claude Code config dir; `gno agents` resolves Claude's instruction file under it (suppressed by an explicit home override) |
+| `CODEX_HOME`               | Codex config dir; same rule as `CLAUDE_CONFIG_DIR`                                                                         |
 
 ---
 

package/spec/output-schemas/agents-mutation.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/agents-mutation@1.0",
+  "title": "GNO Agents Mutation Receipt",
+  "description": "JSON receipt for `gno agents install|update|uninstall --json`",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["command", "blockVersion", "dryRun", "results"],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "dryRun": { "const": false } },
+        "required": ["dryRun"]
+      },
+      "then": {
+        "not": { "properties": { "diffs": true }, "required": ["diffs"] }
+      }
+    }
+  ],
+  "properties": {
+    "command": {
+      "enum": ["install", "update", "uninstall"],
+      "description": "The mutation verb that produced this receipt"
+    },
+    "blockVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Protocol block version of the installed release"
+    },
+    "dryRun": {
+      "type": "boolean",
+      "description": "True when nothing was written; diffs carries the planned changes"
+    },
+    "results": {
+      "type": "array",
+      "description": "One row per resolved target",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "label", "path", "action", "detected"],
+        "allOf": [
+          {
+            "if": {
+              "properties": { "action": { "const": "covered" } },
+              "required": ["action"]
+            },
+            "then": {
+              "properties": { "via": true, "detail": true },
+              "required": ["via", "detail"]
+            }
+          }
+        ],
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Harness id (claude, codex, cursor, ...) or extra-dir id"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable harness label"
+          },
+          "path": {
+            "type": "string",
+            "description": "Instruction file path for this target"
+          },
+          "action": {
+            "enum": [
+              "install",
+              "update",
+              "current",
+              "remove",
+              "absent",
+              "covered",
+              "not-detected",
+              "error"
+            ],
+            "description": "What the run did (or would do) for this target"
+          },
+          "detected": {
+            "type": "boolean",
+            "description": "Whether the harness config dir exists on this machine"
+          },
+          "via": {
+            "type": "string",
+            "description": "Target id that covers this one (import chain or shared real file)"
+          },
+          "detail": {
+            "type": "string",
+            "description": "Human-readable detail (coverage reason, error guidance)"
+          },
+          "backup": {
+            "type": ["string", "null"],
+            "description": "Backup file path for a written target; null when no backup was made (new file or dry run). Omitted for no-op rows."
+          }
+        }
+      }
+    },
+    "diffs": {
+      "type": "array",
+      "description": "Unified diffs of planned writes; present only with dryRun",
+      "items": { "type": "string" }
+    },
+    "manualBlock": {
+      "type": "string",
+      "description": "The complete block to paste by hand; present on install/update when at least one target reported an error"
+    }
+  }
+}

package/spec/output-schemas/agents-verify.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/agents-verify@1.0",
+  "title": "GNO Agents Verify Receipt",
+  "description": "JSON receipt for `gno agents verify --json`",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["command", "blockVersion", "ok", "results"],
+  "properties": {
+    "command": { "const": "verify" },
+    "blockVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Protocol block version of the installed release"
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "True when no target is outdated, missing, or malformed (covered / not-detected do not fail)"
+    },
+    "results": {
+      "type": "array",
+      "description": "One row per resolved target",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "label", "path", "status", "detected"],
+        "allOf": [
+          {
+            "if": {
+              "properties": { "status": { "const": "covered" } },
+              "required": ["status"]
+            },
+            "then": {
+              "properties": { "via": true, "detail": true },
+              "required": ["via", "detail"]
+            }
+          }
+        ],
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Harness id (claude, codex, cursor, ...) or extra-dir id"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable harness label"
+          },
+          "path": {
+            "type": "string",
+            "description": "Instruction file path for this target"
+          },
+          "status": {
+            "enum": [
+              "ok",
+              "outdated",
+              "missing",
+              "malformed",
+              "error",
+              "covered",
+              "not-detected"
+            ],
+            "description": "Verification outcome for this target (`error` = the file exists but could not be read)"
+          },
+          "detected": {
+            "type": "boolean",
+            "description": "Whether the harness config dir exists on this machine"
+          },
+          "via": {
+            "type": "string",
+            "description": "Target id whose row carries the actual block status (import chain or shared real file)"
+          },
+          "detail": {
+            "type": "string",
+            "description": "Human-readable detail (coverage reason, failure guidance)"
+          },
+          "blockVersion": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Version stamped on the found block (a legacy/pre-release stamp may read 0 — the `outdated` migration case); omitted when the stamp is unparseable"
+          },
+          "hashOk": {
+            "type": "boolean",
+            "description": "Block body matches its stamp hash (tamper detection)"
+          }
+        }
+      }
+    }
+  }
+}