docs: address session showcase review feedback

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

@@ -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)
@@ -146,6 +149,11 @@ 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
@@ -202,6 +210,25 @@ 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
@@ -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
@@ -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
@@ -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.
 
 ---
@@ -616,11 +662,59 @@ 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

docs/showcase/examples.json

@@ -86,9 +86,13 @@
         "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",
@@ -119,5 +123,5 @@
       "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
     }
   },
-  "last_updated": "2026-04-07"
+  "last_updated": "2026-04-10"
 }