unraid-docker-manager/.planning/phases/05-polish-deploy/05-02-PLAN.md

---
phase: 05-polish-deploy
plan: 02
type: execute
wave: 2
depends_on: [05-01]
files_modified: [n8n-workflow.json]
autonomous: true

must_haves:
  truths:
    - "Docker socket errors show 'Cannot connect to Docker' (not stack trace)"
    - "Failed actions show 'Failed to X' format (not verbose details)"
    - "User ID stored in n8n credentials (not hardcoded in workflow JSON)"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Terse error messages in response nodes"
      contains: "Cannot connect to Docker"
    - path: "n8n-workflow.json"
      provides: "Credential reference for user auth"
      contains: "$credentials"
  key_links:
    - from: "IF User Authenticated"
      to: "n8n credentials"
      via: "credential reference expression"
      pattern: "\\$credentials"
---

<objective>
Harden error handling with minimal user-facing messages and migrate user ID to n8n credentials system.

Purpose: Production-ready error UX and secure credential storage for workflow sharing.
Output: Terse error messages, credential-based auth, exportable workflow without sensitive data.
</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/05-polish-deploy/05-CONTEXT.md
@.planning/phases/05-polish-deploy/05-RESEARCH.md
@.planning/phases/05-polish-deploy/05-01-SUMMARY.md
@n8n-workflow.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Standardize error messages</name>
  <files>n8n-workflow.json</files>
  <action>
Find all error response nodes and update their message text to follow minimal format:

**Docker/infrastructure errors (detect "docker.sock" or "ECONNREFUSED" in error):**
- Message: "Cannot connect to Docker"

**Action failures:**
- Pattern: "Failed to {action} {container}"
- Examples: "Failed to start plex", "Failed to stop nginx"

**No match errors:**
- Keep existing "No container matching 'X'" format (already terse)

Update these nodes to use terse format:
- Send Docker Error -> "Cannot connect to Docker"
- Send Action Result (error case) -> "Failed to {action} {container}"
- Send Update Error -> "Failed to update {container}"
- Send Logs Error -> "Failed to get logs for {container}"

Do NOT include:
- Stack traces
- HTTP status codes
- Docker API error details
- Technical debugging info

Per CONTEXT.md: "Minimal error messages - 'Failed to start plex' without verbose details"
  </action>
  <verify>
Grep workflow JSON for error messages - should be terse, no technical details.
Manually test by stopping n8n's Docker socket access and sending command - should see "Cannot connect to Docker".
  </verify>
  <done>
All user-facing error messages follow terse format.
Infrastructure errors show "Cannot connect to Docker".
Action errors show "Failed to X Y" pattern.
  </done>
</task>

<task type="auto">
  <name>Task 2: Migrate user ID to n8n credentials</name>
  <files>n8n-workflow.json</files>
  <action>
Currently the workflow has hardcoded user ID in IF nodes for auth check. Per CONTEXT.md and RESEARCH.md, migrate to n8n credentials system.

**Step 1: Create credential type reference in workflow**

n8n credentials will be created manually by user during deployment, but workflow must reference them.

**Step 2: Update auth check nodes**

Find "IF User Authenticated" and "IF Callback Authenticated" nodes.

Change the condition from hardcoded ID comparison to credential reference:
```
// Old (hardcoded):
$json.message.from.id === 123456789

// New (credential reference):
$json.message.from.id === parseInt($credentials.telegramAuth.userId)
```

Note: The credential name "telegramAuth" with field "userId" follows RESEARCH.md pattern.
User will create this credential during deployment (documented in README from Plan 03).

**Step 3: Clean up sensitive data**

Search workflow JSON for any hardcoded numeric IDs that look like Telegram user IDs (8+ digit numbers).
Remove or replace with credential references.

Per CONTEXT.md: "Sensitive values (Telegram user ID) moved to n8n credentials system - not hardcoded in workflow JSON"
  </action>
  <verify>
Grep workflow JSON for 8+ digit numbers - should find none (except node position coordinates).
Auth check nodes should reference $credentials.telegramAuth.userId.
  </verify>
  <done>
No hardcoded user ID in workflow JSON.
Auth nodes use credential reference.
Workflow can be safely exported/shared.
  </done>
</task>

</tasks>

<verification>
1. All error messages terse (no stack traces, no verbose details)
2. Docker socket errors produce "Cannot connect to Docker"
3. Action failures produce "Failed to X Y" format
4. No hardcoded Telegram user ID in workflow JSON
5. Auth nodes reference $credentials.telegramAuth.userId
6. Workflow exports cleanly without embedded secrets
</verification>

<success_criteria>
- Error messages fit in single Telegram line (no scrolling needed)
- Zero hardcoded sensitive values in workflow JSON
- grep -E '[0-9]{9,}' workflow.json returns only position coordinates
</success_criteria>

<output>
After completion, create `.planning/phases/05-polish-deploy/05-02-SUMMARY.md`
</output>