diff --git a/Agent-Workflow.-.md b/Agent-Workflow.-.md
index 7fee7a9..8bff1a9 100644
--- a/Agent-Workflow.-.md
+++ b/Agent-Workflow.-.md
@@ -26,6 +26,12 @@ hop land R_... -- go test ./...
 No second landing authorization is requested unless the user explicitly asks
 for review-first behavior.
 
+Desktop capture stores the agent's verbatim transcription of the visible
+message and its attachment references. Because the skill runs after Codex
+receives the message, it cannot prove byte-for-byte fidelity with the raw
+submission. A trusted prompt-submission hook or controller is the deterministic
+capture boundary.
+
 ## Follow-up messages
 
 A later `hop begin` with the same Codex task session checkpoints existing
diff --git a/CLI-Reference.-.md b/CLI-Reference.-.md
index bc803fa..962edd6 100644
--- a/CLI-Reference.-.md
+++ b/CLI-Reference.-.md
@@ -1,6 +1,17 @@
 # CLI reference
 
-Add `--json` anywhere in a command for machine-readable output.
+Add `--json` anywhere in a command for machine-readable output. Successful
+responses use this envelope:
+
+```json
+{
+  "ok": true,
+  "data": {}
+}
+```
+
+The JSON shape is an alpha contract and may evolve before the first tagged
+release.
 
 ## Project and prompt lifecycle