docs: address review feedback for plan lifecycle showcase

docs/showcase/cli-tools/action-and-plan-management.md

@@ -61,6 +61,8 @@ agents plan apply <plan-id>     ← writes changes to disk
 Plan (phase: apply, state: applied) ← terminal
 ```
 
+> **Note:** The lifecycle is not strictly linear — plans can revert from Execute or Apply back to Strategize when constraints (such as the `constrained` state) require reassessment.
+
 ---
 
 ## Step-by-Step Walkthrough
@@ -479,19 +481,20 @@ $ agents plan list
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ ID                         ┃ Name                                   ┃ Phase      ┃ State    ┃ Action                 ┃ Invaria… ┃ Projects           ┃ Updated            ┃ Elapsed       ┃
 ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
-│ 01KNKJZ44ES00VT8JTRKX1HEQA │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ (none)             │ 2026-04-07 09:04   │ 00:00:50      │
 │ 01KNKJZ424C48388RWHW3KY5QZ │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ local/my-webapp    │ 2026-04-07 09:04   │ 00:00:50      │
 │ 01KNKK0MKCDXGP8Z3PZ88S5GGZ │ local/security-audit-01knkk0m         │ strategize │ queued   │ local/security-audit   │ 1        │ local/my-webapp    │ 2026-04-07 09:05   │ 00:00:00      │
 └────────────────────────────┴────────────────────────────────────────┴────────────┴──────────┴────────────────────────┴──────────┴────────────────────┴────────────────────┴───────────────┘
 ╭────────────────────────────────── Summary ───────────────────────────────────╮
-│ Total: 3                                                                     │
+│ Total: 2                                                                     │
 │ Processing: 0                                                                │
 │ Completed: 0                                                                 │
 │ Errored: 0                                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
-✓ OK 3 plans listed
+✓ OK 2 plans listed
 ```
 
+> **Tip:** This walkthrough concentrates on plan creation and lifecycle inspection. The `agents plan execute` and `agents plan apply` commands are covered in dedicated execution/apply showcases.
+
 ---
 
 ### Step 13: Filter plans by phase, state, and action
@@ -620,7 +623,7 @@ $ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json
 ### Step 16: Cancel a plan
 
 ```bash
-$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA
+$ agents plan cancel 01KNKJZ424C48388RWHW3KY5QZ
 ```
 
 **Output:**
@@ -662,7 +665,7 @@ local/security-audit
 
 # Count queued plans
 $ agents plan list --state queued --format json | jq '.data | length'
-3
+2
 
 # Get all plan IDs for a specific action
 $ agents plan list --action local/security-audit --format json \
@@ -681,6 +684,7 @@ $ agents plan list --format json | jq '.data[] | select(.state == "errored") | .
 
 | Phase | Description |
 |---|---|
+| `action` | Reusable template phase — transitions to Strategize via `agents plan use` |
 | `strategize` | AI creates an execution strategy (decisions tree) |
 | `execute` | AI executes the strategy, generating a ChangeSet |
 | `apply` | ChangeSet is written to disk |
@@ -691,7 +695,8 @@ $ agents plan list --format json | jq '.data[] | select(.state == "errored") | .
 |---|---|
 | `queued` | Waiting to be processed |
 | `processing` | Currently being processed by an actor |
-| `complete` | Phase completed successfully |
+| `complete` | Phase completed successfully (Strategize/Execute phases) |
+| `constrained` | Apply cannot proceed within current constraints — may revert to Strategize |
 | `applied` | Changes written to disk (terminal) |
 | `cancelled` | Cancelled by user (terminal) |
 | `errored` | Failed with an error (recoverable via `plan resume`) |
@@ -772,7 +777,7 @@ $ agents plan use local/security-audit local/my-webapp \
 
 # 12. List all plans
 $ agents plan list
-# → Table: 3 plans + Summary panel
+# → Table: 2 plans + Summary panel
 
 # 13. Filter plans
 $ agents plan list --phase strategize
@@ -788,7 +793,7 @@ $ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json
 # → JSON envelope with full plan data
 
 # 16. Cancel a plan
-$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA
+$ agents plan cancel 01KNKJZ424C48388RWHW3KY5QZ
 # → ✓ Plan cancelled: local/architecture-review-01knkjz4
 ```
 </details>

docs/showcase/examples.json

@@ -68,29 +68,87 @@
       "educational_value": "high",
       "generated_by": "uat-tester",
       "generated_at": "2026-04-07"
+    },
+    {
+      "title": "Action & Plan Management: The v3 Plan Lifecycle",
+      "category": "cli-tools",
+      "path": "cli-tools/action-and-plan-management.md",
+      "feature": "Action management and plan lifecycle",
+      "commands": [
+        "agents action create --config examples/actions/simple.yaml",
+        "agents action list",
+        "agents action list --namespace local",
+        "agents action list --state available",
+        "agents action list \\".*audit.*\\"",
+        "agents action show local/security-audit",
+        "agents action show local/large-refactor --format json",
+        "agents action archive local/lint-check",
+        "agents action list --state archived",
+        "agents project create local/my-webapp",
+        "agents plan use local/architecture-review local/my-webapp",
+        "agents plan use local/security-audit local/my-webapp --arg severity_threshold=high --invariant \\"Never modify production data\\"",
+        "agents plan list",
+        "agents plan list --phase strategize",
+        "agents plan list --state queued",
+        "agents plan list --action local/security-audit",
+        "agents plan status <PLAN_ID>",
+        "agents plan status <PLAN_ID> --format json",
+        "agents plan cancel <PLAN_ID>"
+      ],
+      "complexity": "intermediate",
+      "educational_value": "high",
+      "generated_by": "uat-tester",
+      "generated_at": "2026-04-07"
     }
   ],
   "categories": {
     "cli-tools": {
       "name": "CLI Tools",
       "description": "Text-based command-line applications",
-      "keywords": ["CLI", "command-line", "terminal", "console", "tool"]
+      "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"]
+      "keywords": [
+        "API",
+        "REST",
+        "client",
+        "HTTP",
+        "web",
+        "request"
+      ]
     },
     "data-processing": {
       "name": "Data Processing",
       "description": "Tools for data analysis and transformation",
-      "keywords": ["data", "CSV", "JSON", "parser", "analyzer", "transform"]
+      "keywords": [
+        "data",
+        "CSV",
+        "JSON",
+        "parser",
+        "analyzer",
+        "transform"
+      ]
     },
     "testing-tools": {
       "name": "Testing Tools",
       "description": "Testing utilities and automation",
-      "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"]
+      "keywords": [
+        "test",
+        "pytest",
+        "behave",
+        "unittest",
+        "automation",
+        "QA"
+      ]
     }
   },
-  "last_updated": null
+  "last_updated": "2026-04-08"
 }