Incorporates 5 lessons from commit 216f3a4 into the plan:
- Connection keys/targets must use node names, not IDs
- HTTP auth must use Header Auth credential, not manual env vars
- Node names must be unique
- Use $('Node Name') after GraphQL chains, not $input.item.json
- Added validation checklist to verification section
Marks Task 2 as already completed (dead code removal done in hotfix).
Updates node counts from 193 to 181 baseline.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added IF node to check batch size (threshold: 5 containers)
- Small batches (<=5): use single updateContainers mutation (parallel, fast)
- Large batches (>5): use existing serial Execute Workflow loop
- Build Batch Update Mutation node constructs updateContainers GraphQL query
- Execute Batch Update with 120-second timeout for large image pulls
- Handle Batch Update Response maps results and updates Container ID Registry
- Format and send batch result via Telegram
- Both paths produce consistent result messaging
Workflow pushed to n8n successfully (HTTP 200).
- Migrated Get Container For Action to GraphQL
- Migrated Get Container For Cancel to GraphQL
- Migrated Get All Containers For Update All to GraphQL (with imageId)
- Migrated Fetch Containers For Update All Exec to GraphQL (with imageId)
- Migrated Get Container For Callback Update to GraphQL
- Migrated Fetch Containers For Bitmap Stop to GraphQL
Added 6 GraphQL Response Normalizer nodes and 6 Container ID Registry update nodes.
All nodes use $env.UNRAID_HOST and $env.UNRAID_API_KEY for authentication.
15-second timeout for myunraid.net cloud relay.
Workflow pushed to n8n successfully (HTTP 200).
- Add Build Start/Stop Mutation Code nodes to construct GraphQL queries
- Update Start/Stop Container HTTP nodes to POST to Unraid GraphQL API
- Add GraphQL Error Handler nodes after each mutation (maps ALREADY_IN_STATE to 304)
- Implement restart as sequential stop+start chain (no native restart mutation)
- Add Handle Stop-for-Restart Result node to tolerate 304 on stop step
- Wire: Route Action -> Build Mutation -> HTTP -> Error Handler -> Format Result
- Format Result nodes unchanged (zero-change migration for output formatting)
- Workflow pushed to n8n: HTTP 200
- Replace all 5 Docker API HTTP Request nodes with GraphQL queries
- Add 5 GraphQL Response Normalizer nodes (one per query path)
- Transform Unraid GraphQL responses to Docker API contract format
- Preserve all downstream Code nodes unchanged (bitmap encoding, keyboard building)
- All connection chains validated and working
- Pushed to n8n successfully (HTTP 200)
- Replace 'Get All Containers' Docker API call with GraphQL query
- Add GraphQL Response Normalizer to transform Unraid format to Docker contract
- Add Container ID Registry update on every container lookup
- Update Resolve Container ID to output unraidId (PrefixedID) for mutations
- Wire: Query All Containers -> Normalizer -> Registry Update -> Resolve Container ID
- Added 15-01-SUMMARY.md documenting implementation and deviations
- Updated STATE.md: Phase 15 complete (2/2 plans), 52 total plans, v1.4 at 20%
- Task 1 (Container ID Registry) was pre-existing in baseline
- Task 2 (Token Encoder/Decoder) implemented and pushed to n8n
- All utility nodes standalone, ready for Phase 16 wiring
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Callback Token Encoder: compress 129-char Unraid PrefixedID to 8-char hex token
- SHA-256 hashing with 7-window collision detection (56 chars / 8-char windows)
- Callback Token Decoder: resolve 8-char token back to PrefixedID
- Both use JSON serialization for static data persistence (_callbackTokens)
- Standalone utility nodes at [600,2400] and [1000,2400]
- Not connected - Phase 16 will wire into active flow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phases 15-18: Infrastructure Foundation, API Migration, Cleanup, Documentation
23 requirements mapped across 4 phases with 0 gaps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Unraid GraphQL API foundation — connectivity, authentication, and
container ID format verified for native Unraid API integration.
Phase 14: Unraid API Access (2 plans, 4 tasks)
- Established Unraid GraphQL API connectivity via myunraid.net cloud relay
- Dual credential storage (.env.unraid-api + n8n env vars)
- Container ID format: {server_hash}:{container_hash} (128-char SHA256 pair)
- Complete API contract documented in ARCHITECTURE.md
- "unraid" test command added to Telegram bot
Phases 15-16 dropped (superseded by v1.4 Unraid API Native).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Archive v1.2 Modularization & Polish milestone:
- Archive ROADMAP.md, REQUIREMENTS.md, and audit to milestones/
- Evolve PROJECT.md with v1.2 validated requirements and decisions
- Reorganize ROADMAP.md with collapsed milestone groupings
- Delete REQUIREMENTS.md (fresh for next milestone)
- Update STATE.md and MILESTONES.md
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- File written during Phase 10-05 for 3 sub-workflows (now 7)
- References 199 nodes (now 166 in main workflow)
- Fully superseded by DEPLOY-SUBWORKFLOWS.md (725 lines, current)
- README now links only to DEPLOY-SUBWORKFLOWS.md for technical details
- Remaining references in .planning/ are historical records (expected)
BATCH-04 and BATCH-05 UAT passed. 9 bugs fixed during testing.
All 12 v1.2 requirements now complete. Phase 13 (docs overhaul) next.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixes discovered during BATCH-04/BATCH-05 UAT testing:
- Convert confirmation to HTTP Request (editMessageText for inline kb,
sendMessage for text command) with dynamic endpoint selection
- Fix data chain breaks: use named node refs ($('Parse Callback Data'),
$('Get Update All Data')) instead of $json after API calls
- Add infrastructure container exclusion (n8n, socket-proxy) by image
and container name to prevent bot self-destruction during updates
- Add batch responseMode to update sub-workflow (skip Telegram messages)
- Reorder infra check before :latest filter so sha256-digest images
appear in skipped list
- Add onError:continueRegularOutput to Answer Update All Start for
expired callback queries
- Show "Back to List" button in batch summary for update-all flow
- Add Prepare Update All Batch fallback in Prepare Batch Loop
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add Known Limitations section to DEPLOY-SUBWORKFLOWS.md
- Document UNR-01: Unraid shows "apply update" after bot updates a container
- Explain root cause: bot bypasses Unraid's XML template system
- Provide workaround: click Apply Update in Unraid (instant, image cached)
- Clarify "Check for Updates" does NOT clear badge, may create new ones
- Mark UNR-01 as complete (documented limitation with workaround)
- Update README to document docker-socket-proxy architecture instead of direct socket mount
- Clarify TELEGRAM_BOT_TOKEN needs both n8n credential AND env var
- Clarify user ID is hardcoded in IF nodes (no env var needed)
- Add missing commands to usage table (update all, /list)
- Document all 8 workflow files (main + 7 sub-workflows)
- Mark ENV-01, ENV-02, DEBT-01, DEBT-02 as complete in REQUIREMENTS.md
- Verify DEBT-02 is fixed (single --max-time 600 flag, no duplicates)
Research found Unraid badge issue is architectural (bot bypasses
Unraid's XML template system). Updated plans to document limitation
with workaround instead of attempting programmatic fix. Plan 01
covers docs/env/debt, Plan 02 covers deferred Update All UAT.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
UAT results: tests 1-3,6 pass (bitmap, long names, batch exec, regression).
Tests 4-5 (Update All UAT) deferred to after Phase 12.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Is Bitmap Batch Stop and Resolve Batch Stop Names were checking $json.bitmap
which contains the Telegram API response, not the parsed callback data. Changed
both to reference $("Parse Callback Data").item.json directly.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Three bugs from plan 11-01 execution:
1. Parse Callback Data bstop return missing bitmap/isBitmapBatchStop fields
2. Is Bitmap Batch Stop wired to expired branch [0] instead of not-expired [1]
3. Is Bitmap Batch Stop false branch went to Initialize Batch State, bypassing Prepare Batch Stop Exec
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add 'Update All :latest' button to Build Container List and Build Paginated List
- Add uall:start parser to Parse Callback Data (sets isUpdateAllStart flag)
- Add updateallstart rule to Route Callback (index 2)
- Add Answer Update All Start node with 'Checking for updates...' callback response
- Wire Route Callback [updateallstart] -> Answer Update All Start -> Get All Containers For Update All
- Fix Check Available Updates to support both text and callback origins (try/catch for Keyword Router vs Parse Callback Data)
- Created 10.2-03-SUMMARY.md documenting scope reduction and platform limitation
- Updated STATE.md: Phase 10.2 complete (3/3 plans)
- Documented critical finding: n8n static data does not persist between executions
- Final state: 170 nodes (168 baseline + 2 correlation ID generators)
- Correlation ID infrastructure and structured error returns retained
n8n $getWorkflowStaticData only reliably tracks top-level property changes.
Deep nested mutations (staticData.errorLog.debug.enabled = true) are not
persisted between executions. Fix: serialize errorLog as JSON string in
staticData._errorLog — every read does JSON.parse, every write does
JSON.stringify as a top-level assignment.
Fixed in: Process Debug Command, Log Error, Log Trace, 6 inline trace
nodes, Parse Callback Data callback routing trace.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Plan 02 executor placed correlationId outside the json object in all
Prepare Input code nodes, creating "Unexpected token '}'" syntax errors.
Moved correlationId inside the json return object in all 19 affected nodes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two bugs: (1) connection array had old fallback at index [9] shifting debug
connections off-by-one, so /errors routed to Show Menu. (2) /debug status
matched rule 1 (contains "status") before rule 11 (startsWith /debug).
Fix: move startsWith debug rules [1-4] before contains rules [5-12].
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Part A - Correlation ID Generation:
- Added Generate Correlation ID node for text command path
- Added Generate Callback Correlation ID node for callback path
- Wired between authentication and routing nodes
- Uses timestamp + random string pattern (no external dependencies)
Part B - Correlation ID Propagation:
- Modified 19 Prepare Input nodes to pass correlationId to sub-workflows
- Uses $input.item.json.correlationId pattern for flexibility
- Supports both text and callback paths
Part C - Error Capture Infrastructure:
- Added 2 error detection IF nodes for high-value paths:
* Check Execute Container Action Success
* Check Execute Inline Action Success
- Error path: success === false → Log Error node
- Success path: continues to original result handling
- Log Error node receives error data from sub-workflows
- Pass-through design preserves data for downstream handlers
Main workflow: 172 → 176 nodes (+4)
- 2 correlation ID generators
- 2 error detection IF nodes
Error ring buffer now captures:
- Container action failures (Docker API errors)
- Sub-workflow errors with full diagnostic context
- Correlation IDs for request tracing
- Workflow name, node, HTTP codes, raw responses
- Create Log Error code node with ring buffer write logic
- Create Log Trace code node with debug mode check and auto-disable
- Both nodes implement ring buffer (max 50 entries) with auto-rotation
- Log Error: accepts error data, truncates large fields (stack 500, raw 1000)
- Log Error: passes through input data with _errorLogged flag
- Log Trace: checks debug.enabled before logging, passes through unchanged
- Log Trace: auto-disables debug mode after 100 executions
- Both nodes positioned at utility area (2600, -200/-400)
- Nodes are standalone (no connections) - ready for Plan 02 wiring
- Node count: 170 -> 172 (+2 utility nodes)
The list keyword rule was added to Keyword Router but its connection
pointed to Show Menu (fallback) instead of Prepare Status Input.
Added proper connection at index 8 and shifted fallback to index 9.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
