Normalize JSON and JSONL output

docs/automation-examples.md

@@ -4,6 +4,12 @@ These examples are intended as starting points for local scripts and
 infrastructure automation. They assume the single `geth` executable is on
 `PATH`.
 
+Use `--json` when one process invocation produces one result that will be
+parsed as a complete document. Use `--jsonl` for line-oriented shell pipelines:
+each current command writes one compact object on one physical line. The flags
+are mutually exclusive, and failures use the same `type: "error"` envelope and
+return a nonzero exit status in either mode.
+
 ## Shell
 
 Initialize a home, start the daemon in a user-owned process, wait for control,
@@ -25,6 +31,13 @@ geth doctor --json
 geth status --json
 ```
 
+For a compact line suitable for an append-only log or `jq -c` pipeline:
+
+```sh
+geth status --jsonl >>geth-status.jsonl
+tail -n 1 geth-status.jsonl | jq -r '.type'
+```
+
 Create a backup into a separate directory and validate that it can restore to a
 new home:
 

docs/compatibility.md

@@ -32,15 +32,28 @@ explicit migration expectation before scripts depend on them.
 
 ## JSON Output
 
-`--json` output is the preferred script contract. For stable commands, the
+`--json` and `--jsonl` are mutually exclusive machine-output modes:
+
+- `--json` writes exactly one pretty-printed JSON document for the command
+  result. Embedded newlines are formatting whitespace, so consumers should
+  parse the complete stdout stream as one document.
+- `--jsonl` writes each result as one compact JSON object followed by a
+  newline. Current non-streaming commands emit one physical line; a future
+  streaming command may emit multiple records, one complete object per line.
+
+Machine output does not mix operator prose into stdout. Successful direct CLI
+workflows and local-control responses include a stable top-level `type` field;
+type and action names use lowercase kebab-case. For stable commands, the
 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`.
+recovery output, and exit nonzero. The envelope is pretty-printed in `--json`
+mode and occupies exactly one physical line in `--jsonl` mode. Common codes
+include `daemon_unavailable`, `unauthorized`, `peer_not_found`,
+`resource_not_found`, `invalid_input`, and `command_failed`.
 
 Backward-compatible JSON changes include:
 

docs/roadmap.md

@@ -121,6 +121,17 @@ For deployment-readiness work that cuts across feature areas, see
   - `[x]` Tests cover transient path detection/copying, file-log states, and
     user-scoped generated definitions.
 
+- `[x]` Normalize machine-readable CLI output.
+  Acceptance criteria:
+  - `[x]` `--json` emits one pretty JSON document and `--jsonl` emits each
+    result as one compact physical line; the flags are mutually exclusive.
+  - `[x]` Direct CLI results, local-control responses, and service reports use
+    stable top-level `type` fields without mixing operator prose into stdout.
+  - `[x]` Machine-mode failures use the stable error envelope, include a
+    focused recovery hint when available, and exit nonzero.
+  - `[x]` Tests and automation documentation define the single-document and
+    line-oriented contracts.
+
 - `[ ]` Publish copy-paste installation entrypoints for release artifacts.
   Acceptance criteria:
   - `[ ]` Linux, macOS, and Windows installation instructions verify artifact