docs: define milestone v1.4 requirements

.planning/PROJECT.md

@@ -56,11 +56,12 @@ When you get a container update notification or notice a service is down, you ca
 **Goal:** Replace Docker socket proxy with Unraid's GraphQL API for all container operations, remove all proxy artifacts, and update documentation.
 
 **Target features:**
-- All container operations via Unraid GraphQL API (status, start, stop, restart, update, logs)
+- All container operations via Unraid GraphQL API (status, start, stop, restart, update)
-- Remove docker-socket-proxy references from workflows, credentials, and n8n container config
+- Remove container logs feature (not valuable enough to justify hybrid architecture)
-- Clean up all proxy-related artifacts (nodes, variables, network references)
+- Remove docker-socket-proxy container entirely (no hybrid architecture)
+- Remove all proxy-related artifacts from workflows, credentials, n8n container config
 - Documentation fully updated for Unraid API-native architecture (README, ARCHITECTURE.md, CLAUDE.md)
-- Migration/cleanup instructions for removing the proxy container
+- Cleanup instructions for removing the proxy container
 
 ### Out of Scope
 
@@ -70,6 +71,8 @@ When you get a container update notification or notice a service is down, you ca
 - Proactive monitoring/notifications — bot is reactive (you ask, it answers)
 - Offline mode — real-time Docker API access is core to functionality
 - Ring buffer / persistent debug logging — n8n static data is execution-scoped, not workflow-scoped
+- Container logs via Telegram bot — removed in v1.4 to eliminate hybrid architecture (Docker proxy + Unraid API); not valuable enough to justify complexity
+- Real-time container stats — requires WebSocket infrastructure, defer to future
 
 ## Current State
 
@@ -132,6 +135,8 @@ When you get a container update notification or notice a service is down, you ca
 | myunraid.net cloud relay for Unraid API | Direct LAN IP fails (nginx strips auth headers on redirect) | ✓ Good |
 | Environment variables for Unraid API auth | More reliable than n8n Header Auth credential system for GraphQL | ✓ Good |
 | Descope v1.3 to Phase 14 only | Phases 15-16 superseded by v1.4 Unraid API Native approach | ✓ Good |
+| Remove container logs feature in v1.4 | Not valuable enough to justify hybrid architecture (Docker proxy for logs + Unraid API for everything else) | — Pending |
+| Remove docker-socket-proxy entirely | Clean single-API architecture, no hybrid routing complexity | — Pending |
 
 ---
 *Last updated: 2026-02-09 after v1.4 milestone started*

.planning/REQUIREMENTS.md

@@ -0,0 +1,110 @@
+# Requirements: Unraid Docker Manager
+
+**Defined:** 2026-02-09
+**Core Value:** When you get a container update notification or notice a service is down, you can immediately investigate and act from your phone.
+
+## v1.4 Requirements
+
+Requirements for v1.4 Unraid API Native milestone. Each maps to roadmap phases.
+
+### API Migration
+
+- [ ] **API-01**: Container status query works via Unraid GraphQL API (replaces Docker REST API)
+- [ ] **API-02**: Container start works via Unraid GraphQL mutation
+- [ ] **API-03**: Container stop works via Unraid GraphQL mutation
+- [ ] **API-04**: Container restart works via sequential stop+start GraphQL mutations (no native restart)
+- [ ] **API-05**: Container update works via single `updateContainer` GraphQL mutation (replaces 5-step Docker flow)
+- [ ] **API-06**: Batch container update works via `updateContainers` GraphQL mutation
+- [ ] **API-07**: "Update all :latest" works via Unraid GraphQL API with :latest filtering
+- [ ] **API-08**: Unraid update badges clear automatically after bot-initiated updates (no manual sync)
+
+### Infrastructure
+
+- [ ] **INFRA-01**: Container ID translation layer maps names to Unraid PrefixedID format (129-char `server_hash:container_hash`)
+- [ ] **INFRA-02**: Callback data encoding works with Unraid PrefixedIDs within Telegram's 64-byte limit
+- [ ] **INFRA-03**: GraphQL response normalization transforms Unraid API responses to match workflow contracts
+- [ ] **INFRA-04**: GraphQL error handling standardized (check `response.errors[]`, handle HTTP 304 "already in state")
+- [ ] **INFRA-05**: Timeout configuration accounts for myunraid.net cloud relay latency (200-500ms per request)
+
+### Cleanup
+
+- [ ] **CLN-01**: Docker socket proxy references removed from all workflow JSON files
+- [ ] **CLN-02**: Container logs feature removed from workflows (text command, inline keyboard, sub-workflow)
+- [ ] **CLN-03**: n8n-logs.json sub-workflow removed or emptied
+- [ ] **CLN-04**: docker-socket-proxy container can be safely removed (no remaining dependencies)
+- [ ] **CLN-05**: n8n container config cleaned (remove proxy network, socket-related env vars)
+- [ ] **CLN-06**: "unraid" test command updated or removed (v1.3 connectivity test)
+
+### Documentation
+
+- [ ] **DOC-01**: README.md updated to reflect Unraid API-native architecture (remove proxy references)
+- [ ] **DOC-02**: ARCHITECTURE.md updated with Unraid GraphQL API contracts and patterns
+- [ ] **DOC-03**: CLAUDE.md updated with new API patterns and removed proxy recipes
+- [ ] **DOC-04**: Cleanup instructions documented for removing docker-socket-proxy container
+
+## Future Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Container Logs (Removed in v1.4)
+
+- **LOGS-01**: Container logs via Unraid GraphQL API (if API adds logs support in future)
+- **LOGS-02**: Container logs via SSH fallback (alternative to Docker socket proxy)
+
+### Advanced Features
+
+- **ADV-01**: Real-time container stats via GraphQL subscription
+- **ADV-02**: Container autostart configuration via bot
+- **ADV-03**: Port conflict detection and reporting
+- **ADV-04**: Direct LAN fallback if myunraid.net relay unavailable
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Container logs via Telegram | Removed in v1.4 — not valuable enough to justify hybrid architecture (Docker proxy + Unraid API) |
+| GraphQL subscriptions (WebSocket) | Requires infrastructure n8n doesn't natively support, high complexity for low value |
+| Dual API support (Docker + Unraid) | No hybrid architecture — single API simplifies maintenance and debugging |
+| New container deployment | Manage existing only, deployment rarely needed from mobile |
+| Natural language understanding | Simple keyword matching works, Claude API adds unnecessary complexity |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| INFRA-01 | — | Pending |
+| INFRA-02 | — | Pending |
+| INFRA-03 | — | Pending |
+| INFRA-04 | — | Pending |
+| INFRA-05 | — | Pending |
+| API-01 | — | Pending |
+| API-02 | — | Pending |
+| API-03 | — | Pending |
+| API-04 | — | Pending |
+| API-05 | — | Pending |
+| API-06 | — | Pending |
+| API-07 | — | Pending |
+| API-08 | — | Pending |
+| CLN-01 | — | Pending |
+| CLN-02 | — | Pending |
+| CLN-03 | — | Pending |
+| CLN-04 | — | Pending |
+| CLN-05 | — | Pending |
+| CLN-06 | — | Pending |
+| DOC-01 | — | Pending |
+| DOC-02 | — | Pending |
+| DOC-03 | — | Pending |
+| DOC-04 | — | Pending |
+
+**Coverage:**
+- v1.4 requirements: 23 total
+- Mapped to phases: 0
+- Unmapped: 23 ⚠️
+
+---
+*Requirements defined: 2026-02-09*
+*Last updated: 2026-02-09 after initial definition*