Normalize JSON and JSONL output

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: