From 8a8bd93ef2579ae607bb55f9b0a895cd569afbc0 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 16 Sep 2026 12:28:57 -0700
Subject: [PATCH] docs: -z exit codes differ from chat -q/-Q on purpose; real
 turn_exit_reason example

The two one-shot entry points map the same outcome to different codes
(failed/partial/budget -> 2 on -z, 1 on -q/-Q; completed-with-no-text -> 1 vs 0)
and the reference documented both tables 60 lines apart without saying so.
Also `iteration_limit` is a metrics end_reason, not a turn_exit_reason; the
finalizer emits `max_iterations_reached(N/M)`.
---
 website/docs/reference/cli-commands.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 4c6917123f..acd67424de 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -240,8 +240,11 @@ Same agent, same tools, same skills — just strips every interactive / cosmetic
 Exit codes: `0` the turn completed; `2` it failed or stopped partway (`partial`,
 iteration budget, `completed: false`) — even when an explanation was printed;
 `130` it was interrupted; `1` a completed turn produced no text at all; `2` also
-for usage errors (bad flags) before the run starts. Judge the run by the exit
-code (or the `--usage-file` flags), not by whether stdout is non-empty.
+for usage errors (bad flags) before the run starts. These codes intentionally
+differ from `chat -q`/`-Q` above (which exit `1` for failed/partial/budget and
+`0` for a completed turn with no text): `-z` reserves `1` for "answered nothing".
+Judge the run by the exit code (or the `--usage-file` flags), not by whether
+stdout is non-empty.
 
 #### `--usage-file` — JSON usage report for pipelines