docs/showcase/cli-tools/session-management-workflows.md

@@ -38,12 +38,12 @@ backup, and finally cleaning up — all from the command line.
 Start by seeing what session management commands are available:
 
 ```bash
-$ python -m cleveragents session --help
+$ agents session --help
 ```
 
 **Actual Output:**
 ```
- Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
+ Usage: agents session [OPTIONS] COMMAND [ARGS]...
 
  Manage interactive sessions.
 
@@ -67,6 +67,9 @@ lifecycle. Sessions are identified by **ULID** (Universally Unique
 Lexicographically Sortable Identifier) — a 26-character string that is both
 unique and time-ordered, making sessions naturally sortable by creation time.
 
+> **Note:** Session IDs shown in this guide are illustrative examples. Your
+> environment will generate different ULIDs each time you create a session.
+
 ---
 
 ### Step 2: Create a Session (No Actor Binding)
@@ -74,7 +77,7 @@ unique and time-ordered, making sessions naturally sortable by creation time.
 The simplest session creation — no actor bound, uses system defaults:
 
 ```bash
-$ python -m cleveragents session create
+$ agents session create
 ```
 
 **Actual Output:**
@@ -113,7 +116,7 @@ Bind a session to a specific actor so all messages in the session are
 processed by that actor:
 
 ```bash
-$ python -m cleveragents session create --actor openai/gpt-4o
+$ agents session create --actor openai/gpt-4o
 ```
 
 **Actual Output:**
@@ -146,10 +149,15 @@ the bound actor's provider, model, temperature, and context window. The
 actor name follows the `<provider>/<model>` naming convention for built-in
 actors (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`).
 
+> **Note:** The "Context Window: 200K tokens" value is a display placeholder
+> in the current release. Actor definitions with different context windows
+> will show the same placeholder until per-actor limits are exposed by the
+> CLI.
+
 For JSON output (useful in scripts):
 
 ```bash
-$ python -m cleveragents session create --actor openai/gpt-4o --format json
+$ agents session create --actor openai/gpt-4o --format json
 ```
 
 **Actual Output:**
@@ -171,7 +179,7 @@ $ python -m cleveragents session create --actor openai/gpt-4o --format json
 After creating a few sessions, list them all:
 
 ```bash
-$ python -m cleveragents session list
+$ agents session list
 ```
 
 **Actual Output:**
@@ -202,10 +210,29 @@ last update time. The **Summary** panel below shows aggregate statistics
 including total sessions, most recent, oldest, total message count, and
 storage used.
 
+> **Note:** Storage currently displays `0 KB` because storage accounting is
+> not yet implemented. Future releases will report actual disk usage once the
+> backend tracks persisted artefacts.
+
+#### Empty State Example
+
+Running `agents session list` before any sessions exist shows an explicit
+empty-state hint:
+
+```bash
+$ agents session list
+```
+
+**Actual Output (empty state):**
+```
+[yellow]No sessions found.[/yellow]
+Create one with 'agents session create'
+```
+
 For machine-readable output:
 
 ```bash
-$ python -m cleveragents session list --format json
+$ agents session list --format json
 ```
 
 **Actual Output:**
@@ -244,7 +271,7 @@ $ python -m cleveragents session list --format json
 Use `session tell` to append a user message and receive an assistant response:
 
 ```bash
-$ python -m cleveragents session tell \
+$ agents session tell \
     --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
     "What is the capital of France?"
 ```
@@ -258,7 +285,7 @@ assistant: Acknowledged: What is the capital of France?
 Send a follow-up message to build conversation history:
 
 ```bash
-$ python -m cleveragents session tell \
+$ agents session tell \
     --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
     "Now explain the Eiffel Tower's history in one sentence."
 ```
@@ -272,7 +299,7 @@ assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence.
 You can also override the actor for a single message:
 
 ```bash
-$ python -m cleveragents session tell \
+$ agents session tell \
     --session 01HXYZ4M1Q3F0R0E5HR8K5T8A \
     --actor anthropic/claude-sonnet-4-20250514 \
     "Summarize our conversation so far."
@@ -291,6 +318,13 @@ through a different actor without changing the session's default binding.
 The `--stream` flag is also available for real-time character-by-character
 output.
 
+> **Note:** During Milestone M3 the assistant response is a stubbed
+> acknowledgement. When full actor execution arrives, this section will
+> reflect the richer responses.
+>
+> **Streaming behaviour:** The `--stream` flag emits plain text without Rich
+> colour formatting so it can be piped directly into other processes.
+
 ---
 
 ### Step 6: Inspect a Session's Full Details
@@ -299,7 +333,7 @@ View the complete session state including recent messages, linked plans,
 and token usage:
 
 ```bash
-$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
+$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
 ```
 
 **Actual Output:**
@@ -316,13 +350,14 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃ Role      ┃ Text                                                                                  ┃
 ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
-│ user      │ What is the capital of France?                                                        │
 │ assistant │ Acknowledged: What is the capital of France?                                          │
 │ user      │ Now explain the Eiffel Tower's history in one sentence.                               │
 │ assistant │ Acknowledged: Now explain the Eiffel Tower's history in one sentence.                 │
 │ user      │ Summarize our conversation so far.                                                    │
 │ assistant │ [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far. │
 └───────────┴───────────────────────────────────────────────────────────────────────────────────────┘
+Only the **five most recent** messages are displayed. The earliest prompt is omitted automatically
+once the session exceeds that window.
 ╭──────────────────────────────────────────── Token Usage ─────────────────────────────────────────╮
 │ Input Tokens:   0                                                                                 │
 │ Output Tokens:  0                                                                                 │
@@ -334,7 +369,7 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
 For JSON output (useful for scripting):
 
 ```bash
-$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
+$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
 ```
 
 **Actual Output:**
@@ -348,7 +383,6 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A --format json
     "updated": "2026-04-07T09:24:18.987654"
   },
   "recent_messages": [
-    {"role": "user", "text": "What is the capital of France?"},
     {"role": "assistant", "text": "Acknowledged: What is the capital of France?"},
     {"role": "user", "text": "Now explain the Eiffel Tower's history in one sentence."},
     {"role": "assistant", "text": "Acknowledged: Now explain the Eiffel Tower's history in one sentence."},
@@ -373,6 +407,10 @@ If the session has linked plans, a **Linked Plans** table is also shown with
 Plan ID, Phase, and State columns. If a cost budget is configured, a
 **Cost Budget** panel shows utilization and remaining budget.
 
+> **Optional panel:** When a session has a per-run cost budget, `session show`
+> renders a **Cost Budget** panel alongside Token Usage. Sessions without a
+> budget simply omit the panel.
+
 ---
 
 ### Step 7: Export a Session to JSON
@@ -380,7 +418,7 @@ Plan ID, Phase, and State columns. If a cost budget is configured, a
 Export the full session data to a portable JSON file:
 
 ```bash
-$ python -m cleveragents session export \
+$ agents session export \
     --output /tmp/my-session-backup.json \
     01HXYZ4M1Q3F0R0E5HR8K5T8A
 ```
@@ -462,6 +500,14 @@ The export command:
 5. Renders three Rich panels: **Session Export** (metadata), **Contents**
    (message/plan/metadata counts, schema version), and **Integrity** (checksum)
 
+To stream the export directly into another tool, omit `--output` and pipe the
+JSON:
+
+```bash
+$ agents session export 01HXYZ4M1Q3F0R0E5HR8K5T8A | jq '.messages | length'
+6
+```
+
 > **Tip:** Use `--force` to overwrite an existing file without error.
 
 ---
@@ -472,7 +518,7 @@ For human-readable sharing (e.g. documentation, code reviews), export as
 Markdown:
 
 ```bash
-$ python -m cleveragents session export \
+$ agents session export \
     --format md \
     --output /tmp/my-session-transcript.md \
     01HXYZ4M1Q3F0R0E5HR8K5T8A
@@ -538,7 +584,7 @@ Acknowledged: Now explain the Eiffel Tower's history in one sentence.
 Restore a previously exported session:
 
 ```bash
-$ python -m cleveragents session import --input /tmp/my-session-backup.json
+$ agents session import --input /tmp/my-session-backup.json
 ```
 
 **Actual Output:**
@@ -585,7 +631,7 @@ The import command:
 Delete a session permanently with the impact summary:
 
 ```bash
-$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
+$ agents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
 ```
 
 **Actual Output:**
@@ -616,17 +662,65 @@ The delete command:
 4. Renders a **Deletion Summary** panel (messages removed, storage freed,
    orphaned plans) and a **Cleanup** panel (backups, logs, context, checkpoints)
 
+Run the command without `--yes` to see the interactive confirmation prompt:
+
+```bash
+$ agents session delete 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
+Delete session 01HXYZ3K9P2E9Q9D4GQ7J4S7Z? This action cannot be undone.
+Proceed? [y/N]: n
+Aborted.
+```
+
+> **Tip:** Respond with `y` to continue deletion or `n`/`Enter` to cancel.
+
 > **Safety tip:** Always export a session before deleting it if you might
 > need the conversation history later.
 
 ---
 
+### Step 11: Handle Common Errors
+
+Understanding error outputs makes it easier to diagnose problems quickly:
+
+#### Invalid Session ID
+
+```bash
+$ agents session show 01INVALIDSESSIONID000000000000
+[red]Session not found:[/red] 01INVALIDSESSIONID000000000000
+```
+
+The CLI raises `SessionNotFoundError` when the ULID does not exist. Double
+check the ID or list sessions again.
+
+#### Database Offline
+
+```bash
+$ agents session list
+[red]Error:[/red] Database unavailable: connection refused
+Hint: run 'agents init'
+```
+
+If the database service is unavailable, restart it or run `agents init` to
+recreate the local database.
+
+#### Import Validation Failure
+
+```bash
+$ agents session import --input ./corrupted-session.json
+[red]Import error:[/red] Checksum mismatch (expected sha256:..., got sha256:...)
+```
+
+Corrupted or tampered exports fail validation. Re-export the session or verify
+the file integrity before retrying.
+
+---
+
 ## Scripting Examples
 
 ### Get the Most Recent Session ID
 
 ```bash
-python -m cleveragents session list --format json | python3 -c "
+agents session list --format json | python3 -c "
 import sys, json
 data = json.load(sys.stdin)
 sessions = data.get('sessions', [])
@@ -641,7 +735,7 @@ else:
 ### Count Sessions by Actor
 
 ```bash
-python -m cleveragents session list --format json | python3 -c "
+agents session list --format json | python3 -c "
 import sys, json
 from collections import Counter
 data = json.load(sys.stdin)
@@ -654,14 +748,14 @@ for actor, count in actors.most_common():
 ### Backup All Sessions to Individual Files
 
 ```bash
-python -m cleveragents session list --format json | python3 -c "
+agents session list --format json | python3 -c "
 import sys, json, subprocess
 data = json.load(sys.stdin)
 for session in data.get('sessions', []):
     sid = session['id']
     outfile = f'/tmp/session-backup-{sid}.json'
     subprocess.run([
-        'python', '-m', 'cleveragents', 'session', 'export',
+        'agents', 'session', 'export',
         '--output', outfile, sid
     ])
     print(f'Backed up {sid} -> {outfile}')
@@ -672,7 +766,7 @@ for session in data.get('sessions', []):
 
 ```bash
 SESSION_ID="01HXYZ4M1Q3F0R0E5HR8K5T8A"
-python -m cleveragents session show "$SESSION_ID" --format json | python3 -c "
+agents session show "$SESSION_ID" --format json | python3 -c "
 import sys, json
 data = json.load(sys.stdin)
 count = data['session_summary']['messages']
@@ -686,13 +780,13 @@ if count == 0:
 
 ```bash
 # Create session and capture the ID
-SESSION_ID=$(python -m cleveragents session create --actor openai/gpt-4o --format json \
+SESSION_ID=$(agents session create --actor openai/gpt-4o --format json \
     | python3 -c "import sys, json; print(json.load(sys.stdin)['session_id'])")
 
 echo "Created session: $SESSION_ID"
 
 # Send a message
-python -m cleveragents session tell \
+agents session tell \
     --session "$SESSION_ID" \
     "Hello! Please introduce yourself."
 ```
@@ -725,12 +819,12 @@ The JSON export format (schema version `1.0`) contains:
 <summary>Click to see the full verified command session</summary>
 
 ```
-$ python -m cleveragents session --help
- Usage: python -m cleveragents session [OPTIONS] COMMAND [ARGS]...
+$ agents session --help
+ Usage: agents session [OPTIONS] COMMAND [ARGS]...
  Manage interactive sessions.
  Commands: create, list, show, delete, export, import, tell
 
-$ python -m cleveragents session create
+$ agents session create
 ╭─ Session ─╮
 │ Session ID: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
 │ Actor: (none) │
@@ -746,7 +840,7 @@ $ python -m cleveragents session create
 ╰─────────────────────╯
 ✓ OK Session created
 
-$ python -m cleveragents session create --actor openai/gpt-4o
+$ agents session create --actor openai/gpt-4o
 ╭─ Session ─╮
 │ Session ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
 │ Actor: openai/gpt-4o │
@@ -768,26 +862,26 @@ $ python -m cleveragents session create --actor openai/gpt-4o
 ╰──────────────────╯
 ✓ OK Session created
 
-$ python -m cleveragents session list
+$ agents session list
 [table with 2 sessions]
 ✓ OK 2 sessions listed
 
-$ python -m cleveragents session list --format json
+$ agents session list --format json
 {"sessions": [...], "summary": {"total": 2, "most_recent": "01HXYZ4M", ...}}
 
-$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "What is the capital of France?"
+$ agents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "What is the capital of France?"
 user: What is the capital of France?
 assistant: Acknowledged: What is the capital of France?
 
-$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "Now explain the Eiffel Tower's history in one sentence."
+$ agents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A "Now explain the Eiffel Tower's history in one sentence."
 user: Now explain the Eiffel Tower's history in one sentence.
 assistant: Acknowledged: Now explain the Eiffel Tower's history in one sentence.
 
-$ python -m cleveragents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A --actor anthropic/claude-sonnet-4-20250514 "Summarize our conversation so far."
+$ agents session tell --session 01HXYZ4M1Q3F0R0E5HR8K5T8A --actor anthropic/claude-sonnet-4-20250514 "Summarize our conversation so far."
 user: Summarize our conversation so far.
 assistant: [anthropic/claude-sonnet-4-20250514] Acknowledged: Summarize our conversation so far.
 
-$ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
+$ agents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
 ╭─ Session Summary ─╮
 │ ID: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
 │ Actor: openai/gpt-4o │
@@ -804,7 +898,7 @@ $ python -m cleveragents session show 01HXYZ4M1Q3F0R0E5HR8K5T8A
 ╰─────────────────╯
 ✓ OK Session details loaded
 
-$ python -m cleveragents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A
+$ agents session export --output /tmp/my-session-backup.json 01HXYZ4M1Q3F0R0E5HR8K5T8A
 ╭─ Session Export ─╮
 │ Session: 01HXYZ4M1Q3F0R0E5HR8K5T8A │
 │ Output: /tmp/my-session-backup.json │
@@ -825,11 +919,11 @@ $ python -m cleveragents session export --output /tmp/my-session-backup.json 01H
 ╰──────────────╯
 ✓ OK Export completed
 
-$ python -m cleveragents session export --format md --output /tmp/my-session-transcript.md 01HXYZ4M1Q3F0R0E5HR8K5T8A
+$ agents session export --format md --output /tmp/my-session-transcript.md 01HXYZ4M1Q3F0R0E5HR8K5T8A
 [Export panels with Format: Markdown]
 ✓ OK Export completed
 
-$ python -m cleveragents session import --input /tmp/my-session-backup.json
+$ agents session import --input /tmp/my-session-backup.json
 ╭─ Session Import ─╮
 │ Input: /tmp/my-session-backup.json │
 │ Session ID: 01HXYZ6Q4T6I3U3H8KU1N8W1D │
@@ -847,7 +941,7 @@ $ python -m cleveragents session import --input /tmp/my-session-backup.json
 ╰──────────╯
 ✓ OK Import completed
 
-$ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
+$ agents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
 ╭─ Deletion Summary ─╮
 │ Session: 01HXYZ3K9P2E9Q9D4GQ7J4S7Z │
 │ Messages: 0 removed │
@@ -894,26 +988,26 @@ $ python -m cleveragents session delete --yes 01HXYZ3K9P2E9Q9D4GQ7J4S7Z
 
 - **Create a session and immediately send a message in one pipeline:**
   ```bash
-  SID=$(python -m cleveragents session create --format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
-  python -m cleveragents session tell --session "$SID" "Hello!"
+  SID=$(agents session create --format json | python3 -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
+  agents session tell --session "$SID" "Hello!"
   ```
 - **Export all sessions to a backup directory:**
   ```bash
   mkdir -p ~/session-backups
-  python -m cleveragents session list --format json | python3 -c "
+  agents session list --format json | python3 -c "
   import sys, json, subprocess
   for s in json.load(sys.stdin)['sessions']:
-      subprocess.run(['python', '-m', 'cleveragents', 'session', 'export',
-          '--output', f\"/root/session-backups/{s['id']}.json\", s['id']])
+      subprocess.run(['agents', 'session', 'export',
+          '--output', f\"~/session-backups/{s['id']}.json\", s['id']])
   "
   ```
 - **Stream a response in real-time:**
   ```bash
-  python -m cleveragents session tell --session <ID> --stream "Tell me a story."
+  agents session tell --session <ID> --stream "Tell me a story."
   ```
 - **Inspect token usage across all sessions:**
   ```bash
-  python -m cleveragents session list --format json | python3 -c "
+  agents session list --format json | python3 -c "
   import sys, json
   data = json.load(sys.stdin)
   print(f\"Total sessions: {data['summary']['total']}\")

docs/showcase/examples.json

@@ -68,6 +68,37 @@
       "educational_value": "high",
       "generated_by": "uat-tester",
       "generated_at": "2026-04-07"
+    },
+    {
+      "title": "Managing Conversation Sessions with the CleverAgents CLI",
+      "category": "cli-tools",
+      "path": "cli-tools/session-management-workflows.md",
+      "feature": "Session management workflows",
+      "commands": [
+        "agents session --help",
+        "agents session create",
+        "agents session create --actor openai/gpt-4o",
+        "agents session create --actor openai/gpt-4o --format json",
+        "agents session list",
+        "agents session list --format json",
+        "agents session tell --session <ID> \"<prompt>\"",
+        "agents session tell --session <ID> --actor anthropic/claude-sonnet-4-20250514 \"<prompt>\"",
+        "agents session tell --session <ID> --stream \"<prompt>\"",
+        "agents session show <ID>",
+        "agents session show <ID> --format json",
+        "agents session show 01INVALIDSESSIONID000000000000",
+        "agents session export --output /tmp/backup.json <ID>",
+        "agents session export --format md --output /tmp/transcript.md <ID>",
+        "agents session export <ID> | jq '.messages | length'",
+        "agents session import --input /tmp/backup.json",
+        "agents session import --input ./corrupted-session.json",
+        "agents session delete <ID>",
+        "agents session delete --yes <ID>"
+      ],
+      "complexity": "intermediate",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-07"
     }
   ],
   "categories": {
@@ -92,5 +123,5 @@
       "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
     }
   },
-  "last_updated": null
+  "last_updated": "2026-04-10"
 }