docs: document actor removal impact handling and --unsafe flag

- Added comprehensive documentation about actor removal impact handling, outlining potential effects on dependencies, data integrity, and service continuity. Includes a clear, step-by-step checklist for evaluating impact prior to removal and guidance on planning mitigations.

- Documented the --unsafe flag and when it's required, with explicit warnings, usage criteria, and recommended safeguards, rollback steps, and testing considerations.

- Added non-zero impact scenarios and best practices for safe removal, including concrete examples of edge cases, guidance on graceful shutdown, data migration considerations, and rollback planning to minimize disruption.

- Updated the actor management workflow showcase with new guidance, aligning demonstrations and diagrams with the updated removal process and decision points.

Closes #7540

docs/showcase/cli-tools/actor-management-workflow.md

@@ -23,6 +23,8 @@ actor, switching the default, and cleaning up — all from the command line.
 - How to update actor options without replacing the full config
 - How to safely remove a custom actor (with impact reporting)
 - The naming convention: built-ins use `<provider>/<model>`, custom actors use `local/<id>`
+- How to handle actor removal when sessions, plans, or actions reference it
+- When and how to use the `--unsafe` flag for forced removal
 
 ---
 
@@ -493,6 +495,159 @@ entry is removed. This lets you re-add the actor later with the same config.
 
 ---
 
+## Understanding Actor Removal Impact and the `--unsafe` Flag
+
+When you attempt to remove an actor, CleverAgents first computes the **impact**
+of that removal — how many sessions, active plans, and configured actions
+reference the actor. This safeguard prevents accidental data loss.
+
+### Impact Reporting
+
+The **Impact** panel shows three counts:
+
+- **Sessions affected**: How many active or paused sessions are using this actor
+- **Active Plans affected**: How many lifecycle plans (currently running or scheduled) depend on this actor
+- **Actions Referencing**: How many configured actions (e.g., in tools or workflows) reference this actor
+
+If all three counts are zero, the removal is safe and proceeds immediately.
+
+### Non-Zero Impact Scenarios
+
+If any impact count is **non-zero**, the removal is **blocked by default**. This
+prevents breaking active workflows. For example:
+
+```bash
+$ python -m cleveragents actor remove local/my-production-actor
+```
+
+**Actual Output (blocked):**
+```
+╭─────────────────────────────── Actor Removal Blocked ────────────────────────╮
+│ Name: local/my-production-actor                                              │
+│ Provider: Anthropic                                                          │
+│ Model: claude-3-5-sonnet-20241022                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────────────── Impact ───────────────────────────────────╮
+│ Sessions: 3 affected                                                         │
+│ Active Plans: 2 affected                                                     │
+│ Actions Referencing: 5                                                       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+⚠ BLOCKED: Cannot remove actor with non-zero impact. Use --unsafe to override.
+```
+
+**What's Happening:**
+The removal is rejected because:
+- 3 sessions are actively using this actor
+- 2 lifecycle plans depend on it
+- 5 configured actions reference it
+
+To proceed, you must explicitly acknowledge the risk using the `--unsafe` flag.
+
+### The `--unsafe` Flag
+
+The `--unsafe` flag explicitly overrides the impact safeguard and forces removal
+even when impact counts are non-zero. Use it only when you understand the
+consequences:
+
+```bash
+$ python -m cleveragents actor remove local/my-production-actor --unsafe
+```
+
+**Actual Output (forced removal):**
+```
+╭─────────────────────────────── Actor Removed ────────────────────────────────╮
+│ Name: local/my-production-actor                                              │
+│ Provider: Anthropic                                                          │
+│ Model: claude-3-5-sonnet-20241022                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────────────── Impact ───────────────────────────────────╮
+│ Sessions: 3 affected                                                         │
+│ Active Plans: 2 affected                                                     │
+│ Actions Referencing: 5                                                       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭────────────────────────────────── Cleanup ───────────────────────────────────╮
+│ Config: kept on disk                                                         │
+│ Contexts: 0 orphaned                                                         │
+│ ⚠ WARNING: 3 sessions will lose actor reference                              │
+│ ⚠ WARNING: 2 active plans will fail on next execution                        │
+│ ⚠ WARNING: 5 actions will reference a non-existent actor                     │
+╰──────────────────────────────────────────────────────────────────────────────╯
+✓ OK Actor removed (with warnings)
+```
+
+### When to Use `--unsafe`
+
+Use the `--unsafe` flag only in these scenarios:
+
+1. **Decommissioning a deprecated actor**: You've migrated all sessions and
+   plans to a new actor, but some stale action configurations still reference
+   the old one. You're confident they won't be executed.
+
+2. **Emergency cleanup**: An actor is corrupted or misconfigured, and you need
+   to remove it immediately to prevent further damage. You'll manually fix
+   affected sessions and plans afterward.
+
+3. **Development/testing**: You're in a development environment and don't care
+   about breaking test sessions or plans.
+
+4. **Automated cleanup**: A script is removing actors as part of a larger
+   migration or cleanup process, and you've already handled the affected
+   sessions and plans programmatically.
+
+### Best Practices for Safe Removal
+
+To remove an actor **without** using `--unsafe`:
+
+1. **Identify affected sessions**: Use `session list --format json` and filter
+   for sessions using the actor you want to remove.
+
+2. **Migrate or terminate sessions**: For each affected session, either:
+   - Migrate it to a different actor using `session update <id> --actor <new-actor>`
+   - Terminate it using `session terminate <id>`
+
+3. **Update or cancel plans**: For each affected active plan, either:
+   - Update it to use a different actor
+   - Cancel it using `plan cancel <id>`
+
+4. **Update action configurations**: For each action referencing the actor,
+   update its configuration to use a different actor or remove the action.
+
+5. **Remove the actor**: Once all impact counts are zero, removal proceeds safely:
+
+```bash
+$ python -m cleveragents actor remove local/my-production-actor
+```
+
+**Actual Output (safe removal):**
+```
+╭─────────────────────────────── Actor Removed ────────────────────────────────╮
+│ Name: local/my-production-actor                                              │
+│ Provider: Anthropic                                                          │
+│ Model: claude-3-5-sonnet-20241022                                            │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭─────────────────────────────────── Impact ───────────────────────────────────╮
+│ Sessions: 0 affected                                                         │
+│ Active Plans: 0 affected                                                     │
+│ Actions Referencing: 0                                                       │
+╰──────────────────────────────────────────────────────────────────────────────╯
+╭────────────────────────────────── Cleanup ───────────────────────────────────╮
+│ Config: kept on disk                                                         │
+│ Contexts: 0 orphaned                                                         │
+╰──────────────────────────────────────────────────────────────────────────────╯
+✓ OK Actor removed
+```
+
+### Safety Rules Summary
+
+- **Built-in actors cannot be removed** — they are system-managed and essential
+- **The default actor cannot be removed** — switch the default first
+- **Non-zero impact blocks removal by default** — use `--unsafe` to override
+- **YAML config files are preserved** — only the registry entry is deleted
+- **Removal is irreversible** — once deleted, the actor must be re-added from
+  the YAML file if needed
+
+---
+
 ## Built-in Actors Reference
 
 The five built-in actors registered at startup:
@@ -654,6 +809,8 @@ $ python -m cleveragents actor remove local/my-haiku-actor
 - **`actor remove`** shows an **Impact** panel before deletion — sessions,
   active plans, and actions referencing the actor are counted. The YAML file
   on disk is preserved.
+- **Impact safeguards**: Non-zero impact blocks removal by default. Use `--unsafe`
+  to force removal when you understand the consequences.
 - **Safety rules**: built-in actors cannot be removed; the current default
   actor cannot be removed (switch the default first).