diff --git a/docs/showcase/cli-tools/repl-and-actor-run.md b/docs/showcase/cli-tools/repl-and-actor-run.md
index 157cec3c9..7e394e292 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`)