Document CLI output and exit conventions

README.md

@@ -58,6 +58,37 @@ internal/
 - **Padded-cell mode**: When `pass_mgr` is available, auth tokens are resolved automatically. Manual `--token` flags are rejected.
 - **Manual mode**: When `pass_mgr` is not available, `--token` must be provided explicitly to authenticated commands.
 
+## Output / Error Contract
+
+### Human-readable mode
+
+Default output is human-readable:
+- list commands render simple tables
+- get/detail commands render key-value output
+- empty lists render `(no results)`
+
+### JSON mode
+
+`--json` can be supplied globally and produces structured JSON on stdout.
+
+Current contract:
+- success payloads go to **stdout** as JSON
+- errors go to **stderr** as plain text
+- the CLI does **not** wrap successful payloads in a universal envelope yet
+- list/get payloads preserve canonical code-bearing fields whenever the backend already returns them
+
+This is intentionally simple so agents can pipe `hf ... --json` into other tooling without first stripping banners or mixed text.
+
+### Exit / stderr conventions
+
+Current CLI convention is:
+- exit `0` on success
+- exit `1` on command/validation/runtime errors
+- user-facing errors are written to **stderr**
+- success output is written to **stdout**
+
+There is not yet a finer-grained exit-code taxonomy; callers should currently treat any non-zero exit as failure.
+
 ## Current Status
 
 ### Implemented