Merge pull request 'docs: add showcase example for CLI version/info/diagnostics basics' (#11108) from fix-pr-4211 into master

CHANGELOG.md

@@ -515,6 +515,12 @@ _ALL_DATA_COLUMNS + ") " "SELECT " + _ALL_DATA_COLUMNS + " FROM v3_plans"`.
   Resolution chain is logged at debug level via the
   `PrecedenceResolution` dataclass and `PrecedenceSource` enum.
 
+- **CLI showcase: version/info/diagnostics basics (#4211)**: Added a verified CLI showcase example
+  for the `version`, `info`, and `diagnostics` introspection commands. The guide walks through
+  fast-path eager flag behavior (`--help`, `--version`), rich format output with Rich panels,
+  machine-readable JSON envelope structure shared across all CLI commands, and CI-friendly
+  `diagnostics --check` health monitoring. Registered in `docs/showcase/examples.json`. Closes #7592.
+
 - `agents actor context clear` command to reset actor message history and
   state while preserving the underlying context directory via `ContextManager`
   (#6370).

CONTRIBUTORS.md

@@ -56,6 +56,8 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
 * HAL 9000 has contributed the architecture-pool-supervisor milestone assignment feature (PR #8188 / issue #7521): added `forgejo_update_pull_request` permission and documented the PR workflow for major spec changes, enabling automatic milestone assignment for specification PRs.
 * HAL 9000 has contributed the git worktree TOCTOU race condition fix (PR #8178 / issue #7507): replaced the unsafe mkdtemp() + rmdir() pattern with a parent-directory approach to eliminate the race window in concurrent git worktree operations.
+* HAL 9000 has contributed CLI documentation for version, info, and diagnostics commands (PR #4211 / issue #7592): created a beginner-friendly showcase walkthrough covering fast-path eager flags, rich format output with Rich panels, machine-readable JSON envelope structure, and CI-friendly diagnostics health checks.
+
 * HAL 9000 has contributed the git_tools TOCTOU race condition fix (PR #8255 / issue #7619): eliminated the Time-Of-Check-To-Time-Of-Use race in `_get_base_env()` by adding double-checked locking with a module-level `threading.Lock`, preventing concurrent threads from writing conflicting environment snapshots.
 * HAL 9000 has contributed the ActorLoader.list_actors TOCTOU race condition fix (PR #8660 / issue #8588): moved the namespace filter inside the ``with self._lock:`` block in ``list_actors()`` so that dictionary reads and filtering are atomic, eliminating stale results and potential ``RuntimeError`` under concurrent access. Added concurrency BDD coverage via Behave test scenarios using ``threading.Barrier``.
 * HAL 9000 has contributed the mandatory PR compliance checklist to `implementation-supervisor.md` (#9824): added an 8-item checklist to the worker prompt body with concrete items covering CHANGELOG.md, CONTRIBUTORS.md, commit footer, CI verification, BDD tests, Epic reference, labels, and milestone assignment to eliminate systemic PR merge blockers.

docs/showcase/cli-tools/cleveragents-cli-basics.md

@@ -460,9 +460,7 @@ based on code analysis. Exact values depend on your local environment.*
 - **`--format`** is a global flag that must come **before** the subcommand.
 - **`diagnostics --check`** is CI-friendly: exits non-zero only when there are
   actual `ERROR`-level checks (missing API keys are `WARN`, not `ERROR`).
-- All three introspection commands (`version`, `info`, `diagnostics`) are
-  **lightweight** — they're in the fast-path that avoids loading heavy
-  subcommand modules.
+- Both --help and --version use a fast-path eager exit that avoids loading subcommand modules, resulting in instant response times. The version, info, and diagnostics commands are lightweight introspection tools but do not benefit from the fast-path optimization.
 
 ## Try It Yourself
 

docs/showcase/examples.json

@@ -21,6 +21,27 @@
       "generated_by": "uat-tester",
       "generated_at": "2026-04-19"
     },
+    {
+      "title": "CleverAgents CLI Basics: Version, Info & Diagnostics",
+      "category": "cli-tools",
+      "path": "cli-tools/cleveragents-cli-basics.md",
+      "feature": "CLI version/info/diagnostics basics \u2014 fast-path behavior and output envelope",
+      "commands": [
+        "python -m cleveragents --help",
+        "python -m cleveragents --version",
+        "python -m cleveragents version",
+        "python -m cleveragents --format json version",
+        "python -m cleveragents info",
+        "python -m cleveragents --format json info",
+        "python -m cleveragents diagnostics",
+        "python -m cleveragents --format json diagnostics",
+        "python -m cleveragents diagnostics --check"
+      ],
+      "complexity": "beginner",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-07"
+    },
     {
       "title": "Mastering Output Format Flags in CleverAgents CLI",
       "category": "cli-tools",
@@ -216,5 +237,5 @@
       ]
     }
   },
-  "last_updated": "2026-04-27"
+  "last_updated": "2026-05-07"
 }