From 6d750fab1feb4395cd3831d260084b2b7d7dcbc5 Mon Sep 17 00:00:00 2001
From: Michael Darmousseh <michael@extend.com>
Date: Fri, 20 Feb 2026 18:05:44 -0600
Subject: [PATCH] Remove --agent references, LLM-friendly output is the default

--agent flag was removed in an earlier release. Compact JSON/NDJSON
output is now the default behavior; -v enables pretty-printing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md          |  7 ++---
 docs/agent-mode.md | 67 +++++++++++++++++++++++++++-------------------
 2 files changed, 43 insertions(+), 31 deletions(-)

diff --git a/README.md b/README.md
index 697e02b..882fecc 100644
--- a/README.md
+++ b/README.md
@@ -98,8 +98,9 @@ murl http://localhost:3000/tools | jq '.[0].name'
 |---|---|
 | `-d, --data` | Add key=value or JSON data (repeatable) |
 | `-H, --header` | Add HTTP header (repeatable) |
-| `-v, --verbose` | Print request/response details to stderr |
-| `--agent` | Agent mode — compact JSON, NDJSON lists, structured errors |
+| `-v, --verbose` | Pretty-print output, show request debug info |
+| `--login` | Force OAuth re-authentication |
+| `--no-auth` | Skip all authentication |
 | `--version` | Show version info |
 | `--upgrade` | Upgrade to latest version |
 
@@ -120,7 +121,7 @@ murl https://example.com/mcp/tools --login
 
 ## Documentation
 
-- [Agent Mode](docs/agent-mode.md) — NDJSON output, structured errors, exit codes
+- [Output & Exit Codes](docs/agent-mode.md) — NDJSON format, structured errors, exit codes
 - [MCP Server Setup](docs/mcp-servers.md) — mcp-proxy, Streamable HTTP, local servers
 - [Contributing](docs/contributing.md) — development setup, testing, releasing
 
diff --git a/docs/agent-mode.md b/docs/agent-mode.md
index 4cb826b..30f99c0 100644
--- a/docs/agent-mode.md
+++ b/docs/agent-mode.md
@@ -1,13 +1,30 @@
-# Agent Mode
+# Output Format
 
-murl implements [POSIX Agent Standard (Level 2)](https://github.com/turlockmike/posix-agent-standard) for AI agent compatibility. Use `--agent` to enable.
+murl is LLM-friendly by default — compact JSON to stdout, structured errors to stderr. Use `-v` for human-readable pretty-printing.
 
-## Behavior
+## stdout
 
-- **Pure JSON output:** Compact JSON to stdout (no pretty-printing)
-- **JSON Lines (NDJSON):** List operations output one JSON object per line
-- **Structured errors:** JSON error objects to stderr with error codes
-- **Non-interactive:** No prompts or progress indicators
+- **Single results:** compact JSON (one line, no extra whitespace)
+- **Lists:** NDJSON (one JSON object per line)
+
+```bash
+# Single tool call — compact JSON
+murl http://localhost:3000/tools/echo -d message=hello
+{"content":[{"type":"text","text":"hello"}]}
+
+# List tools — one JSON object per line
+murl http://localhost:3000/tools
+{"name":"echo","description":"Echo a message",...}
+{"name":"fetch","description":"Fetch a URL",...}
+```
+
+## stderr
+
+Errors are structured JSON:
+
+```json
+{"error": "HTTPSTATUSERROR", "message": "401 Unauthorized", "code": 1}
+```
 
 ## Exit Codes
 
@@ -16,34 +33,28 @@ murl implements [POSIX Agent Standard (Level 2)](https://github.com/turlockmike/
 | `0` | Success |
 | `1` | General error (connection, timeout, server error) |
 | `2` | Invalid arguments (malformed URL, invalid data format) |
-| `100` | MCP server error (reported via JSON `code` field, not exit code) |
 
-## Examples
+## Verbose Mode
+
+`-v` switches to human-friendly output: pretty-printed JSON and request/response debug info on stderr.
 
 ```bash
-# Agent-optimized help
-murl --agent --help
+murl http://localhost:3000/tools -v
+```
+
+## Piping
 
-# List tools (NDJSON — one JSON object per line)
-murl --agent http://localhost:3000/tools
+Output is designed for standard Unix pipelines:
 
-# Call a tool (compact JSON)
-murl --agent http://localhost:3000/tools/echo -d message=hello
+```bash
+# Format with jq
+murl http://localhost:3000/tools | jq .
 
-# Process with jq
-murl --agent http://localhost:3000/tools | jq -c '.'
+# Extract fields
+murl http://localhost:3000/tools | jq -r '.name'
 
 # Handle errors programmatically
-if ! result=$(murl --agent http://localhost:3000/tools/invalid 2>&1); then
-  echo "Error: $result" | jq -r '.message'
+if ! result=$(murl http://localhost:3000/tools/invalid 2>/dev/null); then
+  echo "failed"
 fi
 ```
-
-## Human Mode vs Agent Mode
-
-| Feature | Human Mode | Agent Mode (`--agent`) |
-|---------|-----------|------------------------|
-| JSON Output | Pretty-printed (indented) | Compact (no spaces) |
-| List Output | JSON array | JSON Lines (NDJSON) |
-| Error Output | Friendly message to stderr | Structured JSON to stderr |
-| Exit Codes | 0, 1, or 2 | Semantic (0, 1, 2) |