Output contracts

Response-producing CLI commands write exactly one JSON object to stdout by default. Pass --yaml for YAML. Diagnostic logs go to stderr and are controlled by RUST_LOG, -v, and -vv.

CLI and documented HTTP handler success and error responses use the same envelope: schema_version, ok, and type, plus command-specific fields. Router-level unmatched paths and methods are outside this response contract. Output excerpts include encoding, byte ranges, and total byte counts; log paths identify complete retained logs.

{"schema_version":"0.1","ok":true,"type":"wait","job_id":"<id>","state":"exited","exit_code":0,"stdout":"done\n","stderr":"","encoding":"utf-8-lossy","stdout_range":[0,5],"stderr_range":[0,0],"stdout_total_bytes":5,"stderr_total_bytes":0,"updated_at":"2026-07-20T00:00:00Z"}

Generated completions, MCP stdio protocol, and Clap help/version output are not response envelopes. The serve command emits a JSON error envelope for startup configuration failures such as an unsafe bind, a missing token for a non-loopback bind, or a wildcard CORS origin. MCP startup errors are outside the response-envelope contract.