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/RouteCompiler.php

@@ -9,6 +9,7 @@ use App\Framework\Discovery\ValueObjects\DiscoveredAttribute;
 use App\Framework\Router\CompiledPattern;
 use App\Framework\Router\CompiledRoutes;
 use App\Framework\Router\RouteData;
+use App\Framework\Router\RouteNameInterface;
 use App\Framework\Router\ValueObjects\MethodParameter;
 use App\Framework\Router\ValueObjects\ParameterCollection;
 use App\Framework\Router\ValueObjects\SubdomainPattern;
@@ -36,8 +37,8 @@ final readonly class RouteCompiler
 
             // Extract route data directly from the Route attribute
             $method = strtoupper($routeAttribute->method->value);
-            $path = $routeAttribute->path;
-            $routeName = $routeAttribute->name;
+            $path = $routeAttribute->getPathAsString();
+            $routeName = $this->extractRouteName($routeAttribute->name);
 
             // Process subdomain patterns
             $subdomainPatterns = SubdomainPattern::fromInput($routeAttribute->subdomain);
@@ -211,15 +212,21 @@ final readonly class RouteCompiler
                 $pattern = $this->stripAnchors($route->regex);
                 $patterns[] = "({$pattern})";
 
-                // Route-Gruppe Index merken
-                $routeGroupIndex = $currentIndex++;
+                // This route's main capture group index
+                $routeGroupIndex = $currentIndex;
 
-                // Parameter-Mapping berechnen
+                // Parameter-Mapping berechnen - parameters are INSIDE the route pattern
+                // So their indices are routeGroupIndex + 1, routeGroupIndex + 2, etc.
                 $paramMap = [];
+                $paramOffset = 1; // Parameters start right after the route's capture group
                 foreach ($route->paramNames as $paramName) {
-                    $paramMap[$paramName] = $currentIndex++;
+                    $paramMap[$paramName] = $routeGroupIndex + $paramOffset++;
                 }
 
+                // Now advance currentIndex past ALL capture groups in this route's pattern
+                // That's 1 (the route group) + count(paramNames) (the parameters inside it)
+                $currentIndex += 1 + count($route->paramNames);
+
                 $routeData[$globalIndex] = new RouteData(
                     route: $route,
                     paramMap: $paramMap,
@@ -313,4 +320,16 @@ final readonly class RouteCompiler
 
         return $regex;
     }
+
+    /**
+     * Extract route name as string from enum or string
+     */
+    private function extractRouteName(RouteNameInterface|string|null $routeName): string
+    {
+        if ($routeName instanceof RouteNameInterface) {
+            return $routeName->value;
+        }
+
+        return (string) ($routeName ?? '');
+    }
 }