From 5245dcef1afcde2775735d85022f4eec5e40d986 Mon Sep 17 00:00:00 2001
From: Ismail Pelaseyed <homanp@gmail.com>
Date: Sun, 22 Mar 2026 20:18:29 +0100
Subject: [PATCH] docs: clarify headless json output format

Explain that `--format json` now emits semantic JSON events so the README matches the current headless behavior.
---
 README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2631741..656e9b4 100644
--- a/README.md
+++ b/README.md
@@ -64,8 +64,9 @@ Works in interactive mode too—same flag.
 grok --prompt "summarize the repo state" --format json
 ```
 
-`--format json` emits newline-delimited `StreamChunk` objects instead of the
-default human-readable text stream.
+`--format json` emits a newline-delimited JSON event stream instead of the
+default human-readable text output. Events are semantic, step-level records such
+as `step_start`, `text`, `tool_use`, `step_finish`, and `error`.
 
 **List Grok models and pricing hints:**