@gmickel/gno 1.38.0 → 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.38.0"
+  "version": "1.39.0"
 }

package/package.json

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

@@ -113,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 |
@@ -2582,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
@@ -2623,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:**
 
@@ -2728,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.
@@ -3643,16 +3838,18 @@ Write-lease contention on `index` / `update` / `embed` does not use the generic
 
 ## 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)"
+          }
+        }
+      }
+    }
+  }
+}

package/src/cli/commands/agents/block.ts

@@ -0,0 +1,164 @@
+/**
+ * GNO agents protocol block: content, markers, hashing, extraction.
+ *
+ * One compact, versioned instruction block bounded by stable BEGIN/END
+ * markers. Install/update/uninstall 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 matches the installed release and its hash matches its body.
+ *
+ * @module src/cli/commands/agents/block
+ */
+
+import { CliError } from "../../errors.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Version of the protocol block content. Bump on any content change. */
+export const BLOCK_VERSION = 2;
+
+/** Stable across block versions — never change these once shipped. */
+export const BEGIN_MARKER = "<!-- gno:agents:begin -->";
+export const END_MARKER = "<!-- gno:agents:end -->";
+
+const STAMP_RE = /^<!-- gno-agents block v(\d+) sha256:([0-9a-f]{16}) /;
+const HASH_PREFIX_LENGTH = 16;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendering
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The protocol block body (between stamp line and end marker). Compact by
+ * design: the retrieval ladder + the writing contract. Detailed workflows live
+ * in the GNO skill; the block just points at it. No filesystem paths — the
+ * text is the same on every machine.
+ */
+export function renderBlockBody(): string {
+  return `## GNO knowledge retrieval
+
+Local knowledge search over indexed collections. Source files are the truth; the GNO index is disposable, machine-local.
+
+Ladder — scope to a collection first (\`--collection <name>\`):
+
+1. Exact term/identifier/quote/error: \`gno search "<text>"\`
+2. Entity or known document: \`gno query "<question>" --fast -n 10\`
+3. Multi-document evidence for a goal: \`gno context build "<goal>" --budget 12000\`
+4. Change/dependency questions: \`gno changes\` / \`gno diff <doc>\` / \`gno impact <doc>\`
+5. Generated factual answer: \`gno ask "<question>" --verify\` (abstention is valid)
+6. Expected document missing: reformulate + re-check collection scope (\`gno query diagnose "<query>" --target <doc>\`) before any grep fallback.
+
+Writing: retrieve first — a question alone is read-only. Edit an existing canonical note in its source file; \`gno capture\` creates genuinely new notes (collection, title/path, source kind, provenance) — never an update API. After writes: reindex the collection, verify retrieval.
+
+Cite with gno:// URIs. Advanced retrieval (structured queries, filters, backlinks, similar, capture recipes) lives in the \`gno\` skill: load it (\`/gno\`) when installed, otherwise run \`gno skill install --scope user\` first.`;
+}
+
+/** SHA-256 hex digest of the body, truncated for the stamp line. */
+export function hashBlockBody(body: string): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(body);
+  return hasher.digest("hex").slice(0, HASH_PREFIX_LENGTH);
+}
+
+/** Render the stamp line carrying version + body hash. */
+export function renderStampLine(body: string): string {
+  return `<!-- gno-agents block v${BLOCK_VERSION} sha256:${hashBlockBody(body)} — managed by \`gno agents\`; manual edits inside the markers are overwritten -->`;
+}
+
+/** Render the complete block: BEGIN marker, stamp, body, END marker. */
+export function renderBlock(): string {
+  const body = renderBlockBody();
+  return `${BEGIN_MARKER}\n${renderStampLine(body)}\n${body}\n${END_MARKER}`;
+}
+
+/** True when the extracted stamp's hash matches the extracted body. */
+export function stampAuthenticates(block: ExtractedBlock): boolean {
+  return block.stamp !== null && block.stamp.hash === hashBlockBody(block.body);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Extraction & Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ExtractedBlock {
+  /** Offset of the BEGIN marker in the file content. */
+  start: number;
+  /** Offset just past the END marker. */
+  end: number;
+  /** Everything between the markers (stamp line + body), without markers. */
+  inner: string;
+  /** Body without the stamp line (equal to inner when no stamp present). */
+  body: string;
+  /** Parsed stamp, when present and well-formed. */
+  stamp: { version: number; hash: string } | null;
+}
+
+export type BlockExtraction =
+  | { found: false }
+  | { found: true; block: ExtractedBlock };
+
+function countOccurrences(haystack: string, needle: string): number {
+  let count = 0;
+  let idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    count += 1;
+    idx = haystack.indexOf(needle, idx + needle.length);
+  }
+  return count;
+}
+
+const MARKER_GUIDANCE =
+  "Fix or remove the markers manually (or restore the file from its .gno-agents.bak backup), then re-run.";
+
+/**
+ * Extract the managed block from file content.
+ * Fail-closed: malformed or duplicate markers throw with guidance — the
+ * installer never guesses or "repairs".
+ */
+export function extractBlock(
+  content: string,
+  filePath: string
+): BlockExtraction {
+  const begins = countOccurrences(content, BEGIN_MARKER);
+  const ends = countOccurrences(content, END_MARKER);
+
+  if (begins === 0 && ends === 0) {
+    return { found: false };
+  }
+  if (begins !== 1 || ends !== 1) {
+    throw new CliError(
+      "VALIDATION",
+      `Malformed GNO agents markers in ${filePath}: found ${begins} BEGIN and ${ends} END marker(s), expected exactly one of each. ${MARKER_GUIDANCE}`
+    );
+  }
+
+  const start = content.indexOf(BEGIN_MARKER);
+  const endMarkerStart = content.indexOf(END_MARKER);
+  if (endMarkerStart < start) {
+    throw new CliError(
+      "VALIDATION",
+      `Malformed GNO agents markers in ${filePath}: END marker appears before BEGIN marker. ${MARKER_GUIDANCE}`
+    );
+  }
+
+  const end = endMarkerStart + END_MARKER.length;
+  const rawInner = content.slice(start + BEGIN_MARKER.length, endMarkerStart);
+  // Trim exactly the structural newlines install added around the inner text.
+  const inner = rawInner.replace(/^\n/, "").replace(/\n$/, "");
+
+  const newlineIdx = inner.indexOf("\n");
+  const firstLine = newlineIdx === -1 ? inner : inner.slice(0, newlineIdx);
+  const stampMatch = STAMP_RE.exec(firstLine);
+  const version = stampMatch ? Number(stampMatch[1]) : Number.NaN;
+  // An absurd version (not a safe integer) is an unparseable stamp, not a
+  // numeric verdict — it would otherwise serialize as null in JSON receipts.
+  const stamp =
+    stampMatch && Number.isSafeInteger(version)
+      ? { version, hash: stampMatch[2] ?? "" }
+      : null;
+  const body = stamp && newlineIdx !== -1 ? inner.slice(newlineIdx + 1) : inner;
+
+  return { found: true, block: { start, end, inner, body, stamp } };
+}