unraid-docker-manager/.planning/phases/01-foundation/01-01-PLAN.md

---
phase: 01-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - n8n-workflow.json
autonomous: false
user_setup:
  - service: telegram
    why: "Bot token required for n8n Telegram integration"
    account_setup:
      - task: "Create Telegram bot"
        location: "Telegram app -> @BotFather"
        steps:
          - "Open Telegram, search for @BotFather"
          - "Send /newbot"
          - "Choose a name (e.g., 'Unraid Docker Manager')"
          - "Choose a username (must end with 'bot', e.g., 'unraid_docker_bot')"
          - "Copy the API token provided"
    env_vars:
      - name: TELEGRAM_BOT_TOKEN
        source: "BotFather response after /newbot"
      - name: TELEGRAM_USER_ID
        source: "Send any message to @userinfobot to get your Telegram user ID"

must_haves:
  truths:
    - "User can send a message to the Telegram bot"
    - "Bot responds only to authorized user ID"
    - "Unauthorized users receive no response (silent ignore)"
    - "Echo response includes original message and timestamp"
  artifacts:
    - path: "n8n-workflow.json"
      provides: "Complete n8n workflow definition"
      contains: "Telegram Trigger"
  key_links:
    - from: "Telegram Trigger node"
      to: "IF node"
      via: "message.from.id check"
      pattern: "from.id"
    - from: "IF node (true branch)"
      to: "Code node"
      via: "authenticated flow"
    - from: "Code node"
      to: "Telegram Send node"
      via: "echo message"
---

<objective>
Create the n8n workflow that receives Telegram messages, authenticates the user, and echoes messages back with timestamp.

Purpose: Establish the foundation for all bot communication - prove the Telegram <-> n8n round-trip works before adding Docker features.
Output: Working n8n workflow that echoes messages back to the authorized user.
</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/01-foundation/01-CONTEXT.md
@.planning/phases/01-foundation/01-RESEARCH.md
</context>

<tasks>

<task type="checkpoint:human-action" gate="blocking">
  <name>Task 1: Create Telegram Bot and Configure n8n</name>
  <action>
User must complete external setup before workflow can be created:

1. **Create Telegram Bot:**
   - Open Telegram, search for @BotFather
   - Send `/newbot`
   - Follow prompts for name (e.g., "Unraid Docker Manager")
   - Choose username ending with 'bot' (e.g., "unraid_docker_bot")
   - Save the API token provided

2. **Get Your Telegram User ID:**
   - In Telegram, search for @userinfobot
   - Send any message
   - Note your "Id" value (numeric)

3. **Configure n8n Environment Variables:**
   - Add to n8n container environment:
     - `TELEGRAM_BOT_TOKEN=<your-bot-token>`
     - `TELEGRAM_USER_ID=<your-user-id>`
   - Restart n8n container if needed

4. **Create Telegram Credential in n8n:**
   - n8n UI -> Credentials -> Add -> Telegram API
   - Paste bot token in "Access Token" field
   - Save credential
  </action>
  <resume-signal>Type "done" when Telegram bot is created and n8n credential is configured</resume-signal>
</task>

<task type="auto">
  <name>Task 2: Create n8n Workflow for Telegram Echo</name>
  <files>n8n-workflow.json</files>
  <action>
Create an n8n workflow JSON file with the following structure:

**Workflow: "Docker Manager Bot"**

**Node 1: Telegram Trigger**
- Type: n8n-nodes-base.telegramTrigger
- Updates: "message"
- Use the Telegram API credential

**Node 2: IF (User Authentication)**
- Type: n8n-nodes-base.if
- Condition: `{{ $json.message.from.id.toString() }}` equals `{{ $env.TELEGRAM_USER_ID }}`
- True branch continues to echo
- False branch: no connected nodes (silent ignore)

**Node 3: Code (Format Echo)**
- Type: n8n-nodes-base.code
- JavaScript code:
```javascript
const message = $input.item.json.message;
const timestamp = new Date().toISOString();
const text = message.text || '(no text)';

return {
  json: {
    chatId: message.chat.id,
    text: `Got: ${text}\n\nProcessed: ${timestamp}`
  }
};
```

**Node 4: Telegram (Send Message)**
- Type: n8n-nodes-base.telegram
- Resource: message
- Operation: sendMessage
- Chat ID: `={{ $json.chatId }}`
- Text: `={{ $json.text }}`
- Parse Mode: HTML (for future formatting)

**Connections:**
- Telegram Trigger -> IF
- IF (true) -> Code
- Code -> Telegram Send
- IF (false) -> (nothing, ends workflow)

Save as `n8n-workflow.json` in the project root. This file can be imported into n8n.

**Important:** The workflow JSON should be valid for n8n import. Include proper node positions for visual layout.
  </action>
  <verify>
- File `n8n-workflow.json` exists
- JSON is valid (parse without errors)
- Contains all 4 nodes: telegramTrigger, if, code, telegram
- IF condition references `$env.TELEGRAM_USER_ID`
  </verify>
  <done>
- n8n workflow JSON file created and valid
- All nodes properly connected
- User ID authentication configured via environment variable
  </done>
</task>

</tasks>

<verification>
1. Workflow JSON file exists at project root
2. JSON parses without errors
3. All required nodes present with correct types
4. IF node checks user ID from environment variable
5. Code node includes timestamp in output
</verification>

<success_criteria>
- n8n-workflow.json exists and is valid JSON
- Workflow includes Telegram Trigger, IF (auth), Code (echo), Telegram Send
- Authentication uses environment variable for user ID
- Silent ignore implemented (no nodes on false branch)
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
</output>