[DX-793] Add JSON envelope documentation to README

Author: umair-ably

AGENTS.md

@@ -197,7 +197,8 @@ All output helpers use the `format` prefix and are exported from `src/utils/outp
 - **Count labels**: `formatCountLabel(n, "message")` — cyan count + pluralized label.
 - **Limit warnings**: `formatLimitWarning(count, limit, "items")` — yellow warning if results truncated.
 - **JSON guard**: All human-readable output (progress, success, listening messages) must be wrapped in `if (!this.shouldOutputJson(flags))` so it doesn't pollute `--json` output. Only JSON payloads should be emitted when `--json` is active.
-- **JSON errors**: In catch blocks, use `this.handleCommandError(error, flags, component, context?)` for consistent error handling. It logs the event, emits JSON error when `--json` is active, and calls `this.error()` for human-readable output. For non-standard error flows, use `this.jsonError()` directly.
+- **JSON envelope**: Use `this.formatJsonRecord(type, data, flags)` for all JSON output. It wraps data in `{type, command, success?, ...data}`. Types: `"result"` (one-shot), `"event"` (streaming), `"error"`, `"log"` (verbose). Do NOT add ad-hoc `success: true/false` — the envelope handles it. `--json` produces compact single-line output (NDJSON for streaming). `--pretty-json` is unchanged.
+- **JSON errors**: In catch blocks, use `this.handleCommandError(error, flags, component, context?)` for consistent error handling. It logs the event, emits JSON error when `--json` is active, and calls `this.error()` for human-readable output. For non-standard error flows, use `this.jsonError()` directly (it uses `formatJsonRecord("error", ...)` internally).
 - **History output**: Use `[index] timestamp` ordering: `` `${formatIndex(index + 1)} ${formatTimestamp(timestamp)}` ``. Consistent across all history commands (channels, logs, connection-lifecycle, push).
 
 ### Additional output patterns (direct chalk, not helpers)

README.md

@@ -4103,6 +4103,19 @@ EXAMPLES
 _See code: [src/commands/support/contact.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/support/contact.ts)_
 <!-- commandsstop -->
 
+## JSON Output
+
+All commands support `--json` for machine-readable output and `--pretty-json` for human-readable formatted JSON.
+
+When using `--json`, every record is wrapped in a standard envelope:
+
+- **`type`** — `"result"`, `"event"`, `"error"`, or `"log"`
+- **`command`** — the command that produced the record (e.g. `"channels:publish"`)
+- **`success`** — `true` or `false` (only on `"result"` and `"error"` types)
+- Additional fields are command-specific
+
+Streaming commands (subscribe, logs) emit one JSON object per line (NDJSON).
+
 ## Environment Variables
 
 The CLI supports the following environment variables for authentication and configuration:

docs/Project-Structure.md

@@ -105,7 +105,8 @@ This document outlines the directory structure of the Ably CLI project.
 │   │   ├── mock-ably-spaces.ts     # Mock Ably Spaces SDK
 │   │   ├── mock-config-manager.ts  # MockConfigManager (provides test auth)
 │   │   ├── mock-control-api-keys.ts # Mock Control API key responses
-│   │   └── ably-event-emitter.ts   # Event emitter helper for mock SDKs
+│   │   ├── ably-event-emitter.ts   # Event emitter helper for mock SDKs
+│   │   └── ndjson.ts                # NDJSON parsing helpers (parseNdjsonLines, filterByType)
 │   ├── unit/                   # Fast, mocked tests
 │   │   ├── setup.ts            # Unit test setup
 │   │   ├── base/               # Base command class tests