feat: emit stable json errors

docs/compatibility.md

@@ -36,6 +36,12 @@ explicit migration expectation before scripts depend on them.
 top-level response variant name and existing field names keep their meaning
 within a major release.
 
+Execution failures in `--json` or `--jsonl` mode return a stable JSON error
+object on stdout with `type: "error"`, a machine-readable `code`, a human
+`message`, full `detail`, and an optional `hint` derived from operator
+recovery output. Common codes include `daemon_unavailable`, `unauthorized`,
+`peer_not_found`, `resource_not_found`, `invalid_input`, and `command_failed`.
+
 Backward-compatible JSON changes include:
 
 - Adding nullable or optional fields.

docs/production-readiness-roadmap.md

@@ -236,11 +236,11 @@ Goal: make convergence and failure behavior predictable enough for automation.
 
 Goal: make `geth` ergonomic and stable as a base layer for custom automation.
 
-- `[ ]` Stabilize JSON errors.
+- `[x]` Stabilize JSON errors.
   Acceptance criteria:
-  - `[ ]` Common failures include stable machine-readable error codes.
-  - `[ ]` Human errors still include next-step recovery hints.
-  - `[ ]` Tests assert both code and operator-facing hint for representative
+  - `[x]` Common failures include stable machine-readable error codes.
+  - `[x]` Human errors still include next-step recovery hints.
+  - `[x]` Tests assert both code and operator-facing hint for representative
     failures.
 
 - `[ ]` Add wait commands for automation.