diff --git a/.claude/instructions.md b/.claude/instructions.md
new file mode 100644
index 0000000..5fa22fd
--- /dev/null
+++ b/.claude/instructions.md
@@ -0,0 +1,56 @@
+# Project Instructions — Unraid Docker Manager
+
+## n8n API Integration
+
+This project can deploy workflows directly to n8n via API.
+
+**Credentials:** `.env.n8n-api` in project root (gitignored)
+```bash
+N8N_HOST=https://your-n8n-instance.com
+N8N_API_KEY=your-api-key
+```
+
+**Workflow IDs:**
+| Workflow | ID | File |
+|----------|-----|------|
+| Docker Manager Bot (main) | `HmiXBlJefBRPMS0m4iNYc` | `n8n-workflow.json` |
+| Container Update | `7AvTzLtKXM2hZTio92_mC` | `n8n-container-update.json` |
+| Container Actions | `fYSZS5PkH0VSEaT5` | `n8n-container-actions.json` |
+| Container Logs | `oE7aO2GhbksXDEIw` | `n8n-container-logs.json` |
+
+**Push workflow to n8n:**
+```bash
+# Load credentials
+source .env.n8n-api
+
+# Extract allowed fields and push (n8n API rejects extra fields)
+jq '{name, nodes, connections, settings}' n8n-workflow.json > /tmp/update.json
+curl -X PUT "$N8N_HOST/api/v1/workflows/<ID>" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d @/tmp/update.json
+```
+
+**List workflows:**
+```bash
+source .env.n8n-api
+curl -s "$N8N_HOST/api/v1/workflows" -H "X-N8N-API-KEY: $N8N_API_KEY" | jq '.data[] | {id, name}'
+```
+
+## Technical Patterns
+
+**n8n data chain pattern:**
+- Use `$('NodeName').item.json` to reference data across async nodes
+- Don't rely on `$json` after Telegram/HTTP nodes (response overwrites data)
+
+**n8n workflow JSON for API:**
+- API PUT rejects extra fields like `active`, `triggerCount`, `tags`, `pinData`, `staticData`
+- Filter to only: `name`, `nodes`, `connections`, `settings`
+
+**Container ID resolution:**
+- Keyboard callbacks only pass container names (64-byte limit)
+- Sub-workflows resolve name → ID via Docker API when containerId is empty
+
+## GSD Workflow
+
+Using `/gsd:*` commands for structured development. See `.planning/` for roadmap and state.