diff --git a/docs/showcase/cli-tools/repl-and-actor-run.md b/docs/showcase/cli-tools/repl-and-actor-run.md
index 157cec3c9..74ed35c69 100644
--- a/docs/showcase/cli-tools/repl-and-actor-run.md
+++ b/docs/showcase/cli-tools/repl-and-actor-run.md
@@ -13,6 +13,11 @@ from the command line:
 
 This guide walks through both commands with real, verified output.
 
+> **Specification note:** The current `docs/specification.md` synopsis has not yet
+> been updated to include `agents repl` or the `--config` flag for
+> `agents actor run`. This showcase reflects the live CLI behaviour so users can
+> rely on the commands today while the formal spec catches up.
+
 ## Prerequisites
 
 - CleverAgents installed (`pip install cleveragents` or from source with `uv sync`)
@@ -525,6 +530,9 @@ $ agents actor run local/demo-assistant "What is the capital of France?" \
 Output written to /path/to/answer.txt
 ```
 
+> **Note:** The CLI prints the full absolute path to the file. The placeholder
+> `/path/to/answer.txt` represents the directory where you run the command.
+
 **File contents (`answer.txt`):**
 ```
 Paris is the capital of France.
@@ -845,7 +853,7 @@ the capital since the 10th century.
 $ agents actor run local/demo-assistant "What is the capital of France?" \
     --config my-assistant.yaml \
     --output answer.txt
-Output written to answer.txt
+Output written to /path/to/answer.txt
 
 $ agents actor run local/demo-assistant "Write a haiku about mountains" \
     --config my-assistant.yaml \
diff --git a/docs/showcase/examples.json b/docs/showcase/examples.json
index a9f1908f0..1675680ce 100644
--- a/docs/showcase/examples.json
+++ b/docs/showcase/examples.json
@@ -68,6 +68,28 @@
       "educational_value": "high",
       "generated_by": "uat-tester",
       "generated_at": "2026-04-07"
+    },
+    {
+      "title": "REPL and Actor Run: Interactive AI Sessions from the Terminal",
+      "category": "cli-tools",
+      "path": "cli-tools/repl-and-actor-run.md",
+      "feature": "REPL and interactive session",
+      "commands": [
+        "agents repl",
+        "agents repl --no-history",
+        "agents repl --history-path /path/to/history",
+        "agents actor run --help",
+        "agents actor run openai/gpt-4o \"Say hello\"",
+        "agents actor run local/demo-assistant \"What is the capital of France?\" --config my-assistant.yaml",
+        "agents actor run local/demo-assistant \"Write a haiku\" --config my-assistant.yaml --temperature 0.9",
+        "agents actor run local/demo-assistant \"Hello\" --config my-assistant.yaml --output answer.txt",
+        "agents actor run local/demo-assistant \"Hello\" --config my-assistant.yaml --context my-session --context-dir /tmp/ctx",
+        "agents actor run local/my-actor \"Hello\" --config my-actor.yaml --skill local/file-ops"
+      ],
+      "complexity": "intermediate",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-07"
     }
   ],
   "categories": {
@@ -77,7 +99,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 +114,5 @@
       "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
     }
   },
-  "last_updated": null
+  "last_updated": "2026-04-07"
 }