unraid-docker-manager/.planning/phases/08-inline-keyboard-infrastructure/08-03-PLAN.md

---
phase: 08-inline-keyboard-infrastructure
plan: 03
type: execute
wave: 3
depends_on: [08-02]
files_modified: [n8n-workflow.json]
autonomous: false

must_haves:
  truths:
    - "After action completes, message shows result with 'Back to menu' button"
    - "Buttons are removed from completed action messages"
    - "Update operations show progress message during execution"
    - "Full keyboard flow works end-to-end"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Completion message handlers"
      contains: "Show Action Result"
    - path: "n8n-workflow.json"
      provides: "Progress feedback for updates"
      contains: "Show Update Progress"
  key_links:
    - from: "container operation nodes"
      to: "Show Action Result"
      via: "completion flow"
      pattern: "editMessageText"
    - from: "Update Container flow"
      to: "Show Update Progress"
      via: "progress message"
      pattern: "Updating"
---

<objective>
Add progress feedback during operations and completion messages after actions finish.

Purpose: Users see visual feedback during operations ("Updating plex...") and final results ("plex updated") with a button to return to the menu. This completes the inline keyboard UX.

Output: Updated n8n-workflow.json with progress and completion handlers, plus full end-to-end verification.
</objective>

<execution_context>
@/home/luc/.claude/get-shit-done/workflows/execute-plan.md
@/home/luc/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/08-inline-keyboard-infrastructure/08-CONTEXT.md
@.planning/phases/08-inline-keyboard-infrastructure/08-RESEARCH.md
@.planning/phases/08-inline-keyboard-infrastructure/08-01-SUMMARY.md
@.planning/phases/08-inline-keyboard-infrastructure/08-02-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add Completion Messages for Quick Actions</name>
  <files>n8n-workflow.json</files>
  <action>
Add completion handlers that show results and "Back to menu" button after actions.

Per user decision: Quick actions (start, stop, restart) show final result only, not progress.

1. Create Code node "Build Action Success" that:
   - Takes action result and context (chatId, messageId, containerName, actionType)
   - Builds completion message based on action type
   - Includes "Back to menu" button
   - Removes action buttons (keyboard has only navigation)

   ```javascript
   const { chatId, messageId, containerName, actionType } = $json;

   // Build success message based on action
   const messages = {
     start: `▶️ <b>${containerName}</b> started`,
     stop: `⏹️ <b>${containerName}</b> stopped`,
     restart: `🔄 <b>${containerName}</b> restarted`
   };

   const text = messages[actionType] || `Action completed on ${containerName}`;

   const keyboard = {
     inline_keyboard: [
       [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
     ]
   };

   return {
     json: {
       chatId,
       messageId,
       text,
       reply_markup: keyboard
     }
   };
   ```

2. Create HTTP Request node "Show Action Result":
   - Method: POST
   - URL: editMessageText endpoint
   - Body: chat_id, message_id, text, parse_mode, reply_markup

3. Wire completion after each action:
   - Start Container -> Build Action Success (with actionType='start') -> Show Action Result
   - Stop Container -> Build Action Success (with actionType='stop') -> Show Action Result
   - Restart Container -> Build Action Success (with actionType='restart') -> Show Action Result

4. Handle action failures:
   - Create Code node "Build Action Error":
     ```javascript
     const { chatId, messageId, containerName, actionType, error } = $json;

     const text = `❌ Failed to ${actionType} <b>${containerName}</b>\n\n${error || 'Unknown error'}`;

     const keyboard = {
       inline_keyboard: [
         [{ text: '🔄 Try Again', callback_data: `action:${actionType}:${containerName}` }],
         [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
       ]
     };

     return { json: { chatId, messageId, text, reply_markup: keyboard } };
     ```
   - Wire error outputs from container operations to error handler
  </action>
  <verify>
    1. Start a stopped container via button
    2. Verify: After start completes, message shows "plex started" with "Back to Containers" button
    3. Stop a running container (confirm when prompted)
    4. Verify: Shows "plex stopped" with back button
    5. Restart a container
    6. Verify: Shows "plex restarted" with back button
    7. Tap "Back to Containers"
    8. Verify: Returns to container list
  </verify>
  <done>
    - Start shows completion message with back button
    - Stop shows completion message with back button
    - Restart shows completion message with back button
    - Errors show retry and back buttons
    - Action buttons removed after completion (only back button remains)
  </done>
</task>

<task type="auto">
  <name>Task 2: Add Progress Feedback for Update Operations</name>
  <files>n8n-workflow.json</files>
  <action>
Add progress message for update operations (longer running than start/stop/restart).

Per user decision: Updates show progress (simple status, not detailed steps).

1. Create Code node "Build Update Progress" that shows in-progress state:
   ```javascript
   const { chatId, messageId, containerName } = $json;

   return {
     json: {
       chatId,
       messageId,
       text: `⬆️ <b>Updating ${containerName}...</b>\n\nPulling latest image and recreating container.\nThis may take a few minutes.`,
       reply_markup: { inline_keyboard: [] } // Remove buttons during update
     }
   };
   ```

2. Create HTTP Request "Show Update Progress":
   - editMessageText with progress message
   - Removes all buttons during operation

3. Wire update flow:
   - Route Confirmed Action (update) -> Answer Callback -> Build Update Progress -> Show Update Progress -> existing Update Container flow

4. Create Code node "Build Update Success":
   ```javascript
   const { chatId, messageId, containerName } = $json;

   const keyboard = {
     inline_keyboard: [
       [{ text: '◀️ Back to Containers', callback_data: 'list:0' }]
     ]
   };

   return {
     json: {
       chatId,
       messageId,
       text: `✅ <b>${containerName}</b> updated successfully`,
       reply_markup: keyboard
     }
   };
   ```

5. Wire update completion:
   - After Update Container completes -> Build Update Success -> Show Action Result

6. Handle update errors:
   - Wire error path to Build Action Error with appropriate context
  </action>
  <verify>
    1. Start update on a container (confirm when prompted)
    2. Verify: Message immediately changes to "Updating plex..." with no buttons
    3. Wait for update to complete
    4. Verify: Message changes to "plex updated successfully" with back button
    5. If update fails, verify error message appears with retry option
  </verify>
  <done>
    - Update shows progress message during execution
    - Buttons removed during update (prevents duplicate actions)
    - Success message shown after update completes
    - Error message with retry button if update fails
  </done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 3: Full End-to-End Verification</name>
  <what-built>
    Complete inline keyboard infrastructure:
    - Container list with tappable buttons
    - Container submenu with action buttons
    - Confirmation dialogs for dangerous actions
    - Progress feedback for updates
    - Completion messages with navigation
  </what-built>
  <how-to-verify>
    **Flow 1: Basic Navigation**
    1. Send "/status" to bot
    2. Verify: Inline keyboard appears with container list
    3. Tap a container name
    4. Verify: Message edits to show container details and action buttons
    5. Tap "Back to List"
    6. Verify: Returns to container list

    **Flow 2: Start Container**
    1. From container list, tap a STOPPED container
    2. Tap "Start" button
    3. Verify: Container starts, message shows "started" with back button
    4. Tap "Back to Containers"
    5. Verify: Returns to list, container now shows as Running

    **Flow 3: Stop Container (with confirmation)**
    1. Tap a RUNNING container
    2. Tap "Stop" button
    3. Verify: Confirmation dialog appears "Stop container? Yes / No"
    4. Tap "Cancel"
    5. Verify: Returns to container submenu (not list)
    6. Tap "Stop" again
    7. Tap "Yes, Stop"
    8. Verify: Container stops, message shows "stopped" with back button

    **Flow 4: Update Container (with progress)**
    1. Tap a container
    2. Tap "Update" button
    3. Verify: Confirmation dialog appears
    4. Tap "Yes, Update"
    5. Verify: Message shows "Updating..." with no buttons
    6. Wait for completion
    7. Verify: Message shows "updated successfully" with back button

    **Flow 5: Confirmation Timeout**
    1. Tap a container, tap "Stop"
    2. Wait 35 seconds
    3. Tap "Yes, Stop"
    4. Verify: Shows "Confirmation expired" message

    **Flow 6: Direct Access**
    1. Send "/status plex" (or another container name)
    2. Verify: Jumps directly to that container's submenu

    **Flow 7: Pagination (if applicable)**
    1. If you have >6 containers, verify pagination buttons work
    2. If not, verify no pagination buttons appear
  </how-to-verify>
  <resume-signal>Type "approved" to mark Phase 8 complete, or describe any issues found</resume-signal>
</task>

</tasks>

<verification>
After completing all tasks:
1. All KEY-01 through KEY-05 requirements met
2. Full navigation flow works (list -> submenu -> action -> result -> list)
3. Confirmations work with timeout
4. Progress shown for updates
5. Buttons removed after action completion
6. No hanging loading indicators anywhere
7. Direct access (/status name) works
</verification>

<success_criteria>
- KEY-01: Status command shows container list with inline action buttons
- KEY-02: Tapping action button performs start/stop/restart on container
- KEY-03: Dangerous actions (stop, update) show confirmation dialog
- KEY-04: Progress shown via message edit during operations
- KEY-05: Buttons removed after action completes (only back button remains)
</success_criteria>

<output>
After completion, create `.planning/phases/08-inline-keyboard-infrastructure/08-03-SUMMARY.md`
</output>