docs: add delay/yield/looptask/IDLE guidance to cpp.instructions.md and esp-idf.instructions.md

Agent-Logs-Url: https://github.com/MoonModules/WLED-MM/sessions/e6fa4128-6712-4700-b716-3c5194ca2286

Co-authored-by: softhack007 <91616163+softhack007@users.noreply.github.com>

Author: Copilot

.github/cpp.instructions.md

@@ -449,6 +449,44 @@ Always pair every `esp32SemTake` with a matching `esp32SemGive`. Choose a timeou
 
 **Important**: Not every shared resource needs a mutex. Some synchronization is guaranteed by the overall control flow. For example, `volatile bool` flags like `suspendStripService`, `doInitBusses`, `loadLedmap`, and `OTAisRunning` (declared in `wled.h`) are checked sequentially in the main loop (`wled.cpp`), so they serialize access without requiring a semaphore. Use mutexes when true concurrent access from multiple FreeRTOS tasks is possible and race-conditions can lead to unexpected behaviour. Rely on control-flow ordering when operations are sequenced within the same loop iteration.
 
+### `delay()` vs `yield()` in FreeRTOS Tasks
+
+On ESP32, `delay(ms)` calls `vTaskDelay(ms / portTICK_PERIOD_MS)`, which **suspends only the calling task**. The FreeRTOS scheduler immediately runs all other ready tasks. This differs from ESP8266, where `delay()` stalled the entire system unless `yield()` was called inside.
+
+**`delay()` in `loopTask` is acceptable.** The Arduino `loop()` function runs inside `loopTask`. Calling `delay()` there does not block the network stack, audio FFT, LED DMA, or any other FreeRTOS task.
+
+**`yield()` is a no-op in WLED-MM on ESP32.** `WLEDMM_FASTPATH` redefines `yield()` to an empty macro:
+
+```cpp
+#define yield() {}  // WLEDMM: yield() is completely unnecessary on ESP32
+```
+
+Even in stock arduino-esp32, `yield()` calls `vTaskDelay(0)`, which only switches to tasks at equal or higher priority — the IDLE task (priority 0) is never reached. Do not use `yield()` to pace ESP32 tasks or assume it feeds any watchdog.
+
+**Custom `xTaskCreate()` tasks must call `delay(1)` in their loop, not `yield()`.** Without a real blocking call, the IDLE task is starved and the IDLE watchdog may panic:
+
+```cpp
+// WRONG — IDLE task is never scheduled; yield() is a no-op in WLEDMM_FASTPATH
+void myTask(void*) {
+  for (;;) {
+    doWork();
+    yield();
+  }
+}
+
+// CORRECT — delay(1) suspends the task for ≥1 ms, IDLE task runs, IDLE watchdog is fed
+void myTask(void*) {
+  for (;;) {
+    doWork();
+    delay(1);  // DO NOT REMOVE — lets IDLE(0) run and feeds its watchdog
+  }
+}
+```
+
+Prefer blocking FreeRTOS primitives (`xQueueReceive`, `ulTaskNotifyTake`, `vTaskDelayUntil`) over `delay(1)` polling where precise timing or event-driven behaviour is needed.
+
+**Watchdog note.** WLED-MM disables the Task Watchdog by default (`WLED_WATCHDOG_TIMEOUT 0` in `wled.h`). When enabled, `esp_task_wdt_reset()` is called at the end of each `loop()` iteration. Long blocking operations inside `loop()` — such as OTA downloads or slow file I/O — must call `esp_task_wdt_reset()` periodically, or be restructured so the main loop is not blocked for longer than the configured timeout.
+
 ## General
 
 - Follow the existing style in the file you are editing

.github/esp-idf.instructions.md

@@ -682,6 +682,21 @@ Guidelines:
   #endif
   ```
 
+### `delay()`, `yield()`, and the IDLE task
+
+FreeRTOS on ESP32 is **preemptive** — all tasks are scheduled by priority regardless of `yield()` calls. This is fundamentally different from ESP8266 cooperative multitasking.
+
+| Call | What it does | Reaches IDLE (priority 0)? |
+|---|---|---|
+| `delay(ms)` / `vTaskDelay(ticks)` | Suspends calling task; scheduler runs all other ready tasks | ✅ Yes |
+| `yield()` / `vTaskDelay(0)` | Hint to switch to tasks at **equal or higher** priority only | ❌ No |
+| `taskYIELD()` | Same as `vTaskDelay(0)` | ❌ No |
+| Blocking API (`xQueueReceive`, `ulTaskNotifyTake`, `vTaskDelayUntil`) | Suspends task until event or timeout; IDLE runs freely | ✅ Yes |
+
+**`delay()` in `loopTask` is safe.** Arduino's `loop()` runs inside `loopTask`. Calling `delay()` suspends only `loopTask` — all other FreeRTOS tasks (Wi-Fi stack, audio FFT, LED DMA) continue uninterrupted on either core.
+
+**`yield()` does not yield to IDLE.** Any task that loops with only `yield()` calls will starve the IDLE task, causing the IDLE watchdog to fire. Always use `delay(1)` (or a blocking FreeRTOS call) in tight task loops. Note: WLED-MM redefines `yield()` as an empty macro on ESP32 WLEDMM_FASTPATH builds — see `cpp.instructions.md`.
+
 ### Watchdog management
 
 Long-running operations may trigger the task watchdog. Feed it explicitly: