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/DI/DefaultContainer.php

@@ -7,6 +7,7 @@ namespace App\Framework\DI;
 use App\Framework\Core\ValueObjects\ClassName;
 use App\Framework\DI\Exceptions\CyclicDependencyException;
 use App\Framework\DI\Exceptions\LazyLoadingException;
+use App\Framework\Metrics\FrameworkMetricsCollector;
 use App\Framework\Reflection\CachedReflectionProvider;
 use App\Framework\Reflection\ReflectionProvider;
 use Throwable;
@@ -23,6 +24,8 @@ final class DefaultContainer implements Container
     private readonly LazyInstantiator $lazyInstantiator;
 
     public readonly MethodInvoker $invoker;
+    public readonly ContainerIntrospector $introspector;
+    public readonly FrameworkMetricsCollector $metrics;
 
     public function __construct(
         private readonly InstanceRegistry $instances = new InstanceRegistry(),
@@ -36,6 +39,14 @@ final class DefaultContainer implements Container
             $this->createInstance(...)
         );
         $this->invoker = new MethodInvoker($this, $this->reflectionProvider);
+        $this->introspector = new ContainerIntrospector(
+            $this,
+            $this->instances,
+            $this->bindings,
+            $this->reflectionProvider,
+            fn(): array => $this->resolving
+        );
+        $this->metrics = new FrameworkMetricsCollector();
 
         $this->registerSelf();
         $this->instance(ReflectionProvider::class, $this->reflectionProvider);
@@ -61,24 +72,26 @@ final class DefaultContainer implements Container
     /**
      * @inheritDoc
      */
-    public function get(string $class): object
+    public function get(string|ClassName $class): object
     {
+        $className = $class instanceof ClassName ? $class->toString() : $class;
+
         // Bereits instanziierte Objekte zurückgeben
-        if ($this->instances->hasSingleton($class)) {
-            $singleton = $this->instances->getSingleton($class);
+        if ($this->instances->hasSingleton($className)) {
+            $singleton = $this->instances->getSingleton($className);
             if ($singleton !== null) {
                 return $singleton;
             }
         }
 
-        if ($this->instances->hasInstance($class)) {
-            return $this->instances->getInstance($class);
+        if ($this->instances->hasInstance($className)) {
+            return $this->instances->getInstance($className);
         }
 
         // Lazy Loading versuchen
-        if ($this->lazyInstantiator->canUseLazyLoading($class, $this->instances)) {
+        if ($this->lazyInstantiator->canUseLazyLoading($className, $this->instances)) {
             try {
-                return $this->lazyInstantiator->createLazyInstance($class);
+                return $this->lazyInstantiator->createLazyInstance($className);
             } catch (Throwable $e) {
                 if (! $e instanceof LazyLoadingException) {
                     throw $e;
@@ -86,7 +99,7 @@ final class DefaultContainer implements Container
             }
         }
 
-        return $this->createInstance($class);
+        return $this->createInstance($className);
     }
 
     /**
@@ -115,6 +128,10 @@ final class DefaultContainer implements Container
             }
 
             return $instance;
+        } catch (Throwable $e) {
+            // Track resolution failures
+            $this->metrics->increment('container.resolve.failures');
+            throw $e;
         } finally {
             array_pop($this->resolving);
         }
@@ -130,20 +147,21 @@ final class DefaultContainer implements Container
         // Enhanced diagnostics for missing bindings
         try {
             $reflection = $this->reflectionProvider->getClass($className);
-            
+
             // Check if class is instantiable using framework's method
-            if (!$reflection->isInstantiable()) {
+            if (! $reflection->isInstantiable()) {
                 $this->throwDetailedBindingException($class, $reflection);
             }
 
             $dependencies = $this->dependencyResolver->resolveDependencies($className);
+
             return $reflection->newInstance(...$dependencies->toArray());
         } catch (\RuntimeException $e) {
             // If it's already our detailed exception, just re-throw
             if (str_contains($e->getMessage(), 'Dependency resolution chain:')) {
                 throw $e;
             }
-            
+
             // Otherwise, wrap with binding information
             throw new \RuntimeException(
                 "Cannot resolve class '{$class}': {$e->getMessage()}. " .
@@ -167,22 +185,22 @@ final class DefaultContainer implements Container
     {
         $availableBindings = array_keys($this->bindings->getAllBindings());
         $dependencyChain = implode(' -> ', $this->resolving);
-        
+
         // Look for similar interface bindings
-        $similarBindings = array_filter($availableBindings, function($binding) use ($class) {
+        $similarBindings = array_filter($availableBindings, function ($binding) use ($class) {
             return str_contains($binding, basename(str_replace('\\', '/', $class)));
         });
-        
+
         $message = "Cannot instantiate class '{$class}': class is not instantiable (interface, abstract class, or trait).\n" .
                    "Dependency resolution chain: {$dependencyChain}\n" .
                    "Total available bindings: " . count($availableBindings) . "\n";
-        
-        if (!empty($similarBindings)) {
+
+        if (! empty($similarBindings)) {
             $message .= "Similar bindings found: " . implode(', ', $similarBindings) . "\n";
         }
-        
+
         $message .= "All bindings: " . implode(', ', $availableBindings);
-        
+
         throw new \RuntimeException($message);
     }