docs: correct output format showcase examples

docs/showcase/cli-tools/output-format-flags.md

@@ -4,8 +4,9 @@
 
 CleverAgents CLI supports six distinct output formats selectable via the global
 `--format` (or `-f`) flag. This lets you switch between human-friendly rich
-panels, machine-readable JSON/YAML, plain key-value text, ASCII tables, and
-ANSI-coloured output — all from the same commands. This example walks through
+panels, machine-readable JSON/YAML, plain key-value text, ASCII tables, and the
+legacy `color` flag (currently identical to `plain`) — all from the same
+commands. This example walks through
 every format using the `version`, `info`, `diagnostics`, and `actor list`
 commands.
 
@@ -16,8 +17,8 @@ commands.
 
 ## What You'll Learn
 
-- How to use the **global** `--format` / `-f` flag (set once, applies to any
-  subcommand)
+- How to use the **global** `--format` / `-f` flag (set once for top-level
+  commands) and when to fall back to a **per-command** flag (e.g., `actor list`)
 - The six supported formats: `rich`, `json`, `yaml`, `plain`, `table`, `color`
 - The **JSON/YAML envelope** structure (`command`, `status`, `exit_code`,
   `data`, `timing`, `messages`)
@@ -38,7 +39,7 @@ $ agents --format json version
 **Expected Output:**
 ```json
 {
-  "command": "version",
+  "command": "",
   "status": "ok",
   "exit_code": 0,
   "data": {
@@ -62,7 +63,7 @@ $ agents --format json version
   "messages": [
     {
       "level": "ok",
-      "text": "version completed"
+      "text": "ok"
     }
   ]
 }
@@ -79,7 +80,7 @@ The output is wrapped in the **spec-required envelope**:
 
 | Field | Description |
 |---|---|
-| `command` | The CLI command that was run |
+| `command` | The CLI command that was run (empty for commands that don't set it explicitly) |
 | `status` | `"ok"`, `"warn"`, or `"error"` |
 | `exit_code` | `0` for success |
 | `data` | The command-specific payload |
@@ -96,7 +97,7 @@ $ agents --format yaml version
 
 **Expected Output:**
 ```yaml
-command: version
+command: ''
 status: ok
 exit_code: 0
 data:
@@ -116,7 +117,7 @@ timing:
   duration_ms: 2
 messages:
 - level: ok
-  text: version completed
+  text: ok
 ```
 
 **What's Happening:**
@@ -208,7 +209,7 @@ $ agents --format json info
   "messages": [
     {
       "level": "ok",
-      "text": "completed"
+      "text": "ok"
     }
   ]
 }
@@ -272,7 +273,7 @@ $ agents --format json diagnostics
   "messages": [
     {
       "level": "ok",
-      "text": "completed"
+      "text": "ok"
     }
   ]
 }
@@ -294,10 +295,10 @@ $ agents --format json diagnostics --check
 
 ---
 
-### Step 7: List actors with the `-f` shorthand
+### Step 7: List actors with the per-command flag
 
 ```bash
-$ agents -f json actor list
+$ agents actor list --format json
 ```
 
 **Expected Output:**
@@ -325,7 +326,7 @@ $ agents -f json actor list
   "messages": [
     {
       "level": "ok",
-      "text": "completed"
+      "text": "ok"
     }
   ]
 }
@@ -333,20 +334,17 @@ $ agents -f json actor list
 
 **What's Happening:**
 
-`actor list` uses the **same global `--format` flag** — the format is stored in
-`ctx.obj["format"]` by the root callback and read by the subcommand. The `data`
-field is a JSON array when the command returns a list of items.
-
-> **Note:** `actor list` also accepts a **per-command** `--format` / `-f` flag
-> for backward compatibility. The global flag takes precedence when both are
-> present.
+`actor list` defines its **own** `--format`/`-f` option. The global flag handled
+by the root `agents` command is not propagated here, so provide `--format` after
+the subcommand when you need structured output. The `data` field is a JSON array
+when the command returns a list of items.
 
 ---
 
 ### Step 8: List actors in YAML format
 
 ```bash
-$ agents -f yaml actor list
+$ agents actor list --format yaml
 ```
 
 **Expected Output:**
@@ -368,7 +366,7 @@ timing:
   duration_ms: 11
 messages:
 - level: ok
-  text: completed
+  text: ok
 ```
 
 ---
@@ -376,7 +374,7 @@ messages:
 ### Step 9: List actors in plain format
 
 ```bash
-$ agents -f plain actor list
+$ agents actor list --format plain
 ```
 
 **Expected Output:**
@@ -415,7 +413,7 @@ $ agents -f json diagnostics | jq '.data.has_errors'
 false
 
 # List all actor names
-$ agents -f json actor list | jq -r '.data[].name'
+$ agents actor list --format json | jq -r '.data[].name'
 anthropic/claude-sonnet-4-6
 
 # Get the timing for a command
@@ -437,7 +435,7 @@ $ agents -f json diagnostics | jq '.data.checks[] | select(.status == "warn")'
 | `yaml` | Yes | No | Config files, human-readable structured data |
 | `plain` | No | No | `grep`/`awk` pipelines, minimal terminals |
 | `table` | No | Box-drawing chars | Tabular data in terminals |
-| `color` | No | Yes (ANSI) | Coloured output without Rich panels |
+| `color` | No | No | Legacy alias for plain text output |
 
 ---
 
@@ -449,18 +447,21 @@ $ agents -f json diagnostics | jq '.data.checks[] | select(.status == "warn")'
 ```
 # 1. JSON version — envelope with data.version
 $ agents --format json version
-{"command": "version", "status": "ok", "exit_code": 0,
+{"command": "", "status": "ok", "exit_code": 0,
  "data": {"version": "1.0.0", "channel": "stable", ...},
- "timing": {"duration_ms": 3}, "messages": [{"level": "ok", "text": "version completed"}]}
+ "timing": {"duration_ms": 3}, "messages": [{"level": "ok", "text": "ok"}]}
 
 # 2. YAML version — same envelope, YAML syntax
 $ agents --format yaml version
-command: version
+command: ''
 status: ok
 exit_code: 0
 data:
   version: 1.0.0
   ...
+messages:
+- level: ok
+  text: ok
 
 # 3. Plain version — raw key:value, no envelope
 $ agents --format plain version
@@ -483,17 +484,17 @@ $ agents --format json diagnostics
 {"data": {"checks": [...], "summary": {"total": 11, "ok": 9, "warnings": 2, "errors": 0}}}
 
 # 7. JSON actor list — data is an array
-$ agents -f json actor list
+$ agents actor list --format json
 {"data": [{"name": "anthropic/claude-sonnet-4-6", "provider": "anthropic", ...}]}
 
 # 8. YAML actor list
-$ agents -f yaml actor list
+$ agents actor list --format yaml
 data:
 - name: anthropic/claude-sonnet-4-6
   ...
 
 # 9. Plain actor list — key:value per actor, --- separator between actors
-$ agents -f plain actor list
+$ agents actor list --format plain
 name: anthropic/claude-sonnet-4-6
 provider: anthropic
 ...
@@ -523,7 +524,7 @@ Now that you've seen all six output formats, try these variations:
 
 - **CI health check**: `agents -f json diagnostics --check && echo "All good"`
 - **Extract a field**: `agents -f json version | jq -r '.data.commit'`
-- **Monitor actor count**: `agents -f json actor list | jq '.data | length'`
+- **Monitor actor count**: `agents actor list --format json | jq '.data | length'`
 - **YAML config snapshot**: `agents -f yaml info > system-snapshot.yaml`
 - **Plain grep**: `agents -f plain info | grep database`
 

docs/showcase/examples.json

@@ -12,9 +12,9 @@
         "agents -f json version",
         "agents --format json info",
         "agents --format json diagnostics",
-        "agents -f json actor list",
-        "agents -f yaml actor list",
-        "agents -f plain actor list"
+        "agents actor list --format json",
+        "agents actor list --format yaml",
+        "agents actor list --format plain"
       ],
       "complexity": "intermediate",
       "educational_value": "high",
@@ -77,7 +77,7 @@
       "keywords": ["CLI", "command-line", "terminal", "console", "tool"]
     },
     "api-clients": {
-      "name": "API Clients", 
+      "name": "API Clients",
       "description": "Command-line clients for web APIs",
       "keywords": ["API", "REST", "client", "HTTP", "web", "request"]
     },
@@ -92,5 +92,5 @@
       "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
     }
   },
-  "last_updated": null
+  "last_updated": "2026-04-07"
 }