CHANGELOG.md

@@ -727,6 +727,14 @@ uko-oo:Class` triple emission in `PythonAnalyzer._extract_class()` so that
   suite (7 scenarios) covering label lookup, milestone lookup, worker dispatch,
   PR creation with metadata, and error handling for missing labels/milestones.
 
+- **Tool and Validation Management Showcase** (#4565): Added
+  `docs/showcase/cli-tools/tool-and-validation-management.md`, a step-by-step
+  CLI guide covering the complete lifecycle for managing tools and validations
+  (register, list, inspect, update, remove). Demonstrates the unified registry,
+  capability flags, validation modes and wrapped validations. Indexed the new
+  example in `docs/showcase/examples.json` and added a callout explaining why
+  capability flags display as `(default)` in the detail view.
+
 - Wired `StrategyActor` into the real plan execution path: `_get_plan_executor`
   in `plan.py` now resolves the strategy actor via `resolve_strategy_actor()`
   (reading the `actor.default.strategy` config key) instead of always

docs/showcase/cli-tools/tool-and-validation-management.md

@@ -368,6 +368,12 @@ $ agents tool show qa/coverage-check
 (`namespace/short-name`). For validations, the panel includes an extra
 **Validation Mode** field showing `required` or `informational`.
 
+> **Why do capabilities show as `(default)`?**
+> The detail view collapses the default capability flags and omits resource slot
+> bindings when they match the defaults stored in the registry. The values you
+> set during registration are still persisted and enforced when the tool runs,
+> even though the summary view shows `(default)` / `(none)`.
+
 ---
 
 ### Step 7: Get machine-readable JSON output

docs/showcase/examples.json

@@ -97,6 +97,31 @@
       "educational_value": "high",
       "generated_by": "uat-tester",
       "generated_at": "2026-04-07"
+    },
+    {
+      "title": "Managing Tools and Validations in CleverAgents",
+      "category": "cli-tools",
+      "path": "cli-tools/tool-and-validation-management.md",
+      "feature": "Tool and validation management",
+      "commands": [
+        "agents tool add --config examples/tools/custom-tool.yaml",
+        "agents validation add --config examples/validations/required-validation.yaml",
+        "agents validation add --config examples/validations/wrapped-validation.yaml",
+        "agents tool list",
+        "agents tool list --type validation",
+        "agents tool list --type tool",
+        "agents tool list --namespace qa",
+        "agents tool show local/line-counter",
+        "agents tool show qa/coverage-check",
+        "agents tool list --format json",
+        "agents tool show local/line-counter --format json",
+        "agents validation add --config examples/validations/required-validation.yaml --update",
+        "agents tool remove --yes local/line-counter"
+      ],
+      "complexity": "intermediate",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-07"
     }
   ],
   "categories": {