docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

src/Framework/Http/Parser/HttpRequestParser.php

@@ -175,15 +175,26 @@ final readonly class HttpRequestParser
 
         if (in_array($method, ['POST', 'PUT', 'PATCH'])) {
             if (str_contains($contentType, 'multipart/form-data')) {
+                error_log("HttpRequestParser: Detected multipart/form-data");
+                error_log("HttpRequestParser: rawBody length = " . strlen($rawBody));
+                error_log("HttpRequestParser: \$_POST count = " . count($_POST));
+                error_log("HttpRequestParser: \$_FILES count = " . count($_FILES));
+
                 // For multipart/form-data, PHP automatically populates $_POST and $_FILES
-                // and makes php://input empty. Use $_POST directly in this case.
-                if (strlen($rawBody) === 0 && ! empty($_POST)) {
+                // and makes php://input empty. Use $_POST and $_FILES directly in this case.
+                if (strlen($rawBody) === 0 && (! empty($_POST) || ! empty($_FILES))) {
                     error_log("HttpRequestParser: Using \$_POST fallback for multipart/form-data");
+                    error_log("HttpRequestParser: \$_POST = " . json_encode($_POST));
+                    error_log("HttpRequestParser: \$_FILES = " . json_encode($_FILES));
+                    error_log("HttpRequestParser: \$_FILES empty? " . (empty($_FILES) ? 'YES' : 'NO'));
                     $parsedBody = $_POST;
 
                     // Also handle $_FILES if available
                     if (! empty($_FILES)) {
-                        $uploadedFiles = $this->fileParser->parseFromFilesSuperglobal($_FILES);
+                        error_log("HttpRequestParser: Creating UploadedFiles from \$_FILES");
+                        $uploadedFiles = UploadedFiles::fromFilesArray($_FILES);
+                    } else {
+                        error_log("HttpRequestParser: \$_FILES is empty, using empty UploadedFiles");
                     }
                 } else {
                     // Extract boundary