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/Discovery/Storage/DiscoveryCacheManager.php

@@ -26,6 +26,7 @@ use App\Framework\Discovery\ValueObjects\DiscoveryContext;
 use App\Framework\Filesystem\FilePath;
 use App\Framework\Filesystem\FileSystemService;
 use App\Framework\Logging\Logger;
+use App\Framework\Logging\ValueObjects\LogContext;
 
 /**
  * Enhanced Discovery cache manager with memory-aware and tiered caching strategies
@@ -85,10 +86,10 @@ final class DiscoveryCacheManager
 
         $cached = $this->processRetrievedData($item->value);
         if (! $cached instanceof DiscoveryRegistry) {
-            $this->logger?->warning('Invalid cache data type', [
+            $this->logger?->warning('Invalid cache data type', LogContext::withData([
                 'key' => $key->toString(),
                 'type' => gettype($cached),
-            ]);
+            ]));
             $this->emitCacheMissEvent($key->toString(), 'corrupted');
 
             return null;
@@ -96,9 +97,9 @@ final class DiscoveryCacheManager
 
         // Validate cache freshness
         if ($this->isStale($context, $cached)) {
-            $this->logger?->info('Discovery cache is stale', [
+            $this->logger?->info('Discovery cache is stale', LogContext::withData([
                 'key' => $key->toString(),
-            ]);
+            ]));
             $this->invalidate($context);
             $this->emitCacheMissEvent($key->toString(), 'expired');
 
@@ -160,7 +161,7 @@ final class DiscoveryCacheManager
             $this->updateCacheMetrics($key->toString(), $dataSize, $cacheLevel, 'store');
             $this->trackAccess($key->toString());
 
-            $this->logger?->info('Discovery results cached with memory awareness', [
+            $this->logger?->info('Discovery results cached with memory awareness', LogContext::withData([
                 'key' => $key->toString(),
                 'items' => count($registry),
                 'cache_level' => $cacheLevel->value,
@@ -168,7 +169,7 @@ final class DiscoveryCacheManager
                 'memory_pressure' => $memoryStatus->memoryPressure->toDecimal(),
                 'data_size' => $dataSize->toHumanReadable(),
                 'ttl' => $adjustedTtl->toHours(),
-            ]);
+            ]));
         }
 
         return $success;
@@ -191,11 +192,11 @@ final class DiscoveryCacheManager
         $success = $this->cache->set($cacheItem);
 
         if ($success) {
-            $this->logger?->info('Discovery results cached (standard)', [
+            $this->logger?->info('Discovery results cached (standard)', LogContext::withData([
                 'key' => $key->toString(),
                 'items' => count($registry),
                 'ttl' => $ttl->toHours(),
-            ]);
+            ]));
         }
 
         return $success;

src/Framework/Discovery/Storage/DiscoveryStorage.php

@@ -1,70 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace App\Framework\Discovery\Storage;
-
-use App\Framework\Filesystem\FileMetadata;
-use App\Framework\Filesystem\Storage;
-use SplFileInfo;
-
-/**
- * Spezialisiertes Storage-Interface für Discovery-Operationen
- * Erweitert das Standard-Storage-Interface mit Discovery-spezifischen Methoden
- */
-interface DiscoveryStorage extends Storage
-{
-    /**
-     * Findet geänderte Dateien seit dem letzten Scan
-     *
-     * @param string $directory Zu durchsuchendes Verzeichnis
-     * @param array<string, array> $fileMetadata Vorhandene Metadaten [path => metadata]
-     * @return array<SplFileInfo> Liste geänderter Dateien
-     */
-    public function findChangedFiles(string $directory, array $fileMetadata): array;
-
-    /**
-     * Führt einen inkrementellen Scan durch
-     *
-     * @param string $directory Zu durchsuchendes Verzeichnis
-     * @param array<string, array> $fileMetadata Vorhandene Metadaten [path => metadata]
-     * @return array<string, array> Aktualisierte Metadaten [path => metadata]
-     */
-    public function incrementalScan(string $directory, array $fileMetadata): array;
-
-    /**
-     * Findet alle Dateien mit einem bestimmten Muster
-     *
-     * @param string $directory Zu durchsuchendes Verzeichnis
-     * @param string $pattern Suchmuster (z.B. '*.php')
-     * @return array<SplFileInfo> Liste gefundener Dateien
-     */
-    public function findFiles(string $directory, string $pattern): array;
-
-    /**
-     * Erstellt Metadaten für eine Datei
-     *
-     * @param string $filePath Pfad zur Datei
-     * @param bool $calculateChecksum Ob eine Prüfsumme berechnet werden soll
-     * @return FileMetadata Metadaten der Datei
-     */
-    public function getDiscoveryMetadata(string $filePath, bool $calculateChecksum = true): FileMetadata;
-
-    /**
-     * Erstellt Metadaten für mehrere Dateien parallel
-     *
-     * @param array<string> $filePaths Liste von Dateipfaden
-     * @param bool $calculateChecksum Ob Prüfsummen berechnet werden sollen
-     * @return array<string, FileMetadata> Metadaten [path => metadata]
-     */
-    public function getDiscoveryMetadataMultiple(array $filePaths, bool $calculateChecksum = true): array;
-
-    /**
-     * Registriert Dateisystem-Events für Änderungserkennung
-     *
-     * @param string $directory Zu überwachendes Verzeichnis
-     * @param callable $callback Callback-Funktion für Events (string $path, string $event)
-     * @return bool Erfolg der Registrierung
-     */
-    public function registerFileSystemEvents(string $directory, callable $callback): bool;
-}

src/Framework/Discovery/Storage/DiscoveryStorageService.php

@@ -0,0 +1,180 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Framework\Discovery\Storage;
+
+use App\Framework\Core\PathProvider;
+use App\Framework\Core\ValueObjects\Timestamp;
+use App\Framework\Discovery\Results\AttributeRegistry;
+use App\Framework\Discovery\Results\InterfaceRegistry;
+use App\Framework\Discovery\Results\TemplateRegistry;
+use App\Framework\Filesystem\Directory;
+use App\Framework\Filesystem\FilePath;
+use App\Framework\Filesystem\FileStorage;
+
+/**
+ * Storage for pre-discovered data using Filesystem module
+ *
+ * Stores discovery results as PHP files for fast loading at runtime
+ */
+final readonly class DiscoveryStorageService
+{
+    private Directory $storageDir;
+    private FileStorage $storage;
+
+    public function __construct(PathProvider $pathProvider)
+    {
+        $this->storage = new FileStorage($pathProvider->getBasePath());
+        $storagePath = $pathProvider->getBasePath() . '/storage/discovery';
+        
+        $this->storageDir = new Directory($storagePath, $this->storage);
+        
+        if (!$this->storageDir->exists()) {
+            $this->storageDir->create();
+        }
+    }
+
+    /**
+     * Store attributes registry
+     */
+    public function storeAttributes(AttributeRegistry $registry): void
+    {
+        $data = $registry->toArray();
+        $this->writePhpFile('attributes', $data);
+    }
+
+    /**
+     * Load attributes registry
+     */
+    public function loadAttributes(): ?AttributeRegistry
+    {
+        $data = $this->readPhpFile('attributes');
+
+        if ($data === null) {
+            return null;
+        }
+
+        return AttributeRegistry::fromArray($data);
+    }
+
+    /**
+     * Store templates registry
+     */
+    public function storeTemplates(TemplateRegistry $registry): void
+    {
+        $data = $registry->toArray();
+        $this->writePhpFile('templates', $data);
+    }
+
+    /**
+     * Load templates registry
+     */
+    public function loadTemplates(): ?TemplateRegistry
+    {
+        $data = $this->readPhpFile('templates');
+
+        if ($data === null) {
+            return null;
+        }
+
+        return TemplateRegistry::fromArray($data);
+    }
+
+    /**
+     * Store interfaces registry
+     */
+    public function storeInterfaces(InterfaceRegistry $registry): void
+    {
+        $data = $registry->toArray();
+        $this->writePhpFile('interfaces', $data);
+    }
+
+    /**
+     * Load interfaces registry
+     */
+    public function loadInterfaces(): ?InterfaceRegistry
+    {
+        $data = $this->readPhpFile('interfaces');
+
+        if ($data === null) {
+            return null;
+        }
+
+        return InterfaceRegistry::fromArray($data);
+    }
+
+    /**
+     * Get last modification time for a storage type
+     */
+    public function getLastModified(string $type): ?Timestamp
+    {
+        $filePath = $this->getFilePath($type);
+
+        if (!$this->storage->exists($filePath->toString())) {
+            return null;
+        }
+
+        $metadata = $this->storage->getMetadata($filePath->toString());
+        
+        return Timestamp::fromInt((int)$metadata->modifiedAt->format('U'));
+    }
+
+    /**
+     * Check if storage exists for a type
+     */
+    public function exists(string $type): bool
+    {
+        return $this->storage->exists($this->getFilePath($type)->toString());
+    }
+
+    /**
+     * Clear all discovery storage
+     */
+    public function clear(): void
+    {
+        $files = $this->storageDir->getFiles();
+
+        foreach ($files as $file) {
+            $this->storage->delete($file->getPath()->toString());
+        }
+    }
+
+    /**
+     * Write data as serialized PHP file for fast loading
+     */
+    private function writePhpFile(string $type, array $data): void
+    {
+        $filePath = $this->getFilePath($type);
+
+        // Use serialize instead of var_export to handle Value Objects
+        $serialized = serialize($data);
+        $phpCode = "<?php\n\nreturn unserialize(" . var_export($serialized, true) . ");\n";
+
+        $this->storage->put($filePath->toString(), $phpCode);
+    }
+
+    /**
+     * Read PHP file data
+     */
+    private function readPhpFile(string $type): ?array
+    {
+        $filePath = $this->getFilePath($type);
+
+        if (!$this->storage->exists($filePath->toString())) {
+            return null;
+        }
+
+        $data = require $filePath->toString();
+
+        return is_array($data) ? $data : null;
+    }
+
+    /**
+     * Get file path for storage type
+     */
+    private function getFilePath(string $type): FilePath
+    {
+        return FilePath::create($this->storageDir->getPathString() . '/' . $type . '.php');
+    }
+}