From e953333ad40e6a6e45921446795b21cb30378894 Mon Sep 17 00:00:00 2001
From: Lucas Berger <me@lucasberger.ca>
Date: Wed, 28 Jan 2026 16:36:43 -0500
Subject: [PATCH] chore: add initial planning documents and configuration

---
 .planning/ROADMAP.md  | 91 +++++++++++++++++++++++++++++++++++++++++++
 .planning/STATE.md    | 50 ++++++++++++++++++++++++
 .planning/config.json | 13 +++++++
 3 files changed, 154 insertions(+)
 create mode 100644 .planning/ROADMAP.md
 create mode 100644 .planning/STATE.md
 create mode 100644 .planning/config.json

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
new file mode 100644
index 0000000..bb34617
--- /dev/null
+++ b/.planning/ROADMAP.md
@@ -0,0 +1,91 @@
+# Roadmap — Unraid Docker Manager v1.0
+
+## Milestone: v1.0 — Conversational Docker Control
+
+### Phase 1: Foundation
+**Goal:** Basic Telegram ↔ n8n communication working
+
+- Set up n8n workflow with Telegram trigger
+- Configure Telegram bot via BotFather
+- Echo messages back to verify round-trip
+- Implement user ID verification (single-user auth)
+
+**Delivers:** REQ-01 (send/receive messages), REQ-09 (user ID auth)
+
+**Status:** 🔲 Not started
+
+---
+
+### Phase 2: Docker Integration
+**Goal:** n8n can query Docker and return container info
+
+- Connect n8n to Unraid Docker socket
+- Implement container listing endpoint
+- Parse container status (running, stopped, health)
+- Format status responses for Telegram
+
+**Delivers:** REQ-02 (container status queries)
+
+**Status:** 🔲 Not started
+
+---
+
+### Phase 3: Container Actions
+**Goal:** Control containers through conversation
+
+- Implement start container by name
+- Implement stop container by name
+- Implement restart container by name
+- Implement update container (pull + recreate)
+- Handle fuzzy name matching ("plex" → "plex-server")
+
+**Delivers:** REQ-03, REQ-04, REQ-05, REQ-06
+
+**Status:** 🔲 Not started
+
+---
+
+### Phase 4: Logs & Intelligence
+**Goal:** View logs and answer conversational questions
+
+- Implement log retrieval with configurable line count
+- Integrate Claude API for natural language understanding
+- Parse user intent from conversational messages
+- Implement resource queries ("what's using most memory?")
+
+**Delivers:** REQ-07 (logs), REQ-08 (conversational queries)
+
+**Status:** 🔲 Not started
+
+---
+
+### Phase 5: Polish & Deploy
+**Goal:** Production-ready deployment on Unraid
+
+- Error handling and user-friendly error messages
+- Create Docker container for any custom components
+- Write deployment instructions for Unraid
+- End-to-end testing of all scenarios
+
+**Delivers:** Production readiness
+
+**Status:** 🔲 Not started
+
+---
+
+## Requirements Mapping
+
+| REQ | Description | Phase |
+|-----|-------------|-------|
+| REQ-01 | Send/receive messages | 1 |
+| REQ-02 | Container status queries | 2 |
+| REQ-03 | Start container | 3 |
+| REQ-04 | Stop container | 3 |
+| REQ-05 | Restart container | 3 |
+| REQ-06 | Update container | 3 |
+| REQ-07 | View logs (configurable lines) | 4 |
+| REQ-08 | Conversational queries | 4 |
+| REQ-09 | User ID authentication | 1 |
+
+---
+*Created: 2026-01-28*
diff --git a/.planning/STATE.md b/.planning/STATE.md
new file mode 100644
index 0000000..f36be36
--- /dev/null
+++ b/.planning/STATE.md
@@ -0,0 +1,50 @@
+# Project State — Unraid Docker Manager
+
+## Project Reference
+
+**Building:** Conversational Telegram bot for Docker container management on Unraid
+**Core Value:** Investigate and control containers from your phone through natural conversation
+
+## Current Position
+
+- **Milestone:** v1.0 — Conversational Docker Control
+- **Phase:** 1 of 5 — Foundation
+- **Plan:** None created yet
+- **Status:** Ready to plan Phase 1
+
+## Progress
+
+```
+Phase 1: Foundation         🔲 Not started
+Phase 2: Docker Integration 🔲 Not started
+Phase 3: Container Actions  🔲 Not started
+Phase 4: Logs & Intelligence🔲 Not started
+Phase 5: Polish & Deploy    🔲 Not started
+
+Overall: [░░░░░░░░░░] 0%
+```
+
+## Recent Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| Use n8n for orchestration | Already running on Unraid, handles Telegram webhooks | 2026-01-28 |
+| Claude API for NLU | N100 can't run local LLMs fast enough | 2026-01-28 |
+| Single-user auth | Simple security, only owner needs access | 2026-01-28 |
+
+## Pending Todos
+
+(None yet)
+
+## Blockers & Concerns
+
+(None yet)
+
+## Session Continuity
+
+- **Last session:** 2026-01-28
+- **Stopped at:** Roadmap created, ready to plan Phase 1
+- **Resume file:** None
+
+---
+*Auto-maintained by GSD workflow*
diff --git a/.planning/config.json b/.planning/config.json
new file mode 100644
index 0000000..ef6f605
--- /dev/null
+++ b/.planning/config.json
@@ -0,0 +1,13 @@
+{
+  "workflow_mode": "interactive",
+  "agents": {
+    "researcher": true,
+    "plan_checker": true,
+    "verifier": true
+  },
+  "model_profile": "balanced",
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  }
+}