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/Core/Events/AfterControllerExecution.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Http\Response;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Core\ValueObjects\ClassName;
+use App\Framework\Core\ValueObjects\MethodName;
+
+final readonly class AfterControllerExecution
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public Response $response,
+        public ClassName $controllerClass,
+        public MethodName $methodName,
+        public Duration $executionTime,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}

src/Framework/Core/Events/AfterEmitResponse.php

@@ -4,6 +4,22 @@ declare(strict_types=1);
 
 namespace App\Framework\Core\Events;
 
+use App\Framework\Http\Request;
+use App\Framework\Http\Response;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\Duration;
+
 final readonly class AfterEmitResponse
 {
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public Response $response,
+        public Duration $totalProcessingTime,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
 }

src/Framework/Core/Events/AfterHandleRequest.php

@@ -4,6 +4,22 @@ declare(strict_types=1);
 
 namespace App\Framework\Core\Events;
 
+use App\Framework\Http\Request;
+use App\Framework\Http\Response;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\Duration;
+
 final readonly class AfterHandleRequest
 {
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public Response $response,
+        public Duration $processingTime,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
 }

src/Framework/Core/Events/AfterMiddlewareExecution.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Http\Response;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Core\ValueObjects\ClassName;
+
+final readonly class AfterMiddlewareExecution
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public Response $response,
+        public ClassName $middlewareClass,
+        public Duration $executionTime,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}

src/Framework/Core/Events/AfterRouteMatching.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\Duration;
+
+final readonly class AfterRouteMatching
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public ?string $routeName,
+        public array $routeParameters,
+        public Duration $matchingTime,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}

src/Framework/Core/Events/BeforeControllerExecution.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\ClassName;
+use App\Framework\Core\ValueObjects\MethodName;
+
+final readonly class BeforeControllerExecution
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public ClassName $controllerClass,
+        public MethodName $methodName,
+        public array $parameters,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}

src/Framework/Core/Events/BeforeEmitResponse.php

@@ -4,6 +4,20 @@ declare(strict_types=1);
 
 namespace App\Framework\Core\Events;
 
+use App\Framework\Http\Request;
+use App\Framework\Http\Response;
+use App\Framework\Core\ValueObjects\Timestamp;
+
 final readonly class BeforeEmitResponse
 {
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public Response $response,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
 }

src/Framework/Core/Events/BeforeHandleRequest.php

@@ -4,6 +4,18 @@ declare(strict_types=1);
 
 namespace App\Framework\Core\Events;
 
+use App\Framework\Http\Request;
+use App\Framework\Core\ValueObjects\Timestamp;
+
 final readonly class BeforeHandleRequest
 {
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
 }

src/Framework/Core/Events/BeforeMiddlewareExecution.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Core\ValueObjects\ClassName;
+
+final readonly class BeforeMiddlewareExecution
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        public ClassName $middlewareClass,
+        public int $priority,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}

src/Framework/Core/Events/BeforeRouteMatching.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Core\Events;
+
+use App\Framework\Http\Request;
+use App\Framework\Core\ValueObjects\Timestamp;
+
+final readonly class BeforeRouteMatching
+{
+    public readonly Timestamp $timestamp;
+
+    public function __construct(
+        public Request $request,
+        ?Timestamp $timestamp = null,
+        public array $context = []
+    ) {
+        $this->timestamp = $timestamp ?? Timestamp::now();
+    }
+}