Create comprehensive PowerShell threading documentation and patterns

� PERMANENT THREADING KNOWLEDGE BASE:

✅ CREATED COMPREHENSIVE DOCUMENTATION:
  • docs/POWERSHELL-THREADING-RULES.md - Complete threading guide
  • Enhanced ThreadSafeProgressCollector with usage examples
  • Added to project structure documentation
  • Saved to AI memory for future reference

� CRITICAL RULES DOCUMENTED:
  • PowerShell cmdlets can ONLY call Write-* methods from main thread
  • Background threads must QUEUE updates, never call Write-* directly
  • ProcessQueuedUpdates() must ONLY be called from main thread
  • Common mistakes and error symptoms clearly identified

� DESIGN PATTERNS PROVIDED:
  • Periodic processing pattern (every 1 second)
  • Completion-based processing pattern
  • Manual processing points pattern
  • Correct Task.WaitAll usage with timeouts

� IMPLEMENTATION CHECKLIST:
  • Pre-implementation checklist for new cmdlets
  • Debugging tips and error identification
  • Code examples for correct and incorrect patterns
  • Testing guidelines for threading compliance

� PREVENTS FUTURE REGRESSIONS:
  • Clear documentation of the 'golden rule'
  • Examples of common threading violations
  • Patterns for all background operation types
  • Reference for all future PowerShell module development

This ensures we never repeat the same threading mistakes!

src/Utils/ThreadSafeProgressCollector.cs

@@ -8,6 +8,21 @@ namespace PSMinIO.Utils
     /// <summary>
     /// Thread-safe progress data collector that accumulates progress updates from background threads
     /// and allows the main thread to safely report them to PowerShell
+    ///
+    /// CRITICAL THREADING RULE:
+    /// PowerShell cmdlets can ONLY call Write-Progress, Write-Verbose, Write-Object, Write-Error
+    /// from the main cmdlet thread - NEVER from background threads!
+    ///
+    /// USAGE PATTERN:
+    /// - Background threads: Call QueueProgressUpdate(), QueueVerboseMessage() (thread-safe)
+    /// - Main thread ONLY: Call ProcessQueuedUpdates() to display queued updates
+    ///
+    /// EXAMPLE:
+    /// Task.Run(() => {
+    ///     collector.QueueProgressUpdate(1, "Processing", "Status", 50); // ✅ Safe
+    ///     // WriteProgress(...); // ❌ THREADING ERROR!
+    /// });
+    /// collector.ProcessQueuedUpdates(); // ✅ Only from main thread
     /// </summary>
     public class ThreadSafeProgressCollector
     {