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/MagicLinks/Services/InMemoryMagicLinkService.php

@@ -2,16 +2,17 @@
 
 declare(strict_types=1);
 
-namespace App\Framework\Smartlinks\Services;
+namespace App\Framework\MagicLinks\Services;
 
 use App\Framework\DateTime\Clock;
-use App\Framework\Smartlinks\SmartlinkData;
-use App\Framework\Smartlinks\SmartLinkToken;
-use App\Framework\Smartlinks\TokenAction;
-use App\Framework\Smartlinks\TokenConfig;
+use App\Framework\MagicLinks\MagicLinkData;
+use App\Framework\MagicLinks\MagicLinkToken;
+use App\Framework\MagicLinks\TokenAction;
+use App\Framework\MagicLinks\TokenConfig;
+use App\Framework\MagicLinks\ValueObjects\MagicLinkPayload;
 use App\Framework\Ulid\UlidGenerator;
 
-final class InMemorySmartLinkService implements SmartlinkService
+final class InMemoryMagicLinkService implements MagicLinkService
 {
     private array $tokens = [];
 
@@ -27,16 +28,16 @@ final class InMemorySmartLinkService implements SmartlinkService
         ?TokenConfig            $config = null,
         ?string                 $createdByIp = null,
         ?string                 $userAgent = null
-    ): SmartlinkToken {
+    ): MagicLinkToken {
         $config ??= new TokenConfig();
         $id = $this->ulidGenerator->generate($this->clock);
         ;
         $now = new \DateTimeImmutable();
 
-        $smartlinkData = new SmartlinkData(
+        $magiclinkData = new MagicLinkData(
             id: $id,
             action: $action,
-            payload: $payload,
+            payload: MagicLinkPayload::fromArray($payload),
             expiresAt: $config->getExpiryDateTime(),
             createdAt: $now,
             oneTimeUse: $config->oneTimeUse,
@@ -44,13 +45,13 @@ final class InMemorySmartLinkService implements SmartlinkService
             userAgent: $userAgent
         );
 
-        $token = new SmartlinkToken($id);
-        $this->tokens[$id] = $smartlinkData;
+        $token = new MagicLinkToken($id);
+        $this->tokens[$id] = $magiclinkData;
 
         return $token;
     }
 
-    public function validate(SmartlinkToken $token): ?SmartlinkData
+    public function validate(MagicLinkToken $token): ?MagicLinkData
     {
         if (! isset($this->tokens[$token->value])) {
             return null;
@@ -65,7 +66,7 @@ final class InMemorySmartLinkService implements SmartlinkService
         return $data;
     }
 
-    public function markAsUsed(SmartlinkToken $token): void
+    public function markAsUsed(MagicLinkToken $token): void
     {
         if (isset($this->tokens[$token->value])) {
             $data = $this->tokens[$token->value];
@@ -73,12 +74,12 @@ final class InMemorySmartLinkService implements SmartlinkService
         }
     }
 
-    public function revoke(SmartlinkToken $token): void
+    public function revoke(MagicLinkToken $token): void
     {
         unset($this->tokens[$token->value]);
     }
 
-    public function exists(SmartlinkToken $token): bool
+    public function exists(MagicLinkToken $token): bool
     {
         return isset($this->tokens[$token->value]) &&
             $this->tokens[$token->value]->isValid();