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

tests/Framework/Attributes/RouteAttributeTest.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+use App\Framework\Attributes\Route;
+use App\Framework\Http\Method;
+use App\Framework\Router\ValueObjects\Placeholder;
+use App\Framework\Router\ValueObjects\RoutePath;
+
+describe('Route Attribute', function () {
+    describe('string path support', function () {
+        it('works with traditional string paths', function () {
+            $route = new Route(path: '/api/users/{id}', method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/api/users/{id}');
+            expect($route->getRoutePath()->toString())->toBe('/api/users/{id}');
+            expect($route->getRoutePath()->isDynamic())->toBeTrue();
+        });
+
+        it('handles static string paths', function () {
+            $route = new Route(path: '/health', method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/health');
+            expect($route->getRoutePath()->isStatic())->toBeTrue();
+        });
+    });
+
+    describe('RoutePath object support', function () {
+        it('works with RoutePath objects', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'images',
+                Placeholder::fromString('filename')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/api/images/{filename}');
+            expect($route->getRoutePath())->toBe($routePath);
+        });
+
+        it('handles complex RoutePath objects', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'users',
+                Placeholder::typed('userId', 'uuid'),
+                'posts',
+                Placeholder::typed('postId', 'int')
+            );
+
+            $route = new Route(path: $routePath, method: Method::POST);
+
+            expect($route->getPathAsString())->toBe('/api/users/{userId}/posts/{postId}');
+            expect($route->method)->toBe(Method::POST);
+        });
+
+        it('handles wildcard parameters', function () {
+            $routePath = RoutePath::fromElements(
+                'files',
+                Placeholder::wildcard('path')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET);
+
+            expect($route->getPathAsString())->toBe('/files/{path*}');
+        });
+    });
+
+    describe('mixed usage compatibility', function () {
+        it('provides consistent interface regardless of input type', function () {
+            $stringRoute = new Route(path: '/api/users/{id}', method: Method::GET);
+            $objectRoute = new Route(
+                path: RoutePath::fromElements('api', 'users', Placeholder::fromString('id')),
+                method: Method::GET
+            );
+
+            expect($stringRoute->getPathAsString())->toBe($objectRoute->getPathAsString());
+            expect($stringRoute->getRoutePath()->toString())->toBe($objectRoute->getRoutePath()->toString());
+        });
+    });
+
+    describe('route compilation', function () {
+        it('compiles to CompiledRoute correctly', function () {
+            $routePath = RoutePath::fromElements(
+                'api',
+                'users',
+                Placeholder::typed('id', 'int')
+            );
+
+            $route = new Route(path: $routePath, method: Method::GET, name: 'users.show');
+
+            // Note: This test would need CompiledRoute to be available
+            // For now, we just test the path conversion
+            expect($route->getPathAsString())->toBe('/api/users/{id}');
+        });
+    });
+});