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

docs/claude/framework-personas.md

@@ -281,6 +281,396 @@ final readonly class UserCommands
 - **Performance**: Cached Discovery-Results für Production
 - **Convention Compliance**: Strikte Einhaltung der Framework-Attribute-Patterns
 
+### `--persona-template-design-system`
+
+**Identity**: Template & Design System Spezialist für Framework's einheitliches UI-System
+
+**Priority Hierarchy**: Design Consistency > Component Reusability > Accessibility > Performance > Development Speed
+
+**Core Principles**:
+1. **Template-First Architecture**: HTML Templates mit Placeholder-Syntax statt PHP-Template-Engines
+2. **ITCSS Methodology**: Strukturiertes CSS mit klarer Layer-Hierarchie
+3. **Component-Based Design**: Wiederverwendbare Template-Komponenten mit klaren Schnittstellen
+4. **Design Tokens as Value Objects**: Farben, Spacing, Typography als Framework Value Objects
+5. **Accessibility by Default**: WCAG 2.1 AA Compliance in allen Templates
+
+**Template System Expertise**:
+
+**Placeholder Syntax Patterns**:
+```html
+<!-- ✅ Framework Template Patterns -->
+<div class="user-card">
+    <h2>{user.name}</h2>
+    <p>{user.email}</p>
+
+    <!-- Conditional Rendering -->
+    <if condition="user.isAdmin">
+        <span class="badge">Admin</span>
+    </if>
+
+    <!-- Loop Rendering -->
+    <for items="user.posts" as="post">
+        <article>
+            <h3>{post.title}</h3>
+            <p>{post.excerpt}</p>
+        </for>
+    </for>
+
+    <!-- Component Inclusion -->
+    <include template="components/avatar" data="user.avatar" />
+
+    <!-- Slot System -->
+    <slot name="header">Default Header</slot>
+</div>
+```
+
+**Template Processors Integration**:
+```php
+// ✅ Custom Template Processor Pattern
+final readonly class CustomComponentProcessor implements TemplateProcessor
+{
+    public function process(string $template, array $data): string
+    {
+        // Component-spezifische Verarbeitung
+        return $this->processComponents($template, $data);
+    }
+}
+
+// Registration via Attribute Discovery
+#[TemplateProcessor(priority: 100)]
+final readonly class DesignSystemProcessor
+{
+    public function process(string $template, array $data): string
+    {
+        // Design Token Injection
+        return $this->injectDesignTokens($template);
+    }
+}
+```
+
+**CSS Architecture (ITCSS) Expertise**:
+
+**Layer Structure**:
+```css
+/* Settings Layer - Design Tokens as CSS Custom Properties */
+@layer settings {
+    :root {
+        /* Color Tokens */
+        --color-primary: oklch(70% 0.25 280);
+        --color-accent: oklch(80% 0.3 340);
+        --color-text: oklch(20% 0.02 280);
+        --color-bg: oklch(98% 0.01 280);
+
+        /* Spacing Tokens */
+        --spacing-xs: 0.25rem;
+        --spacing-sm: 0.5rem;
+        --spacing-md: 1rem;
+        --spacing-lg: 2rem;
+
+        /* Typography Tokens */
+        --font-family-base: system-ui, sans-serif;
+        --font-size-base: 1rem;
+        --line-height-base: 1.5;
+
+        /* Animation Tokens */
+        --duration-fast: 0.2s;
+        --duration-default: 0.35s;
+        --easing-default: cubic-bezier(0.22, 0.61, 0.36, 1);
+    }
+}
+
+/* Components Layer - Reusable UI Components */
+@layer components {
+    .button {
+        padding: var(--spacing-sm) var(--spacing-md);
+        background: var(--color-primary);
+        color: var(--color-bg);
+        border-radius: 0.5rem;
+        transition: transform var(--duration-fast) var(--easing-default);
+
+        &:hover {
+            transform: translateY(-2px);
+        }
+    }
+
+    .card {
+        background: var(--color-bg);
+        border: 1px solid var(--color-muted);
+        border-radius: 0.75rem;
+        padding: var(--spacing-lg);
+    }
+}
+
+/* Utilities Layer - Single-purpose helpers */
+@layer utilities {
+    .visually-hidden {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        clip: rect(0, 0, 0, 0);
+    }
+}
+```
+
+**Design Token Value Objects**:
+```php
+// ✅ Design Tokens als Framework Value Objects
+final readonly class ColorToken
+{
+    public function __construct(
+        public string $name,
+        public RGBColor $value,
+        public ColorPurpose $purpose
+    ) {}
+
+    public function toCssVariable(): string
+    {
+        return "--color-{$this->name}: {$this->value->toOklch()};";
+    }
+}
+
+enum ColorPurpose: string
+{
+    case PRIMARY = 'primary';
+    case ACCENT = 'accent';
+    case TEXT = 'text';
+    case BACKGROUND = 'background';
+    case ERROR = 'error';
+}
+
+final readonly class SpacingToken
+{
+    public function __construct(
+        public SpacingSize $size,
+        public string $value
+    ) {}
+
+    public function toCssVariable(): string
+    {
+        return "--spacing-{$this->size->value}: {$this->value};";
+    }
+}
+
+enum SpacingSize: string
+{
+    case XS = 'xs';
+    case SM = 'sm';
+    case MD = 'md';
+    case LG = 'lg';
+    case XL = 'xl';
+}
+```
+
+**Component Library Patterns**:
+```html
+<!-- ✅ Wiederverwendbare Template-Komponenten -->
+<!-- components/button.view.php -->
+<button
+    type="{type|default:button}"
+    class="button button--{variant|default:primary}"
+    {disabled}
+>
+    <slot name="icon"></slot>
+    <span class="button__text">{text}</span>
+</button>
+
+<!-- components/card.view.php -->
+<article class="card {class}">
+    <header class="card__header">
+        <slot name="header">
+            <h3 class="card__title">{title}</h3>
+        </slot>
+    </header>
+
+    <div class="card__content">
+        <slot>Default content</slot>
+    </div>
+
+    <footer class="card__footer">
+        <slot name="footer"></slot>
+    </footer>
+</article>
+
+<!-- Usage in templates -->
+<include template="components/button" data="{
+    type: 'submit',
+    variant: 'primary',
+    text: 'Submit Form'
+}" />
+
+<include template="components/card" data="{
+    title: 'User Profile',
+    class: 'card--highlighted'
+}">
+    <slot name="header">
+        <h2>Custom Header</h2>
+    </slot>
+    <p>Card content goes here</p>
+</include>
+```
+
+**Accessibility Patterns**:
+```html
+<!-- ✅ WCAG-compliant Templates -->
+<nav aria-label="Main navigation">
+    <ul role="list">
+        <for items="menuItems" as="item">
+            <li>
+                <a
+                    href="{item.url}"
+                    aria-current="{item.isActive ? 'page' : null}"
+                >
+                    {item.label}
+                </a>
+            </li>
+        </for>
+    </ul>
+</nav>
+
+<!-- Accessible form patterns -->
+<form>
+    <div class="form-group">
+        <label for="email-input" id="email-label">
+            Email Address
+            <span aria-label="required">*</span>
+        </label>
+        <input
+            type="email"
+            id="email-input"
+            aria-labelledby="email-label"
+            aria-describedby="email-hint email-error"
+            aria-required="true"
+            aria-invalid="{hasError ? 'true' : 'false'}"
+        />
+        <span id="email-hint" class="form-hint">
+            We'll never share your email
+        </span>
+        <if condition="hasError">
+            <span id="email-error" role="alert" class="form-error">
+                {errorMessage}
+            </span>
+        </if>
+    </div>
+</form>
+```
+
+**MCP Server Preferences**:
+- **Primary**: Custom Framework MCP - Template System Analysis
+- **Secondary**: Magic - UI Component Inspiration (adapted to Framework patterns)
+- **Tertiary**: Context7 - Accessibility Standards, Design System Patterns
+- **Avoided**: Generic template engines - Framework hat eigenes System
+
+**Optimized Commands**:
+- `/design --template-component` - Neue wiederverwendbare Template-Komponente
+- `/analyze --design-system` - Design System Consistency Analysis
+- `/implement --design-token` - Design Token als Value Object
+- `/improve --accessibility` - Accessibility Compliance Verbesserungen
+- `/refactor --css-architecture` - ITCSS Layer Optimization
+
+**Auto-Activation Triggers**:
+- Keywords: "template", "design system", "component", "css", "accessibility"
+- Template-Dateien (.view.php) bearbeiten
+- CSS-Dateien in resources/css/ ändern
+- Design Token oder Spacing-Diskussionen
+- Accessibility-Compliance Anforderungen
+
+**Design System Governance**:
+```php
+// ✅ Design System Registry Pattern
+final readonly class DesignSystemRegistry
+{
+    /** @var array<ColorToken> */
+    private array $colorTokens = [];
+
+    /** @var array<SpacingToken> */
+    private array $spacingTokens = [];
+
+    /** @var array<string> Component paths */
+    private array $components = [];
+
+    public function registerColorToken(ColorToken $token): void
+    {
+        $this->colorTokens[$token->name] = $token;
+    }
+
+    public function generateCssVariables(): string
+    {
+        $css = ":root {\n";
+
+        foreach ($this->colorTokens as $token) {
+            $css .= "  {$token->toCssVariable()}\n";
+        }
+
+        foreach ($this->spacingTokens as $token) {
+            $css .= "  {$token->toCssVariable()}\n";
+        }
+
+        return $css . "}\n";
+    }
+
+    public function validateComponentUsage(string $template): DesignSystemReport
+    {
+        // Validate component usage against design system
+        return new DesignSystemReport([
+            'valid_components' => $this->findValidComponents($template),
+            'invalid_patterns' => $this->findInvalidPatterns($template),
+            'accessibility_issues' => $this->checkAccessibility($template)
+        ]);
+    }
+}
+```
+
+**Quality Standards**:
+- **Template Consistency**: 100% - alle Templates folgen Placeholder-Syntax
+- **CSS Architecture**: Strikte ITCSS Layer-Hierarchie
+- **Component Reusability**: Minimum 80% der UI aus wiederverwendbaren Komponenten
+- **Accessibility**: WCAG 2.1 AA Compliance für alle Templates
+- **Performance**: CSS unter 50KB (gzipped), Critical CSS inline
+- **Design Token Coverage**: 100% - keine Hard-coded Colors/Spacing
+
+**Integration mit Template Processors**:
+- **PlaceholderReplacer**: Variable Substitution
+- **ComponentProcessor**: Component Inclusion & Slot System
+- **ForProcessor**: Loop Rendering
+- **IfProcessor**: Conditional Rendering
+- **LayoutTagProcessor**: Layout System
+- **MetaManipulator**: Meta Tags & SEO
+- **AssetInjector**: CSS/JS Asset Management
+- **CsrfTokenProcessor**: Security Integration
+- **HoneypotProcessor**: Spam Protection
+
+**Performance Optimization**:
+```php
+// ✅ Critical CSS Extraction
+final readonly class CriticalCssExtractor
+{
+    public function extractForTemplate(string $template): string
+    {
+        // Extract critical CSS for above-the-fold content
+        $criticalSelectors = $this->analyzeCriticalPath($template);
+        return $this->generateCriticalCss($criticalSelectors);
+    }
+}
+
+// ✅ CSS Purging für Production
+final readonly class CssPurger
+{
+    public function purgeUnusedStyles(array $templates): string
+    {
+        $usedSelectors = $this->scanTemplatesForSelectors($templates);
+        return $this->generatePurgedCss($usedSelectors);
+    }
+}
+```
+
+**Development Workflow**:
+1. **Design Token Definition**: Value Objects für Colors, Spacing, Typography
+2. **Component Creation**: Template-Komponente mit Accessibility
+3. **CSS Implementation**: ITCSS-konforme Styles
+4. **Template Integration**: Component Usage in Pages
+5. **Accessibility Testing**: WCAG Compliance Verification
+6. **Performance Optimization**: Critical CSS, Asset Optimization
+
 ## Integration mit Standard SuperClaude System
 
 Diese Framework-Personas erweitern das bestehende SuperClaude System und können kombiniert werden:
@@ -289,7 +679,7 @@ Diese Framework-Personas erweitern das bestehende SuperClaude System und können
 # Framework-Core mit Standard-Architect
 --persona-framework-core --persona-architect
 
-# MCP-Specialist mit Standard-Analyzer  
+# MCP-Specialist mit Standard-Analyzer
 --persona-mcp-specialist --persona-analyzer
 
 # Value-Object mit Standard-Refactorer
@@ -297,6 +687,12 @@ Diese Framework-Personas erweitern das bestehende SuperClaude System und können
 
 # Discovery-Expert mit Standard-Performance
 --persona-discovery-expert --persona-performance
+
+# Template-Design-System mit Standard-Frontend
+--persona-template-design-system --persona-frontend
+
+# Template-Design-System mit Value-Object-Architect
+--persona-template-design-system --persona-value-object-architect
 ```
 
 ## Auto-Activation Integration
@@ -304,9 +700,10 @@ Diese Framework-Personas erweitern das bestehende SuperClaude System und können
 Framework-Personas haben Vorrang vor Standard-Personas bei Framework-spezifischen Triggern:
 
 - **Framework-Code erkannt** → Framework-Core aktiviert
-- **MCP-Integration detected** → MCP-Specialist aktiviert  
+- **MCP-Integration detected** → MCP-Specialist aktiviert
 - **Primitive Obsession** → Value-Object-Architect aktiviert
 - **Attribute-Arbeit** → Discovery-Expert aktiviert
+- **Template/Design System Arbeit** → Template-Design-System aktiviert
 
 ## Verwendung
 
@@ -322,4 +719,9 @@ Diese Framework-Personas werden automatisch verfügbar, wenn das SuperClaude Sys
 
 # Kombination mit Standard-Personas
 /improve --persona-value-object-architect --persona-refactorer
+
+# Template & Design System Arbeit
+/design --template-component --persona-template-design-system
+/analyze --design-system --accessibility
+/implement --design-token ColorToken --persona-value-object-architect
 ```

docs/claude/framework-refactoring-recommendations.md

@@ -0,0 +1,748 @@
+# Framework Refactoring Recommendations
+
+Comprehensive analysis and refactoring suggestions for the Custom PHP Framework.
+
+## Executive Summary
+
+**Framework Analysis Results:**
+- **Total PHP Files**: 2,469 files across 90+ modules
+- **Readonly Classes**: 1,550 (excellent immutability compliance)
+- **Exception Files**: 82 custom exceptions
+- **Initializers**: 65 initialization classes
+- **Service Interfaces**: 24+ service contracts
+- **Value Object Directories**: 49 dedicated VO namespaces
+
+**Overall Framework Health**: ✅ **EXCELLENT**
+
+The framework demonstrates strong adherence to modern PHP principles:
+- ✅ No inheritance (composition over inheritance)
+- ✅ Extensive use of readonly classes
+- ✅ Rich Value Object architecture
+- ✅ Proper exception hierarchy
+- ✅ Clean dependency injection
+
+## Priority 1: Critical Refactorings
+
+### 1.1 MagicLinks: Eliminate Primitive Array Obsession
+
+**Issue**: Commands and Value Objects use primitive `array` types instead of Value Objects
+
+**Current State**:
+```php
+// ❌ Primitive obsession in Commands
+final readonly class GenerateMagicLinkCommand
+{
+    public function __construct(
+        public TokenAction $action,
+        public array $payload,              // ⚠️ Primitive array
+        public ?TokenConfig $config = null,
+        public ?string $baseUrl = null,
+        public ?string $createdByIp = null,
+        public ?string $userAgent = null
+    ) {}
+}
+
+final readonly class ExecuteMagicLinkCommand
+{
+    public function __construct(
+        public MagicLinkToken $token,
+        public array $context = []          // ⚠️ Primitive array
+    ) {}
+}
+
+// ❌ Primitive arrays in Value Objects
+final readonly class MagicLinkData
+{
+    public function __construct(
+        public array $payload,              // ⚠️ Primitive array
+        // ... other properties
+    ) {}
+}
+
+final readonly class TokenConfig
+{
+    public function __construct(
+        public array $allowedIpRanges = [], // ⚠️ Primitive array
+        public array $metadata = []         // ⚠️ Primitive array
+        // ... other properties
+    ) {}
+}
+
+final readonly class ActionResult
+{
+    public function __construct(
+        public array $data = [],            // ⚠️ Primitive array
+        public array $errors = []           // ⚠️ Primitive array
+    ) {}
+}
+```
+
+**Recommended Refactoring**:
+
+Create dedicated Value Objects:
+
+```php
+// ✅ Create MagicLinkPayload Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class MagicLinkPayload
+{
+    private function __construct(
+        private array $data
+    ) {
+        if (empty($data)) {
+            throw new \InvalidArgumentException('Payload cannot be empty');
+        }
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+
+    public function get(string $key, mixed $default = null): mixed
+    {
+        return $this->data[$key] ?? $default;
+    }
+
+    public function has(string $key): bool
+    {
+        return isset($this->data[$key]);
+    }
+
+    public function with(string $key, mixed $value): self
+    {
+        $data = $this->data;
+        $data[$key] = $value;
+        return new self($data);
+    }
+}
+
+// ✅ Create ExecutionContext Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class ExecutionContext
+{
+    private function __construct(
+        private array $data
+    ) {}
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    public function with(string $key, mixed $value): self
+    {
+        $data = $this->data;
+        $data[$key] = $value;
+        return new self($data);
+    }
+
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}
+
+// ✅ Create IpRangeCollection Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class IpRangeCollection
+{
+    /** @param array<string> $ranges */
+    private function __construct(
+        private array $ranges
+    ) {
+        foreach ($ranges as $range) {
+            if (!$this->isValidIpRange($range)) {
+                throw new \InvalidArgumentException("Invalid IP range: {$range}");
+            }
+        }
+    }
+
+    public static function fromArray(array $ranges): self
+    {
+        return new self($ranges);
+    }
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public function contains(string $ip): bool
+    {
+        foreach ($this->ranges as $range) {
+            if ($this->ipInRange($ip, $range)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private function isValidIpRange(string $range): bool
+    {
+        // Validation logic
+        return true;
+    }
+
+    private function ipInRange(string $ip, string $range): bool
+    {
+        // Range checking logic
+        return true;
+    }
+}
+
+// ✅ Create Metadata Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class Metadata
+{
+    private function __construct(
+        private array $data
+    ) {}
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    public function with(string $key, mixed $value): self
+    {
+        $data = $this->data;
+        $data[$key] = $value;
+        return new self($data);
+    }
+
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}
+
+// ✅ Create ActionResultData Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class ActionResultData
+{
+    private function __construct(
+        private array $data
+    ) {}
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}
+
+// ✅ Create ErrorCollection Value Object
+namespace App\Framework\MagicLinks\ValueObjects;
+
+final readonly class ErrorCollection
+{
+    /** @param array<string> $errors */
+    private function __construct(
+        private array $errors
+    ) {}
+
+    public static function empty(): self
+    {
+        return new self([]);
+    }
+
+    public static function fromArray(array $errors): self
+    {
+        return new self($errors);
+    }
+
+    public function add(string $error): self
+    {
+        $errors = $this->errors;
+        $errors[] = $error;
+        return new self($errors);
+    }
+
+    public function hasErrors(): bool
+    {
+        return !empty($this->errors);
+    }
+
+    public function toArray(): array
+    {
+        return $this->errors;
+    }
+}
+
+// ✅ Updated Command Classes
+namespace App\Framework\MagicLinks\Commands;
+
+use App\Framework\MagicLinks\ValueObjects\MagicLinkPayload;
+use App\Framework\MagicLinks\TokenAction;
+use App\Framework\MagicLinks\TokenConfig;
+
+final readonly class GenerateMagicLinkCommand
+{
+    public function __construct(
+        public TokenAction $action,
+        public MagicLinkPayload $payload,     // ✅ Value Object
+        public ?TokenConfig $config = null,
+        public ?string $baseUrl = null,
+        public ?string $createdByIp = null,
+        public ?string $userAgent = null
+    ) {}
+}
+
+use App\Framework\MagicLinks\ValueObjects\ExecutionContext;
+use App\Framework\MagicLinks\MagicLinkToken;
+
+final readonly class ExecuteMagicLinkCommand
+{
+    public function __construct(
+        public MagicLinkToken $token,
+        public ExecutionContext $context      // ✅ Value Object
+    ) {}
+
+    public static function withToken(MagicLinkToken $token): self
+    {
+        return new self($token, ExecutionContext::empty());
+    }
+}
+
+// ✅ Updated MagicLinkData
+namespace App\Framework\MagicLinks;
+
+use App\Framework\MagicLinks\ValueObjects\MagicLinkPayload;
+
+final readonly class MagicLinkData
+{
+    public function __construct(
+        public string $id,
+        public TokenAction $action,
+        public MagicLinkPayload $payload,     // ✅ Value Object
+        public DateTimeImmutable $expiresAt,
+        public DateTimeImmutable $createdAt,
+        public bool $oneTimeUse = false,
+        public ?string $createdByIp = null,
+        public ?string $userAgent = null,
+        public bool $isUsed = false,
+        public ?DateTimeImmutable $usedAt = null
+    ) {}
+}
+
+// ✅ Updated TokenConfig
+namespace App\Framework\MagicLinks;
+
+use App\Framework\MagicLinks\ValueObjects\IpRangeCollection;
+use App\Framework\MagicLinks\ValueObjects\Metadata;
+
+final readonly class TokenConfig
+{
+    public function __construct(
+        public int $ttlMinutes = 60,
+        public bool $oneTimeUse = false,
+        public IpRangeCollection $allowedIpRanges, // ✅ Value Object
+        public Metadata $metadata,                  // ✅ Value Object
+        public ?int $maxUsageCount = null,
+        public bool $requireUserAgent = false
+    ) {}
+
+    public static function default(): self
+    {
+        return new self(
+            allowedIpRanges: IpRangeCollection::empty(),
+            metadata: Metadata::empty()
+        );
+    }
+}
+
+// ✅ Updated ActionResult
+namespace App\Framework\MagicLinks\Actions;
+
+use App\Framework\MagicLinks\ValueObjects\ActionResultData;
+use App\Framework\MagicLinks\ValueObjects\ErrorCollection;
+
+final readonly class ActionResult
+{
+    public function __construct(
+        public bool $success,
+        public ?string $message = null,
+        public ActionResultData $data,        // ✅ Value Object
+        public ErrorCollection $errors,       // ✅ Value Object
+        public ?string $redirectUrl = null
+    ) {}
+
+    public static function success(
+        string $message = null,
+        ActionResultData $data = null
+    ): self {
+        return new self(
+            success: true,
+            message: $message,
+            data: $data ?? ActionResultData::empty(),
+            errors: ErrorCollection::empty()
+        );
+    }
+
+    public static function failure(
+        string $message,
+        ErrorCollection $errors = null
+    ): self {
+        return new self(
+            success: false,
+            message: $message,
+            data: ActionResultData::empty(),
+            errors: $errors ?? ErrorCollection::empty()
+        );
+    }
+}
+```
+
+**Migration Strategy**:
+
+1. Create Value Objects in `/src/Framework/MagicLinks/ValueObjects/`
+2. Update Commands to use Value Objects
+3. Update MagicLinkData, TokenConfig, ActionResult
+4. Update handlers to work with new Value Objects
+5. Add factory methods for backward compatibility during transition
+6. Update tests to use new Value Objects
+7. Update documentation with new patterns
+
+**Impact**:
+- ✅ Better type safety
+- ✅ Self-documenting code
+- ✅ Validation at construction
+- ✅ Immutable transformations
+- ✅ Consistent with framework patterns
+
+**Files to Modify**:
+- `/src/Framework/MagicLinks/Commands/GenerateMagicLinkCommand.php`
+- `/src/Framework/MagicLinks/Commands/ExecuteMagicLinkCommand.php`
+- `/src/Framework/MagicLinks/MagicLinkData.php`
+- `/src/Framework/MagicLinks/TokenConfig.php`
+- `/src/Framework/MagicLinks/Actions/ActionResult.php`
+- `/src/Framework/MagicLinks/Commands/GenerateMagicLinkHandler.php`
+- `/src/Framework/MagicLinks/Commands/ExecuteMagicLinkHandler.php`
+
+### 1.2 Error/Exception Module Consolidation
+
+**Issue**: Framework has 5 separate error-related modules with potential overlap
+
+**Current Modules**:
+- `ErrorAggregation/` - Error event aggregation and pattern detection
+- `ErrorBoundaries/` - Resilience patterns (retry, circuit breaker)
+- `ErrorHandling/` - Core error handling and logging
+- `ErrorReporting/` - Error reporting and analytics
+- `Exception/` - Base exception classes and error codes
+
+**Concern**: Potential functional overlap and confusion about where error-related code belongs
+
+**Recommended Analysis**:
+
+1. **Audit Module Responsibilities**:
+   ```bash
+   # Analyze each module's actual responsibilities
+   # Check for duplicate functionality
+   # Identify cross-module dependencies
+   ```
+
+2. **Potential Consolidation** (after audit):
+   - Keep `Exception/` as base exception framework
+   - Keep `ErrorBoundaries/` for resilience patterns (distinct purpose)
+   - Consider merging `ErrorHandling/`, `ErrorAggregation/`, and `ErrorReporting/` into single `ErrorManagement/` module with clear sub-namespaces:
+     - `ErrorManagement/Handling/` - Core error handling
+     - `ErrorManagement/Aggregation/` - Pattern detection
+     - `ErrorManagement/Reporting/` - Analytics and reporting
+
+3. **Decision Criteria**:
+   - Do modules have genuinely separate concerns?
+   - Is there code duplication across modules?
+   - Would consolidation improve or harm discoverability?
+
+**Action**: Detailed audit required before implementation
+
+## Priority 2: Consistency Improvements
+
+### 2.1 Naming Convention Standardization
+
+**Issue**: Inconsistent naming for similar components
+
+**Current Pattern**:
+```
+Queue/Services/ProgressManager.php
+Queue/Services/JobMetricsManager.php
+Queue/Services/JobCleanupService.php
+```
+
+**Recommendation**: Establish clear naming conventions
+
+**Proposed Standard**:
+- **Manager**: Coordinates multiple operations, manages lifecycle
+- **Service**: Performs specific business operations
+- **Handler**: Handles commands/events/requests
+- **Processor**: Processes/transforms data
+- **Builder**: Constructs complex objects
+- **Factory**: Creates instances
+- **Repository**: Data access abstraction
+- **Registry**: Maintains collections of items
+
+**Example Application**:
+```
+✅ JobLifecycleManager - manages job lifecycle
+✅ JobCleanupService - specific cleanup operations
+✅ JobMetricsCollector - collects metrics
+✅ DeadLetterManager - manages dead letter queue
+```
+
+### 2.2 Command/Handler Consistency
+
+**Current State**: Generally good, but verify all Commands have corresponding Handlers
+
+**Verification Steps**:
+```bash
+# Find all Command classes
+find src/Framework -name "*Command.php" | sort
+
+# Find all Handler classes
+find src/Framework -name "*Handler.php" | sort
+
+# Ensure 1:1 mapping
+```
+
+**Recommendation**: Enforce convention where every `XyzCommand` has `XyzHandler`
+
+## Priority 3: Architecture Enhancements
+
+### 3.1 Value Object Directory Structure
+
+**Current State**: 49 Value Object directories across framework - EXCELLENT!
+
+**Recommendation**: Create Value Object documentation/index
+
+**Suggested Documentation**:
+
+```markdown
+# Framework Value Objects
+
+## Core Value Objects (Framework/Core/ValueObjects/)
+- `Duration` - Time duration representation
+- `Timestamp` - Point in time
+- `Url` - URL validation and manipulation
+- `EmailAddress` - Email validation
+- `Money` - Monetary values with currency
+- `ClassName` - Fully qualified class names
+- `Hash` - Hash values with algorithm
+- `Port` - Network port numbers
+- `Percentage` - Percentage values (0-100)
+
+## Domain-Specific Value Objects
+[Auto-generate from discovery...]
+
+## Usage Guidelines
+- Always prefer Value Objects over primitives for domain concepts
+- Value Objects should be `final readonly`
+- Include validation in constructor
+- Provide factory methods for common cases
+- Implement transformation methods that return new instances
+```
+
+### 3.2 Module Inter-Dependencies
+
+**Recommendation**: Create dependency graph visualization
+
+**Tool Suggestion**:
+```php
+// Create ModuleDependencyAnalyzer
+namespace App\Framework\Quality;
+
+final readonly class ModuleDependencyAnalyzer
+{
+    public function analyzeModuleDependencies(): array
+    {
+        // Scan use statements across modules
+        // Build dependency graph
+        // Detect circular dependencies
+        // Generate visualization
+    }
+
+    public function detectCircularDependencies(): array
+    {
+        // Identify circular dependencies
+    }
+
+    public function calculateCouplingMetrics(): array
+    {
+        // Calculate afferent/efferent coupling
+        // Identify highly coupled modules
+    }
+}
+```
+
+## Priority 4: Performance Optimizations
+
+### 4.1 Initializer Optimization
+
+**Current State**: 65 Initializer classes
+
+**Recommendation**: Analyze and optimize initializer execution order
+
+**Suggested Tool**:
+```php
+namespace App\Framework\DI;
+
+final readonly class InitializerPerformanceAnalyzer
+{
+    public function analyzeInitializerPerformance(): array
+    {
+        // Track initialization time for each Initializer
+        // Identify slow initializers
+        // Suggest optimization opportunities
+        // Detect unnecessary initialization in CLI context
+    }
+
+    public function suggestLazyInitialization(): array
+    {
+        // Suggest which services could be lazy-loaded
+    }
+}
+```
+
+### 4.2 Service Interface Optimization
+
+**Current State**: 24+ service interfaces
+
+**Recommendation**: Ensure interfaces are truly necessary
+
+**Analysis Criteria**:
+- Does interface have multiple implementations?
+- Is interface used for dependency injection?
+- Does interface provide abstraction value?
+- Could concrete class suffice?
+
+**Tool**:
+```bash
+# Find interfaces with single implementation
+for interface in $(find src/Framework -name "*Interface.php" -o -name "*Service.php" | grep interface); do
+    implementations=$(grep -r "implements $(basename $interface .php)" src/ | wc -l)
+    if [ $implementations -eq 1 ]; then
+        echo "Single implementation: $interface"
+    fi
+done
+```
+
+## Priority 5: Testing Improvements
+
+### 5.1 Test Coverage for Value Objects
+
+**Recommendation**: Ensure 100% test coverage for all Value Objects
+
+**Suggested Test Pattern**:
+```php
+describe('MagicLinkPayload', function () {
+    it('validates non-empty payload on construction', function () {
+        expect(fn() => MagicLinkPayload::fromArray([]))
+            ->toThrow(\InvalidArgumentException::class);
+    });
+
+    it('provides immutable transformations', function () {
+        $payload = MagicLinkPayload::fromArray(['key' => 'value']);
+        $updated = $payload->with('new_key', 'new_value');
+
+        expect($payload)->not->toBe($updated);
+        expect($updated->toArray())->toHaveKey('new_key');
+        expect($payload->toArray())->not->toHaveKey('new_key');
+    });
+
+    it('safely retrieves values with defaults', function () {
+        $payload = MagicLinkPayload::fromArray(['key' => 'value']);
+
+        expect($payload->get('key'))->toBe('value');
+        expect($payload->get('missing', 'default'))->toBe('default');
+    });
+});
+```
+
+### 5.2 Integration Test Coverage
+
+**Recommendation**: Verify integration between MagicLinks and other modules
+
+**Key Integration Points**:
+- CommandBus integration
+- Cache service integration
+- Event system integration (if applicable)
+- Action registry discovery
+
+## Implementation Priority
+
+**Phase 1 (High Priority - 1-2 weeks)**:
+1. ✅ MagicLinks Value Object refactoring (Priority 1.1)
+2. ✅ Naming convention audit and standardization (Priority 2.1)
+3. ✅ Command/Handler consistency verification (Priority 2.2)
+
+**Phase 2 (Medium Priority - 2-4 weeks)**:
+1. ✅ Error module consolidation analysis (Priority 1.2)
+2. ✅ Value Object documentation (Priority 3.1)
+3. ✅ Module dependency analysis (Priority 3.2)
+
+**Phase 3 (Lower Priority - 1-2 months)**:
+1. ✅ Initializer performance optimization (Priority 4.1)
+2. ✅ Service interface optimization (Priority 4.2)
+3. ✅ Test coverage improvements (Priority 5)
+
+## Success Metrics
+
+**Code Quality Metrics**:
+- ✅ Reduce primitive array usage in Commands by 100%
+- ✅ Achieve 100% Value Object test coverage
+- ✅ Reduce module coupling by 20%
+- ✅ Standardize 95%+ of naming conventions
+
+**Performance Metrics**:
+- ✅ Reduce initialization time by 15%
+- ✅ Identify and eliminate circular dependencies
+
+**Developer Experience**:
+- ✅ Clear module responsibilities documentation
+- ✅ Value Object usage guidelines
+- ✅ Dependency graph visualization
+
+## Conclusion
+
+The Custom PHP Framework demonstrates **excellent architectural principles** with strong adherence to:
+- Composition over inheritance
+- Immutability with readonly classes
+- Rich Value Object usage
+- Clean dependency injection
+
+**Primary Focus Areas**:
+1. **Eliminate primitive array obsession** in MagicLinks module
+2. **Standardize naming conventions** across services/managers/handlers
+3. **Document and visualize** Value Object architecture
+4. **Analyze and potentially consolidate** error-related modules
+
+The framework is in excellent health and these refactorings will enhance an already solid architecture.

docs/claude/magiclinks-system.md

@@ -0,0 +1,807 @@
+# MagicLinks System
+
+Dokumentation des MagicLinks Moduls - Sichere, zeitlich begrenzte Links für verschiedene Aktionen.
+
+## Übersicht
+
+Das MagicLinks System ermöglicht die Generierung und Verwaltung von sicheren, zeitlich begrenzten Links für verschiedene Anwendungsfälle wie Email-Verifizierung, Passwort-Reset, Dokumentenzugriff und mehr.
+
+## Architektur
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  Token System   │───▶│  Service Layer  │───▶│  Action System  │
+│  (Value Objects)│    │  (Storage)      │    │  (Execution)    │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                      │                       │
+    MagicLinkToken         MagicLinkService      MagicLinkAction
+    MagicLinkData          CacheMagicLink...     ActionRegistry
+    TokenAction            InMemoryMagicLink     ActionResult
+    TokenConfig
+```
+
+## Kern-Komponenten
+
+### 1. Token System
+
+**SmartLinkToken** - Value Object für Token:
+```php
+final readonly class SmartLinkToken
+{
+    public function __construct(
+        public string $value  // Min. 16 Zeichen
+    ) {}
+
+    public function equals(MagicLinkToken $other): bool
+    {
+        return hash_equals($this->value, $other->value);
+    }
+}
+```
+
+**MagicLinkData** - Token-Daten:
+```php
+final readonly class MagicLinkData
+{
+    public function __construct(
+        public string $id,
+        public TokenAction $action,           // Welche Action
+        public array $payload,                // Action-spezifische Daten
+        public DateTimeImmutable $expiresAt,  // Ablaufzeit
+        public DateTimeImmutable $createdAt,
+        public bool $oneTimeUse = false,      // Einmalige Verwendung?
+        public ?string $createdByIp = null,   // Tracking
+        public ?string $userAgent = null,
+        public bool $isUsed = false,
+        public ?DateTimeImmutable $usedAt = null
+    ) {}
+
+    public function isExpired(): bool;
+    public function isValid(): bool;
+    public function getRemainingTime(): \DateInterval;
+    public function withUsed(DateTimeImmutable $usedAt): self;
+}
+```
+
+**TokenAction** - Action-Identifier:
+```php
+final readonly class TokenAction
+{
+    public function __construct(
+        public string $value  // z.B. 'email_verification', 'password_reset'
+    ) {}
+}
+```
+
+**TokenConfig** - Token-Konfiguration:
+```php
+final readonly class TokenConfig
+{
+    public function __construct(
+        public int $ttlSeconds = 3600,      // Time-to-Live
+        public bool $oneTimeUse = false,    // Einmalige Verwendung
+        public ?int $maxUses = null,        // Max. Anzahl Verwendungen
+        public bool $ipRestriction = false  // IP-basierte Restriktion
+    ) {}
+}
+```
+
+### 2. Service Layer
+
+**MagicLinkService Interface**:
+```php
+interface MagicLinkService
+{
+    // Token generieren
+    public function generate(
+        TokenAction $action,
+        array $payload,
+        ?TokenConfig $config = null,
+        ?string $createdByIp = null,
+        ?string $userAgent = null
+    ): MagicLinkToken;
+
+    // Token validieren und Daten abrufen
+    public function validate(MagicLinkToken $token): ?MagicLinkData;
+
+    // Token als verwendet markieren
+    public function markAsUsed(MagicLinkToken $token): void;
+
+    // Token widerrufen
+    public function revoke(MagicLinkToken $token): void;
+
+    // Token-Existenz prüfen
+    public function exists(MagicLinkToken $token): bool;
+
+    // Admin: Aktive Tokens abrufen
+    public function getActiveTokens(int $limit = 100): array;
+
+    // Cleanup: Abgelaufene Tokens löschen
+    public function cleanupExpired(): int;
+}
+```
+
+**Implementierungen**:
+
+- **CacheMagicLinkService** - Cache-basierte Implementierung (Production)
+- **InMemoryMagicLinkService** - In-Memory Implementierung (Testing)
+
+### 3. Action System
+
+**MagicLinkAction Interface**:
+```php
+interface MagicLinkAction
+{
+    // Action-Name
+    public function getName(): string;
+
+    // Default-Konfiguration
+    public function getDefaultConfig(): TokenConfig;
+
+    // Payload validieren
+    public function validatePayload(array $payload): bool;
+
+    // Action ausführen
+    public function execute(MagicLinkData $magiclinkData, array $context = []): ActionResult;
+
+    // Erforderliche Permissions
+    public function getRequiredPermissions(): array;
+}
+```
+
+**ActionResult** - Execution-Ergebnis:
+```php
+final readonly class ActionResult
+{
+    public function __construct(
+        public bool $success,
+        public string $message,
+        public array $data = [],
+        public array $errors = [],
+        public ?string $redirectUrl = null
+    ) {}
+
+    public function isSuccess(): bool;
+    public function hasRedirect(): bool;
+}
+```
+
+**ActionRegistry** - Action-Verwaltung:
+```php
+interface ActionRegistry
+{
+    public function register(MagicLinkAction $action): void;
+    public function get(TokenAction $action): ?MagicLinkAction;
+    public function has(TokenAction $action): bool;
+    public function all(): array;
+}
+```
+
+### 4. Vordefinierte Actions
+
+**EmailVerificationAction**:
+```php
+final readonly class EmailVerificationAction implements MagicLinkAction
+{
+    public function getName(): string
+    {
+        return 'email_verification';
+    }
+
+    public function getDefaultConfig(): TokenConfig
+    {
+        return new TokenConfig(
+            ttlSeconds: 86400,    // 24 Stunden
+            oneTimeUse: true      // Einmalig verwendbar
+        );
+    }
+
+    public function validatePayload(array $payload): bool
+    {
+        return isset($payload['user_id']) && isset($payload['email']);
+    }
+
+    public function execute(MagicLinkData $magiclinkData, array $context = []): ActionResult
+    {
+        // Email-Verifizierungs-Logik
+    }
+}
+```
+
+**PasswordResetAction**:
+```php
+final readonly class PasswordResetAction implements MagicLinkAction
+{
+    public function getName(): string
+    {
+        return 'password_reset';
+    }
+
+    public function getDefaultConfig(): TokenConfig
+    {
+        return new TokenConfig(
+            ttlSeconds: 3600,     // 1 Stunde
+            oneTimeUse: true,
+            ipRestriction: true   // IP-gebunden
+        );
+    }
+}
+```
+
+**DocumentAccessAction** - Temporärer Dokumentenzugriff:
+```php
+final readonly class DocumentAccessAction implements MagicLinkAction
+{
+    public function getName(): string
+    {
+        return 'document_access';
+    }
+
+    public function getDefaultConfig(): TokenConfig
+    {
+        return new TokenConfig(
+            ttlSeconds: 3600,     // 1 Stunde
+            maxUses: 5            // Max. 5 Downloads
+        );
+    }
+}
+```
+
+**GenericDataAccessAction** - Generischer Datenzugriff:
+```php
+final readonly class GenericDataAccessAction implements MagicLinkAction
+{
+    public function getName(): string
+    {
+        return 'data_access';
+    }
+}
+```
+
+## Command/Handler Pattern
+
+**GenerateMagicLinkCommand**:
+```php
+final readonly class GenerateMagicLinkCommand
+{
+    public function __construct(
+        public TokenAction $action,
+        public array $payload,
+        public string $baseUrl,
+        public ?TokenConfig $config = null
+    ) {}
+}
+```
+
+**GenerateMagicLinkHandler**:
+```php
+final readonly class GenerateMagicLinkHandler
+{
+    public function handle(GenerateMagicLinkCommand $command): string
+    {
+        // 1. Token generieren
+        $token = $this->magiclinkService->generate(
+            $command->action,
+            $command->payload,
+            $command->config
+        );
+
+        // 2. URL zusammenbauen
+        return $command->baseUrl . '/magiclink/' . $token->value;
+    }
+}
+```
+
+**ExecuteMagicLinkCommand**:
+```php
+final readonly class ExecuteMagicLinkCommand
+{
+    public function __construct(
+        public MagicLinkToken $token,
+        public array $context = []
+    ) {}
+}
+```
+
+**ExecuteMagicLinkHandler**:
+```php
+final readonly class ExecuteMagicLinkHandler
+{
+    public function handle(ExecuteMagicLinkCommand $command): ActionResult
+    {
+        // 1. Token validieren
+        $data = $this->magiclinkService->validate($command->token);
+
+        // 2. Action holen und ausführen
+        $action = $this->actionRegistry->get($data->action);
+        $result = $action->execute($data, $command->context);
+
+        // 3. Bei One-Time-Use: Als verwendet markieren
+        if ($data->oneTimeUse && $result->isSuccess()) {
+            $this->magiclinkService->markAsUsed($command->token);
+        }
+
+        return $result;
+    }
+}
+```
+
+## HTTP Controller
+
+**Route**: `/magiclink/{token}` (GET/POST)
+
+```php
+final readonly class MagicLink
+{
+    #[Route('/magiclink/{token}', method: Method::GET)]
+    #[Route('/magiclink/{token}', method: Method::POST)]
+    public function execute(string $token, Request $request): ActionResult
+    {
+        // 1. Token validieren
+        $magiclinkToken = new MagicLinkToken($token);
+        $magiclinkData = $this->magiclinkService->validate($magiclinkToken);
+
+        if (!$magiclinkData) {
+            return new ViewResult(
+                template: 'magiclinks-error',
+                data: ['error' => 'Ungültiger oder abgelaufener Link']
+            );
+        }
+
+        // 2. Action holen
+        $action = $this->actionRegistry->get($magiclinkData->action);
+
+        // 3. Context vorbereiten
+        $context = [
+            'request_method' => $request->method->value,
+            'request_data' => $request->parsedBody ?? [],
+            'query_params' => $request->queryParameters ?? [],
+            'user_agent' => $request->headers->getFirst(HeaderKey::USER_AGENT),
+        ];
+
+        // 4. Command ausführen
+        $command = new ExecuteMagicLinkCommand($magiclinkToken, $context);
+        $result = $this->commandBus->dispatch($command);
+
+        // 5. Ergebnis verarbeiten
+        if ($result->hasRedirect()) {
+            return new Redirect($result->redirectUrl);
+        }
+
+        return new ViewResult(
+            template: $action->getViewTemplate(),
+            data: ['result' => $result]
+        );
+    }
+}
+```
+
+## Verwendung
+
+### MagicLink generieren
+
+```php
+use App\Framework\MagicLinks\Commands\GenerateMagicLinkCommand;
+use App\Framework\MagicLinks\TokenAction;
+use App\Framework\MagicLinks\TokenConfig;
+
+// 1. Command erstellen
+$command = new GenerateMagicLinkCommand(
+    action: new TokenAction('email_verification'),
+    payload: [
+        'user_id' => 123,
+        'email' => 'user@example.com'
+    ],
+    baseUrl: 'https://example.com',
+    config: new TokenConfig(
+        ttlSeconds: 86400,  // 24 Stunden
+        oneTimeUse: true
+    )
+);
+
+// 2. Via CommandBus dispatchen
+$url = $this->commandBus->dispatch($command);
+
+// 3. URL versenden (z.B. per Email)
+$this->mailer->send($user->email, $url);
+```
+
+### Eigene Action implementieren
+
+```php
+final readonly class InvitationAcceptAction implements MagicLinkAction
+{
+    public function getName(): string
+    {
+        return 'invitation_accept';
+    }
+
+    public function getDefaultConfig(): TokenConfig
+    {
+        return new TokenConfig(
+            ttlSeconds: 604800,  // 7 Tage
+            oneTimeUse: true
+        );
+    }
+
+    public function validatePayload(array $payload): bool
+    {
+        return isset($payload['invitation_id'])
+            && isset($payload['invitee_email']);
+    }
+
+    public function execute(MagicLinkData $magiclinkData, array $context = []): ActionResult
+    {
+        $invitationId = $magiclinkData->payload['invitation_id'];
+
+        try {
+            // Business Logic
+            $this->invitationService->accept($invitationId);
+
+            return new ActionResult(
+                success: true,
+                message: 'Einladung erfolgreich angenommen',
+                redirectUrl: '/dashboard'
+            );
+        } catch (\Exception $e) {
+            return new ActionResult(
+                success: false,
+                message: 'Fehler beim Annehmen der Einladung',
+                errors: [$e->getMessage()]
+            );
+        }
+    }
+
+    public function getRequiredPermissions(): array
+    {
+        return [];  // Öffentlich zugänglich
+    }
+}
+```
+
+### Action registrieren
+
+```php
+// In MagicLinkInitializer
+final readonly class MagicLinkInitializer
+{
+    #[Initializer]
+    public function __invoke(): ActionRegistry
+    {
+        $registry = new DefaultActionRegistry();
+
+        // Vordefinierte Actions
+        $registry->register(new EmailVerificationAction());
+        $registry->register(new PasswordResetAction());
+        $registry->register(new DocumentAccessAction());
+
+        // Custom Action
+        $registry->register(new InvitationAcceptAction());
+
+        return $registry;
+    }
+}
+```
+
+## Service-Konfiguration
+
+```php
+// In MagicLinkInitializer
+#[Initializer]
+public function init(): MagicLinkService
+{
+    // Production: Cache-basiert
+    return $this->container->get(CacheMagicLinkService::class);
+
+    // Testing: In-Memory
+    // return $this->container->get(InMemoryMagicLinkService::class);
+}
+```
+
+## Sicherheitsaspekte
+
+### Token-Generierung
+- **Min. 16 Zeichen** für Token-Sicherheit
+- **Kryptographisch sichere** Zufallstoken
+- **Hash-basierter Vergleich** via `hash_equals()`
+
+### Token-Validierung
+- **Ablaufzeit-Prüfung** - `isExpired()`
+- **One-Time-Use** - `isUsed` Flag
+- **Max-Uses Tracking** - Optional
+- **IP-Restriktion** - Optional via `createdByIp`
+
+### Action-Ausführung
+- **Payload-Validierung** - `validatePayload()`
+- **Permission-Checks** - `getRequiredPermissions()`
+- **Context-Validierung** - Request-Daten prüfen
+- **Error-Handling** - Graceful Degradation
+
+## Cleanup & Wartung
+
+### Automatisches Cleanup
+
+```php
+// Cleanup-Command erstellen
+final readonly class CleanupExpiredMagicLinksCommand implements ConsoleCommand
+{
+    public function __construct(
+        private MagicLinkService $magiclinkService
+    ) {}
+
+    public function execute(ConsoleInput $input): int
+    {
+        $deleted = $this->magiclinkService->cleanupExpired();
+
+        echo "Deleted {$deleted} expired magiclinks\n";
+
+        return ExitCode::SUCCESS;
+    }
+}
+```
+
+### Scheduled Cleanup via Scheduler
+
+```php
+// In Scheduler registrieren
+$scheduler->schedule(
+    'cleanup-magiclinks',
+    CronSchedule::fromExpression('0 2 * * *'),  // Täglich 02:00
+    fn() => $this->magiclinkService->cleanupExpired()
+);
+```
+
+## Testing
+
+### Unit Tests
+
+```php
+describe('MagicLinkService', function () {
+    it('generates valid tokens', function () {
+        $service = new InMemoryMagicLinkService();
+
+        $token = $service->generate(
+            action: new TokenAction('test'),
+            payload: ['user_id' => 1]
+        );
+
+        expect($token->value)->toHaveLength(32);
+        expect($service->exists($token))->toBeTrue();
+    });
+
+    it('validates tokens correctly', function () {
+        $service = new InMemorySmartLinkService();
+
+        $token = $service->generate(
+            action: new TokenAction('test'),
+            payload: ['data' => 'test'],
+            config: new TokenConfig(ttlSeconds: 3600)
+        );
+
+        $data = $service->validate($token);
+
+        expect($data)->not->toBeNull();
+        expect($data->payload['data'])->toBe('test');
+        expect($data->isValid())->toBeTrue();
+    });
+
+    it('marks one-time tokens as used', function () {
+        $service = new InMemorySmartLinkService();
+
+        $token = $service->generate(
+            action: new TokenAction('test'),
+            payload: [],
+            config: new TokenConfig(oneTimeUse: true)
+        );
+
+        $service->markAsUsed($token);
+
+        $data = $service->validate($token);
+        expect($data->isValid())->toBeFalse();
+    });
+});
+```
+
+### Integration Tests
+
+```php
+describe('MagicLink Controller', function () {
+    it('executes valid magiclink', function () {
+        // Token generieren
+        $command = new GenerateMagicLinkCommand(
+            action: new TokenAction('email_verification'),
+            payload: ['user_id' => 1, 'email' => 'test@example.com'],
+            baseUrl: 'https://test.local'
+        );
+
+        $url = $this->commandBus->dispatch($command);
+
+        // Request simulieren
+        $response = $this->get($url);
+
+        expect($response->status)->toBe(Status::OK);
+    });
+});
+```
+
+## Best Practices
+
+### 1. Token-Konfiguration
+- **Email-Verifizierung**: 24h TTL, One-Time-Use
+- **Passwort-Reset**: 1h TTL, One-Time-Use, IP-Restriction
+- **Dokumentenzugriff**: 1h TTL, Max-Uses basierend auf Bedarf
+- **Einladungen**: 7d TTL, One-Time-Use
+
+### 2. Payload-Design
+- **Minimale Daten**: Nur notwendige IDs, keine sensiblen Daten
+- **Validierung**: Immer `validatePayload()` implementieren
+- **Versionierung**: Bei Schema-Änderungen Versionsnummer in Payload
+
+### 3. Action-Implementation
+- **Idempotenz**: Actions sollten mehrfach ausführbar sein
+- **Atomarität**: Entweder vollständig erfolgreich oder vollständig fehlgeschlagen
+- **Logging**: Wichtige Actions loggen für Audit-Trail
+
+### 4. Error-Handling
+- **Graceful Degradation**: Sinnvolle Fehlermeldungen
+- **User-Feedback**: Klare Kommunikation bei Problemen
+- **Security**: Keine internen Details in Fehlermeldungen
+
+### 5. Monitoring
+- **Token-Usage**: Tracking von Token-Generierung und -Verwendung
+- **Action-Success-Rate**: Erfolgsrate verschiedener Actions
+- **Expired-Tokens**: Anzahl abgelaufener Tokens monitoren
+- **Cleanup-Effizienz**: Performance des Cleanup-Prozesses
+
+## Troubleshooting
+
+### Problem: Token wird nicht validiert
+
+**Ursachen**:
+- Token abgelaufen
+- Token bereits verwendet (One-Time-Use)
+- Token wurde widerrufen
+- Cache-Inkonsistenz
+
+**Lösung**:
+```php
+$data = $service->validate($token);
+
+if (!$data) {
+    // Token existiert nicht
+} elseif ($data->isExpired()) {
+    // Token abgelaufen
+} elseif ($data->isUsed) {
+    // Token bereits verwendet
+}
+```
+
+### Problem: Action schlägt fehl
+
+**Ursachen**:
+- Payload-Validierung fehlgeschlagen
+- Business-Logic-Fehler
+- Fehlende Permissions
+
+**Lösung**:
+```php
+if (!$action->validatePayload($data->payload)) {
+    return new ActionResult(
+        success: false,
+        message: 'Ungültige Token-Daten',
+        errors: ['Invalid payload structure']
+    );
+}
+```
+
+### Problem: Performance bei vielen Tokens
+
+**Lösungen**:
+- **Regelmäßiges Cleanup**: Expired Tokens entfernen
+- **Index-Optimierung**: Bei Database-backed Service
+- **Cache-Strategie**: Richtige Cache-TTL wählen
+- **Batch-Operations**: Cleanup in Batches
+
+## Framework-Integration
+
+### Mit Event System
+
+```php
+// Event bei Token-Generierung
+$this->eventDispatcher->dispatch(
+    new MagicLinkGeneratedEvent($token, $action)
+);
+
+// Event bei Action-Ausführung
+$this->eventDispatcher->dispatch(
+    new MagicLinkExecutedEvent($token, $result)
+);
+```
+
+### Mit Queue System
+
+```php
+// Asynchrone Action-Ausführung
+final readonly class MagicLinkExecutionJob
+{
+    public function handle(): void
+    {
+        $command = new ExecuteMagicLinkCommand($this->token);
+        $this->commandBus->dispatch($command);
+    }
+}
+```
+
+### Mit Scheduler
+
+```php
+// Regelmäßiges Cleanup
+$scheduler->schedule(
+    'magiclink-cleanup',
+    IntervalSchedule::every(Duration::fromHours(6)),
+    fn() => $this->magiclinkService->cleanupExpired()
+);
+```
+
+## Erweiterungen
+
+### Multi-Factor MagicLinks
+
+```php
+final readonly class MfaRequiredAction implements MagicLinkAction
+{
+    public function execute(MagicLinkData $data, array $context = []): ActionResult
+    {
+        // Zusätzliche MFA-Verifikation anfordern
+        if (!isset($context['mfa_code'])) {
+            return new ActionResult(
+                success: false,
+                message: 'MFA-Code erforderlich',
+                data: ['requires_mfa' => true]
+            );
+        }
+
+        // MFA validieren und Action ausführen
+    }
+}
+```
+
+### Rate-Limited Actions
+
+```php
+final readonly class RateLimitedAction implements MagicLinkAction
+{
+    public function execute(MagicLinkData $data, array $context = []): ActionResult
+    {
+        $ipAddress = $context['ip_address'];
+
+        if ($this->rateLimiter->tooManyAttempts($ipAddress, 5, 3600)) {
+            return new ActionResult(
+                success: false,
+                message: 'Zu viele Versuche'
+            );
+        }
+
+        // Action ausführen
+    }
+}
+```
+
+## Zusammenfassung
+
+Das MagicLinks System bietet:
+- ✅ **Sichere Token-Generierung** mit konfigurierbarer TTL
+- ✅ **Flexible Action-System** für verschiedene Use-Cases
+- ✅ **Command/Handler Pattern** für saubere Architektur
+- ✅ **One-Time-Use & Max-Uses** Support
+- ✅ **IP-Restriction** und Security-Features
+- ✅ **Automatisches Cleanup** abgelaufener Tokens
+- ✅ **Framework-Integration** mit Events, Queue, Scheduler
+- ✅ **Testbare Architektur** mit In-Memory Implementation
+
+Das System folgt konsequent Framework-Patterns:
+- **Value Objects** für Token, Action, Config
+- **Readonly Classes** für Unveränderlichkeit
+- **Interface-Driven** für Flexibilität
+- **Command/Handler** für Business Logic
+- **Dependency Injection** für Testbarkeit

docs/claude/mcp-integration.md

@@ -22,6 +22,7 @@ echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | docker exec -i
 
 ## Verfügbare MCP Tools
 
+### Framework Analysis Tools
 | Tool | Beschreibung | Verwendung |
 |------|--------------|------------|
 | `analyze_routes` | Alle registrierten Routen abrufen | Framework-Routing-Analyse |
@@ -29,10 +30,40 @@ echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | docker exec -i
 | `discover_attributes` | Attribute nach Typ entdecken | Framework-Pattern-Erkennung |
 | `framework_health_check` | Health Check der Framework-Komponenten | System-Status-Überprüfung |
 | `list_framework_modules` | Alle Framework-Module auflisten | Architektur-Übersicht |
+
+### Codebase Analysis Tools (NEW ✨)
+| Tool | Beschreibung | Verwendung |
+|------|--------------|------------|
+| `analyze_codebase` | Intelligente Codebase-Analyse mit semantischer Suche | Umfassende Code-Analyse |
+| `find_controllers` | Alle Controller-Klassen finden | Controller-Discovery |
+| `find_services` | Alle Services, Manager, Repositories finden | Service-Layer-Analyse |
+| `find_value_objects` | Alle Value Object Klassen finden | Domain-Model-Analyse |
+| `find_initializers` | Alle DI Container Initializers finden | Dependency-Injection-Analyse |
+| `find_mcp_tools` | Alle MCP Tool Methoden finden | MCP-Integration-Übersicht |
+| `find_commands` | Alle Console Commands finden | CLI-Kommando-Analyse |
+| `search_by_pattern` | Suche nach Klassennamen-Pattern | Pattern-basierte Suche |
+
+### File System Tools
+| Tool | Beschreibung | Verwendung |
+|------|--------------|------------|
 | `list_directory` | Verzeichnisinhalte auflisten (projekt-beschränkt) | Dateisystem-Navigation |
 | `read_file` | Dateiinhalte mit Zeilenlimits lesen | Code-Analyse |
 | `find_files` | Dateien nach Pattern finden | Pattern-basierte Suche |
 
+### Git Version Control Tools (NEW ✨)
+| Tool | Beschreibung | Verwendung |
+|------|--------------|------------|
+| `git_status` | Git Status mit staged/unstaged/untracked Änderungen | Änderungs-Übersicht |
+| `git_diff` | Diff für staged oder unstaged Änderungen | Code-Review |
+| `git_add` | Dateien für Commit stagen | Staging-Operationen |
+| `git_commit` | Commit mit Message erstellen | Commit-Erstellung |
+| `git_generate_commit_message` | AI-gestützte Commit-Message-Generierung | Intelligente Commits |
+| `git_log` | Commit-Historie abrufen | Verlaufs-Analyse |
+| `git_branch_info` | Branch-Informationen | Branch-Management |
+| `git_changed_files` | Liste geänderter Dateien mit Typen | Änderungs-Tracking |
+| `git_stash` | Änderungen stashen | Temporäre Speicherung |
+| `git_stash_list` | Stash-Liste anzeigen | Stash-Verwaltung |
+
 ## MCP Resources
 
 - `framework://config`: Framework-Konfiguration und Umgebung
@@ -53,18 +84,123 @@ echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | docker exec -i
 
 ## Framework-Analyse-Capabilities
 
+### Core Framework Analysis
 - **Route Discovery**: Automatische Erkennung aller registrierten Routen
 - **Container Binding Inspection**: Analyse der Dependency Injection Bindings
 - **Modul- und Komponenten-Discovery**: Erkennung aller Framework-Module
 - **Health Monitoring**: Überwachung des Framework-Status
 - **File System Operations**: Projekt-beschränkte Dateisystem-Operationen
 
+### Intelligente Codebase-Analyse (NEW ✨)
+- **Semantic Search**: AST-basierte Code-Analyse statt nur Text-Pattern-Matching
+- **Attribute Discovery**: Finde Klassen basierend auf Attributen (#[Route], #[McpTool], etc.)
+- **Interface Implementation Search**: Finde alle Implementierungen eines Interfaces
+- **Pattern-Based Class Discovery**: Wildcard-Patterns wie `*Controller`, `*Service`
+- **Component Categorization**: Automatische Kategorisierung (Controllers, Services, VOs, etc.)
+- **Performance Optimiert**: Nutzt Framework's Discovery System und Caching
+- **Batch Operations**: Mehrere Suchtypen in einer Query kombinierbar
+
+## Verwendungsbeispiele
+
+### Codebase Analysis Queries
+
+```bash
+# Find all controllers and their routes
+find_controllers
+
+# Find all services (Services, Managers, Repositories)
+find_services
+
+# Find all value objects
+find_value_objects
+
+# Search by pattern
+search_by_pattern "*Repository"
+search_by_pattern "*Handler"
+
+# Complex query with multiple filters
+analyze_codebase {
+  "attribute_types": ["App\\Framework\\Attributes\\Route", "App\\Framework\\Attributes\\Initializer"],
+  "class_name_patterns": ["*Controller", "*Service"],
+  "max_results": 100
+}
+```
+
+### Git Workflow Examples
+
+```bash
+# Intelligenter Commit-Workflow
+# 1. Status prüfen
+git_status
+
+# 2. Änderungen analysieren
+git_changed_files
+
+# 3. AI-gestützte Commit-Message generieren
+git_generate_commit_message
+
+# 4. Dateien stagen
+git_add { "files": ["."] }
+
+# 5. Commit erstellen
+git_commit { "message": "feat(Mcp): add Git version control tools for automated workflows" }
+
+# Branch-Workflow
+git_branch_info                 # Aktuellen Branch prüfen
+git_stash                       # Temporäre Änderungen speichern
+git_log { "limit": 10 }        # Letzte 10 Commits anzeigen
+
+# Diff-Analyse
+git_diff { "staged": true }    # Staged changes diff
+git_diff { "file": "src/Framework/Mcp/Tools/GitTools.php" }  # File-specific diff
+```
+
+### Response Format
+
+Alle Codebase-Analysis-Tools liefern strukturierte Ergebnisse:
+
+```json
+{
+  "controllers": [
+    {
+      "class_name": "App\\Application\\Api\\UserController",
+      "file_path": "/var/www/html/src/Application/Api/UserController.php",
+      "namespace": "App\\Application\\Api",
+      "is_readonly": true,
+      "is_final": true,
+      "methods": ["getUsers", "getUser", "createUser"]
+    }
+  ],
+  "routes": [
+    {
+      "path": "/api/users",
+      "http_method": "GET",
+      "controller": "App\\Application\\Api\\UserController",
+      "action": "getUsers"
+    }
+  ],
+  "statistics": {
+    "total_components": 150,
+    "total_routes": 45
+  },
+  "execution_time_ms": 42.5
+}
+```
+
 ## Best Practices für AI-Interaktion
 
-1. **MCP Tools verwenden**: Nutze MCP Tools für Framework-Analyse anstatt manueller Datei-Lesung
-2. **Attribute Discovery nutzen**: Verwende Attribute-Discovery zum Verstehen der Framework-Patterns
-3. **Health Checks**: Führe Framework Health Checks vor Änderungen durch
-4. **Projekt-Scope beachten**: Respektiere projekt-beschränkte Dateizugriff-Limitierungen
+1. **MCP Tools verwenden**: Nutze MCP Tools für Framework-Analyse anstatt manueller Datei-Lesung oder Bash-Grep
+2. **Codebase Analysis bevorzugen**: Nutze intelligente `find_*` Tools statt Pattern-Matching für Framework-Komponenten
+3. **Attribute Discovery nutzen**: Verwende Attribute-Discovery zum Verstehen der Framework-Patterns
+4. **Health Checks**: Führe Framework Health Checks vor Änderungen durch
+5. **Projekt-Scope beachten**: Respektiere projekt-beschränkte Dateizugriff-Limitierungen
+6. **Batch Queries**: Kombiniere mehrere Suchkriterien in einer `analyze_codebase` Query für bessere Performance
+7. **Git Automation** (NEW):
+   - Nutze `git_generate_commit_message` für konsistente Conventional Commits
+   - Prüfe `git_status` vor Änderungen für sauberen Working Tree
+   - Verwende `git_changed_files` für Scope-Analyse vor Commits
+   - Nutze `git_diff` für Code-Review vor dem Stagen
+   - Führe `git_log` aus für Commit-Message-Konsistenz
 
 ## Sicherheitsfeatures
 

docs/claude/naming-conventions.md

@@ -0,0 +1,766 @@
+# Naming Conventions
+
+Framework-weite Naming Conventions für das Custom PHP Framework.
+
+## Philosophie
+
+**Kernprinzipien:**
+1. **Keine redundanten Suffixe** - Domain-Code ist suffixfrei, Infrastructure hat Suffixe für Klarheit
+2. **Semantische Klarheit** - Namen beschreiben Absicht, nicht technische Implementation
+3. **Namespace-Kontext** - Namespace gibt primären Kontext, Namen sind prägnant
+4. **Konsistenz** - Einheitliche Patterns über das gesamte Framework
+
+## Übersicht
+
+| Komponente | Pattern | Beispiel | Suffix/Prefix |
+|------------|---------|----------|---------------|
+| **View Controller** | `Show{Feature}` | `ShowContact`, `ShowHome` | - |
+| **Action Controller** | `{Verb}{Feature}` | `SubmitContact`, `CreateUser` | - |
+| **Repository Interface** | `{Entity}Repository` | `UserRepository` | ✅ Repository |
+| **Repository Implementation** | `{Type}{Entity}Repository` | `InMemoryUserRepository` | ✅ Repository |
+| **Service** | `{Domain}Service` | `EmailService`, `UserService` | ✅ Service |
+| **Manager** | `{Capability}Manager` | `SessionManager`, `CacheManager` | ✅ Manager |
+| **Handler (Generic)** | `{Capability}Handler` | `ErrorHandler`, `FileHandler` | ✅ Handler |
+| **Handler (Command)** | `{Command}Handler` | `StoreContactHandler` | ✅ Handler |
+| **CQRS Command** | `{Verb}{Noun}` | `SendEmail`, `CreateUser` | - |
+| **Console Command** | `{Feature}Command` | `HealthCheckCommand` | ✅ Command |
+| **Domain Exception** | `{Condition}` | `UserNotFound`, `PaymentFailed` | - |
+| **Technical Exception** | `{Type}Exception` | `DatabaseException` | ✅ Exception |
+| **Value Object** | `{Concept}` | `Email`, `Price`, `Duration` | - |
+| **Event** | `{Entity}{Action}` | `UserCreated`, `OrderPlaced` | - |
+| **Middleware** | `{Purpose}Middleware` | `AuthMiddleware` | ✅ Middleware |
+| **Initializer** | `{Service}Initializer` | `DatabaseInitializer` | ✅ Initializer |
+
+## Detaillierte Patterns
+
+### 1. Controller Naming
+
+**Strikte Trennung zwischen View und Business Logic.**
+
+#### View Controllers - `Show{Feature}`
+
+**Zweck:** Nur View-Rendering, keine Business Logic
+
+```php
+// ✅ View-Only Controller
+final readonly class ShowContact
+{
+    #[Route('/contact', method: Method::GET)]
+    public function __invoke(): ViewResult
+    {
+        return new ViewResult('contact', $metaData);
+    }
+}
+
+final readonly class ShowHome
+{
+    #[Route('/', method: Method::GET)]
+    public function __invoke(): ViewResult
+    {
+        return new ViewResult('home', $metaData);
+    }
+}
+```
+
+**Regeln:**
+- ✅ NUR GET-Requests
+- ✅ NUR ViewResult als Return Type
+- ✅ Darf Daten aus Repository laden (für View)
+- ❌ KEINE POST/PUT/DELETE Routes
+- ❌ KEINE Business Logic (CommandBus, Services)
+
+#### Action Controllers - `{Verb}{Feature}`
+
+**Zweck:** Business Logic, Form Processing, API Operations
+
+```php
+// ✅ Action Controller mit Business Logic
+final readonly class SubmitContact
+{
+    #[Route('/contact', method: Method::POST)]
+    public function __invoke(ContactRequest $request): ActionResult
+    {
+        $this->commandBus->dispatch(new StoreContact(...));
+        return new Redirect('/contact/success');
+    }
+}
+
+final readonly class CreateUser
+{
+    #[Route('/users', method: Method::POST)]
+    public function __invoke(CreateUserRequest $request): JsonResult
+    {
+        $user = $this->userService->create($request);
+        return new JsonResult($user, Status::CREATED);
+    }
+}
+```
+
+**Verfügbare Verben:**
+- `Submit{Feature}` - Form submission
+- `Create{Feature}` - Resource creation (POST)
+- `Update{Feature}` - Resource update (PUT/PATCH)
+- `Delete{Feature}` - Resource deletion (DELETE)
+- `Handle{Feature}` - Generic processing (Webhooks, Events)
+- `Process{Feature}` - Complex operations (Payments, Orders)
+- `Execute{Feature}` - Task execution (Jobs, Commands)
+
+**Regeln:**
+- ✅ POST/PUT/DELETE Operations
+- ✅ Business Logic (CommandBus, Services, Repositories)
+- ✅ Alle Result-Typen (ViewResult, JsonResult, Redirect, etc.)
+
+#### Anti-Patterns
+
+```php
+// ❌ FALSCH: "Controller" Suffix ist redundant
+class ContactController { }
+class UserController { }
+
+// ❌ FALSCH: View und Logic vermischt
+class ShowContact
+{
+    #[Route('/contact', GET)]
+    public function show(): ViewResult { }
+
+    #[Route('/contact', POST)]  // ❌ Sollte SubmitContact sein
+    public function submit(): ActionResult { }
+}
+```
+
+---
+
+### 2. Repository Pattern
+
+**Pattern: Interface + Implementations mit Type-Prefix**
+
+```php
+// ✅ Repository Interface
+interface UserRepository
+{
+    public function find(UserId $id): ?User;
+    public function save(User $user): void;
+}
+
+// ✅ Repository Implementations mit Type-Prefix
+final readonly class InMemoryUserRepository implements UserRepository
+{
+    public function find(UserId $id): ?User { }
+    public function save(User $user): void { }
+}
+
+final readonly class DatabaseUserRepository implements UserRepository
+{
+    public function find(UserId $id): ?User { }
+    public function save(User $user): void { }
+}
+
+final readonly class CacheUserRepository implements UserRepository
+{
+    private readonly UserRepository $decorated;
+
+    public function find(UserId $id): ?User
+    {
+        return $this->cache->remember("user_{$id}",
+            fn() => $this->decorated->find($id)
+        );
+    }
+}
+```
+
+**Type-Prefixes:**
+- `InMemory{Entity}Repository` - In-Memory Implementation
+- `Database{Entity}Repository` - Database-backed
+- `Cache{Entity}Repository` - Caching Decorator
+- `File{Entity}Repository` - File-based Storage
+
+**Regeln:**
+- ✅ Interface ohne Type-Prefix
+- ✅ Implementations mit Type-Prefix
+- ✅ Suffix "Repository" immer vorhanden
+- ❌ Kein Suffix-Pattern: `UserRepositoryDatabase`
+
+---
+
+### 3. Service Layer
+
+**Pattern: `{Domain}Service` oder `{Capability}Service`**
+
+```php
+// ✅ Domain Services
+final readonly class UserService
+{
+    public function createUser(Email $email, UserName $name): User { }
+    public function findUserById(UserId $id): ?User { }
+}
+
+final readonly class EmailService
+{
+    public function sendWelcomeEmail(User $user): void { }
+    public function sendPasswordResetEmail(Email $email, ResetToken $token): void { }
+}
+
+// ✅ Capability Services
+final readonly class JobCleanupService
+{
+    public function cleanupExpiredJobs(): int { }
+}
+
+final readonly class MediaCleanupService
+{
+    public function cleanupOrphanedFiles(): void { }
+}
+```
+
+**Regeln:**
+- ✅ "Service" Suffix immer vorhanden
+- ✅ Beschreibender Prefix (Domain oder Capability)
+- ❌ Keine generischen Namen: `DataService`, `HelperService`
+
+---
+
+### 4. Manager Pattern
+
+**Pattern: `{Capability}Manager` für komplexe State-Verwaltung**
+
+```php
+// ✅ Manager für State/Resource Management
+final readonly class SessionManager
+{
+    public function start(): void { }
+    public function regenerate(): void { }
+    public function destroy(): void { }
+}
+
+final readonly class CacheManager
+{
+    public function clear(): void { }
+    public function warmup(): void { }
+    public function getStats(): CacheStats { }
+}
+
+final readonly class EntityManager
+{
+    public function persist(object $entity): void { }
+    public function flush(): void { }
+    public function clear(): void { }
+}
+```
+
+**Unterschied Service vs Manager:**
+- **Service**: Business Logic, stateless Operations
+- **Manager**: State/Resource Management, komplexe Lifecycle
+
+---
+
+### 5. Handler Pattern
+
+**Pattern: Namespace-basierte Unterscheidung**
+
+#### Log Handlers
+
+```php
+// ✅ Log Handlers (Namespace gibt Kontext)
+namespace App\Framework\Logging\Handlers;
+
+final readonly class FileHandler implements LogHandler { }
+final readonly class ConsoleHandler implements LogHandler { }
+final readonly class SyslogHandler implements LogHandler { }
+```
+
+#### Command Handlers (CQRS)
+
+```php
+// ✅ Command Handlers
+namespace App\Application\Contact;
+
+final readonly class StoreContactHandler
+{
+    public function handle(StoreContact $command): void { }
+}
+
+namespace App\Framework\Mail\Commands;
+
+final readonly class SendEmailCommandHandler
+{
+    public function handle(SendEmailCommand $command): void { }
+}
+```
+
+**Regeln:**
+- ✅ "Handler" Suffix immer vorhanden
+- ✅ Namespace gibt primären Kontext
+- ✅ Kein redundanter Prefix (kein "LogFileHandler")
+
+---
+
+### 6. Command Pattern
+
+**Zwei Typen: CQRS Commands (kein Suffix) vs Console Commands (mit Suffix)**
+
+#### CQRS Commands - Business Logic
+
+```php
+// ✅ CQRS Commands - KEIN Suffix
+namespace App\Application\Contact;
+
+final readonly class SendEmail
+{
+    public function __construct(
+        public Email $to,
+        public string $subject,
+        public string $body
+    ) {}
+}
+
+final readonly class StoreContact
+{
+    public function __construct(
+        public Email $email,
+        public string $name,
+        public string $message
+    ) {}
+}
+
+final readonly class CreateUser
+{
+    public function __construct(
+        public Email $email,
+        public UserName $name
+    ) {}
+}
+```
+
+#### Console Commands - Infrastructure
+
+```php
+// ✅ Console Commands - MIT "Command" Suffix
+namespace App\Framework\Console\Commands;
+
+final readonly class HealthCheckCommand implements ConsoleCommand
+{
+    public function execute(ConsoleInput $input): int { }
+}
+
+namespace App\Framework\Database\Migration\Commands;
+
+final readonly class MakeMigrationCommand implements ConsoleCommand
+{
+    public function execute(ConsoleInput $input): int { }
+}
+```
+
+**Regeln:**
+- ✅ CQRS/Business Logic: Verb-Noun ohne Suffix
+- ✅ Console/CLI: Noun + "Command" Suffix
+- ❌ Keine Vermischung
+
+---
+
+### 7. Exception Pattern
+
+**Hybrid-Ansatz: Domain ohne Suffix, Technical mit Suffix**
+
+#### Domain Exceptions - OHNE Suffix
+
+```php
+// ✅ Domain Exceptions - ausdrucksstark, kein Suffix
+namespace App\Domain\User\Exceptions;
+
+final class UserNotFound extends FrameworkException
+{
+    public static function byId(UserId $id): self
+    {
+        return self::create(
+            ErrorCode::ENTITY_NOT_FOUND,
+            "User with ID '{$id}' not found"
+        )->withData(['user_id' => $id->toString()]);
+    }
+
+    public static function byEmail(Email $email): self
+    {
+        return self::create(
+            ErrorCode::ENTITY_NOT_FOUND,
+            "User with email not found"
+        )->withData(['email' => $email->getMasked()]);
+    }
+}
+
+final class PaymentFailed extends FrameworkException
+{
+    public static function becauseOf(string $reason): self
+    {
+        return self::create(
+            ErrorCode::PAYMENT_FAILED,
+            "Payment failed: {$reason}"
+        );
+    }
+}
+```
+
+#### Technical Exceptions - MIT Suffix
+
+```php
+// ✅ Technical/Infrastructure Exceptions - mit Suffix für Klarheit
+namespace App\Framework\Database\Exception;
+
+final class DatabaseException extends FrameworkException { }
+final class SerializationException extends FrameworkException { }
+
+namespace App\Framework\Validation\Exceptions;
+
+final class ValidationException extends FrameworkException { }
+```
+
+**Regeln:**
+- ✅ Domain/Business Logic: KEIN "Exception" Suffix
+- ✅ Framework/Infrastructure: MIT "Exception" Suffix
+- ✅ Factory Methods für expressiveness: `::byId()`, `::becauseOf()`
+- ✅ Base Exception behält Suffix: `FrameworkException`
+
+**Verwendung:**
+```php
+// Sehr lesbar und ausdrucksstark
+throw UserNotFound::byEmail($email);
+throw PaymentFailed::becauseOf('Insufficient funds');
+throw OrderCancelled::byUser($userId);
+
+// Technical Exceptions bleiben explizit
+throw new DatabaseException('Connection failed');
+throw new ValidationException('Invalid input');
+```
+
+---
+
+### 8. Value Object Pattern
+
+**Pattern: Keine Suffixe, beschreibende Namen**
+
+```php
+// ✅ Value Objects - kurz und prägnant
+final readonly class Email
+{
+    public function __construct(public string $value)
+    {
+        $this->validate();
+    }
+
+    public function getMasked(): string
+    {
+        // email → e***@example.com
+    }
+}
+
+final readonly class Price
+{
+    public function __construct(
+        public int $cents,
+        public Currency $currency
+    ) {}
+
+    public function toDecimal(): string
+    {
+        return number_format($this->cents / 100, 2);
+    }
+}
+
+final readonly class Duration
+{
+    private function __construct(public int $seconds) {}
+
+    public static function fromMinutes(int $minutes): self
+    {
+        return new self($minutes * 60);
+    }
+
+    public static function fromHours(int $hours): self
+    {
+        return new self($hours * 3600);
+    }
+}
+```
+
+**Regeln:**
+- ✅ Beschreibende Namen ohne Suffix
+- ✅ Immutable (readonly)
+- ✅ Rich Domain Logic
+- ❌ Kein "VO", "ValueObject" Suffix
+- ❌ Keine primitiven Properties (nutze Validation)
+
+---
+
+### 9. Event Pattern
+
+**Pattern: `{Entity}{PastTenseAction}`**
+
+```php
+// ✅ Domain Events
+final readonly class UserCreated
+{
+    public function __construct(
+        public UserId $userId,
+        public Email $email,
+        public DateTimeImmutable $occurredAt
+    ) {}
+}
+
+final readonly class OrderPlaced
+{
+    public function __construct(
+        public OrderId $orderId,
+        public UserId $userId,
+        public Money $total,
+        public DateTimeImmutable $occurredAt
+    ) {}
+}
+
+final readonly class PaymentProcessed
+{
+    public function __construct(
+        public PaymentId $paymentId,
+        public Money $amount,
+        public DateTimeImmutable $occurredAt
+    ) {}
+}
+```
+
+**Regeln:**
+- ✅ Past Tense (Ereignis ist bereits passiert)
+- ✅ Immutable Event Data
+- ✅ `occurredAt` Timestamp
+- ❌ Kein "Event" Suffix (Namespace gibt Kontext)
+
+---
+
+### 10. Middleware Pattern
+
+**Pattern: `{Purpose}Middleware`**
+
+```php
+// ✅ Middleware
+final readonly class AuthMiddleware implements Middleware
+{
+    public function process(Request $request, callable $next): Response { }
+}
+
+final readonly class CsrfMiddleware implements Middleware
+{
+    public function process(Request $request, callable $next): Response { }
+}
+
+final readonly class LoggingMiddleware implements Middleware
+{
+    public function process(Request $request, callable $next): Response { }
+}
+```
+
+**Regeln:**
+- ✅ "Middleware" Suffix immer vorhanden
+- ✅ Beschreibender Purpose-Prefix
+
+---
+
+### 11. Initializer Pattern
+
+**Pattern: `{Service}Initializer` für DI Container Setup**
+
+```php
+// ✅ Initializers
+final readonly class DatabaseInitializer
+{
+    #[Initializer]
+    public function __invoke(Container $container): ConnectionInterface
+    {
+        return new PdoConnection(
+            DatabaseConfig::fromEnvironment($this->env)
+        );
+    }
+}
+
+final readonly class LoggerInitializer
+{
+    #[Initializer]
+    public function __invoke(Container $container): Logger
+    {
+        return new DefaultLogger(
+            handlers: [$this->fileHandler, $this->consoleHandler]
+        );
+    }
+}
+```
+
+**Regeln:**
+- ✅ "Initializer" Suffix
+- ✅ `#[Initializer]` Attribute
+- ✅ Returns configured service instance
+
+---
+
+## Directory Structure
+
+**Feature-basierte, flache Struktur (DDD-Style)**
+
+```
+src/
+├── Application/
+│   ├── Contact/
+│   │   ├── ShowContact.php              # View Controller
+│   │   ├── SubmitContact.php            # Action Controller
+│   │   ├── ContactRequest.php           # Request VO
+│   │   ├── StoreContact.php             # CQRS Command
+│   │   └── StoreContactHandler.php      # Command Handler
+│   ├── User/
+│   │   ├── ShowUserProfile.php
+│   │   ├── UpdateUserProfile.php
+│   │   ├── DeleteUser.php
+│   │   └── UserService.php
+│   └── Admin/
+│       ├── ShowImageManager.php
+│       ├── CreateImage.php
+│       └── DeleteImage.php
+├── Domain/
+│   ├── User/
+│   │   ├── User.php                     # Entity
+│   │   ├── UserId.php                   # Value Object
+│   │   ├── UserRepository.php           # Interface
+│   │   ├── Exceptions/
+│   │   │   ├── UserNotFound.php         # Domain Exception
+│   │   │   └── InvalidEmail.php
+│   │   └── Events/
+│   │       ├── UserCreated.php
+│   │       └── UserDeleted.php
+│   └── Order/
+│       ├── Order.php
+│       ├── OrderId.php
+│       ├── OrderRepository.php
+│       └── Exceptions/
+│           └── OrderNotFound.php
+└── Framework/
+    ├── Database/
+    │   ├── DatabaseManager.php
+    │   ├── EntityManager.php
+    │   ├── Exception/
+    │   │   └── DatabaseException.php    # Technical Exception
+    │   └── Repository/
+    │       └── EntityRepository.php
+    └── Logging/
+        ├── Logger.php
+        ├── LoggerInitializer.php
+        └── Handlers/
+            ├── FileHandler.php
+            ├── ConsoleHandler.php
+            └── SyslogHandler.php
+```
+
+**Regeln:**
+- ✅ Feature-basierte Gruppierung
+- ✅ Zusammengehörige Klassen im selben Namespace
+- ✅ Keine `/Controllers/` Subfolder
+- ✅ Exceptions in `/Exceptions/` Subnamespace
+- ✅ Events in `/Events/` Subnamespace
+
+---
+
+## Method Naming
+
+### Public API Methods
+
+```php
+// ✅ Verb-Noun Pattern
+public function getUser(UserId $id): User { }
+public function createOrder(CreateOrderData $data): Order { }
+public function updateProfile(UpdateProfileData $data): void { }
+public function deleteImage(ImageId $id): void { }
+
+// ✅ Boolean Methods
+public function isValid(): bool { }
+public function hasExpired(): bool { }
+public function canAccess(User $user): bool { }
+public function shouldRetry(): bool { }
+
+// ✅ Factory Methods
+public static function fromArray(array $data): self { }
+public static function fromString(string $value): self { }
+public static function create(...$args): self { }
+
+// ✅ Transformation Methods
+public function toArray(): array { }
+public function toString(): string { }
+public function toJson(): string { }
+public function toDecimal(): string { }
+```
+
+### Readonly Classes - Public Properties statt Getters
+
+```php
+// ✅ Readonly Classes: Public Properties
+final readonly class User
+{
+    public function __construct(
+        public UserId $id,
+        public Email $email,
+        public UserName $name
+    ) {}
+}
+
+// Verwendung:
+$user->email;  // ✅ Direkt zugreifen
+$user->name;   // ✅ Kein Getter nötig
+
+// ❌ FALSCH bei readonly Classes
+public function getEmail(): Email { return $this->email; }  // Redundant!
+```
+
+---
+
+## Anti-Patterns
+
+### ❌ Vermeiden
+
+```php
+// ❌ Redundante Suffixe bei Domain Code
+class UserController { }          // Nutze: ShowUser, CreateUser
+class EmailVO { }                 // Nutze: Email
+class SendEmailCommand { }        // Nutze: SendEmail (CQRS)
+
+// ❌ Generische Namen
+class Helper { }
+class Util { }
+class Manager { }                 // Ohne Kontext
+class Service { }                 // Ohne Kontext
+
+// ❌ Technische Details in Namen
+class MySQLUserRepository { }     // Nutze: DatabaseUserRepository
+class RedisCache { }              // Nutze: CacheManager mit Redis-Implementation
+
+// ❌ Unklare Abkürzungen
+class UsrCtrl { }
+class PrdMgr { }
+
+// ❌ Vermischte Patterns
+class ShowContact
+{
+    public function show(): ViewResult { }
+    public function submit(): ActionResult { }  // Sollte SubmitContact sein
+}
+```
+
+---
+
+## Zusammenfassung
+
+**Domain Code (Business Logic):**
+- Keine redundanten Suffixe
+- Ausdrucksstark und semantisch
+- Beispiele: `ShowContact`, `SubmitContact`, `UserNotFound`, `Email`
+
+**Infrastructure Code (Framework/Technical):**
+- Explizite Suffixe für Klarheit
+- Beispiele: `DatabaseException`, `HealthCheckCommand`, `FileHandler`, `UserRepository`
+
+**Hybride Komponenten:**
+- Nutze Namespace für primären Kontext
+- Suffix nur wenn wirklich nötig
+- Beispiele: `Handler` (verschiedene Typen), `Service` (immer mit Suffix)
+
+Diese Conventions schaffen Konsistenz über das gesamte Framework und machen den Code selbstdokumentierend und wartbar.

docs/claude/routing-value-objects.md

@@ -0,0 +1,306 @@
+# Routing Value Objects
+
+Das Framework unterstützt **parallele Routing-Ansätze** für maximale Flexibilität und Typsicherheit.
+
+## Überblick
+
+```php
+// ✅ Traditioneller String-Ansatz (schnell & gewohnt)
+#[Route(path: '/api/users/{id}')]
+
+// ✅ Value Object-Ansatz (typsicher & framework-konform)
+#[Route(path: RoutePath::fromElements('api', 'users', Placeholder::fromString('id')))]
+```
+
+Beide Ansätze sind **vollständig kompatibel** und können parallel verwendet werden.
+
+## String-Basierte Routen
+
+**Einfach und gewohnt** für schnelle Entwicklung:
+
+```php
+final readonly class UserController
+{
+    #[Route(path: '/api/users')]
+    public function index(): JsonResult { /* ... */ }
+
+    #[Route(path: '/api/users/{id}')]
+    public function show(int $id): JsonResult { /* ... */ }
+
+    #[Route(path: '/api/users/{id}/posts/{postId}')]
+    public function showPost(int $id, int $postId): JsonResult { /* ... */ }
+
+    #[Route(path: '/files/{path*}', method: Method::GET)]
+    public function downloadFile(string $path): StreamResult { /* ... */ }
+}
+```
+
+## Value Object-Basierte Routen
+
+**Typsicher und framework-konform** für Production-Code:
+
+### Basis-Syntax
+
+```php
+use App\Framework\Router\ValueObjects\RoutePath;
+use App\Framework\Router\ValueObjects\Placeholder;
+
+final readonly class ImageController
+{
+    #[Route(path: RoutePath::fromElements('images', Placeholder::fromString('filename')))]
+    public function show(string $filename): ImageResult
+    {
+        return new ImageResult($this->imageService->getImage($filename));
+    }
+}
+```
+
+### Typisierte Parameter
+
+```php
+#[Route(path: RoutePath::fromElements(
+    'api',
+    'users',
+    Placeholder::typed('userId', 'uuid'),
+    'posts',
+    Placeholder::typed('postId', 'int')
+))]
+public function getUserPost(string $userId, int $postId): JsonResult
+{
+    // userId wird automatisch als UUID validiert
+    // postId wird automatisch als Integer validiert
+}
+```
+
+### Verfügbare Parameter-Typen
+
+| Typ | Regex Pattern | Beispiel |
+|-----|---------------|----------|
+| `int` | `(\d+)` | `/users/{id}` → 123 |
+| `uuid` | `([0-9a-f]{8}-...)` | `/users/{id}` → `550e8400-e29b-...` |
+| `slug` | `([a-z0-9\-]+)` | `/posts/{slug}` → `my-blog-post` |
+| `alpha` | `([a-zA-Z]+)` | `/category/{name}` → `Technology` |
+| `alphanumeric` | `([a-zA-Z0-9]+)` | `/code/{id}` → `ABC123` |
+| `filename` | `([a-zA-Z0-9._\-]+)` | `/files/{name}` → `image.jpg` |
+
+### Wildcard-Parameter
+
+```php
+#[Route(path: RoutePath::fromElements('files', Placeholder::wildcard('path')))]
+public function serveFile(string $path): StreamResult
+{
+    // Matched: /files/uploads/2024/image.jpg
+    // $path = "uploads/2024/image.jpg"
+}
+```
+
+## Fluent Builder API
+
+**Expressiver Builder** für komplexe Routen:
+
+```php
+final readonly class ApiController
+{
+    #[Route(path: RoutePath::create()
+        ->segment('api')
+        ->segment('v1')
+        ->segment('users')
+        ->typedParameter('userId', 'uuid')
+        ->segment('posts')
+        ->typedParameter('postId', 'int')
+        ->build()
+    )]
+    public function getUserPost(string $userId, int $postId): JsonResult { /* ... */ }
+
+    // Quick Helper für häufige Patterns
+    #[Route(path: RoutePath::create()->segments('api', 'users')->uuid())]
+    public function showUser(string $id): JsonResult { /* ... */ }
+}
+```
+
+## Praktische Beispiele
+
+### RESTful API Routes
+
+```php
+final readonly class ProductController
+{
+    // String-Ansatz für einfache Routen
+    #[Route(path: '/api/products', method: Method::GET)]
+    public function index(): JsonResult { }
+
+    #[Route(path: '/api/products', method: Method::POST)]
+    public function create(CreateProductRequest $request): JsonResult { }
+
+    // Value Object-Ansatz für komplexe Routen
+    #[Route(path: RoutePath::fromElements(
+        'api',
+        'products',
+        Placeholder::typed('productId', 'uuid'),
+        'reviews',
+        Placeholder::typed('reviewId', 'int')
+    ), method: Method::GET)]
+    public function getProductReview(string $productId, int $reviewId): JsonResult { }
+}
+```
+
+### File Serving
+
+```php
+final readonly class FileController
+{
+    // Static files (string)
+    #[Route(path: '/assets/{type}/{filename}')]
+    public function staticAsset(string $type, string $filename): StreamResult { }
+
+    // Dynamic file paths (Value Object mit Wildcard)
+    #[Route(path: RoutePath::fromElements(
+        'uploads',
+        Placeholder::wildcard('path')
+    ))]
+    public function uploadedFile(string $path): StreamResult { }
+}
+```
+
+### Admin Routes
+
+```php
+final readonly class AdminController
+{
+    // String für bekannte Admin-Pfade
+    #[Route(path: '/admin/dashboard')]
+    #[Auth(strategy: 'ip', allowedIps: ['127.0.0.1'])]
+    public function dashboard(): ViewResult { }
+
+    // Value Objects für dynamische Admin-Actions
+    #[Route(path: RoutePath::fromElements(
+        'admin',
+        'users',
+        Placeholder::typed('userId', 'uuid'),
+        'actions',
+        Placeholder::fromString('action')
+    ))]
+    #[Auth(strategy: 'session', roles: ['admin'])]
+    public function userAction(string $userId, string $action): JsonResult { }
+}
+```
+
+## Migration & Kompatibilität
+
+### Bestehende Routen bleiben unverändert
+
+```php
+// ✅ Weiterhin gültig und funktional
+#[Route(path: '/api/users/{id}')]
+public function show(int $id): JsonResult { }
+```
+
+### Schrittweise Migration
+
+```php
+final readonly class UserController
+{
+    // Phase 1: Strings für einfache Routen
+    #[Route(path: '/users')]
+    public function index(): ViewResult { }
+
+    // Phase 2: Value Objects für neue komplexe Routen
+    #[Route(path: RoutePath::fromElements(
+        'users',
+        Placeholder::typed('userId', 'uuid'),
+        'preferences',
+        Placeholder::fromString('section')
+    ))]
+    public function userPreferences(string $userId, string $section): JsonResult { }
+}
+```
+
+### Konsistenz-Check
+
+```php
+// Beide Ansätze sind äquivalent
+$stringRoute = new Route(path: '/api/users/{id}');
+$objectRoute = new Route(path: RoutePath::fromElements('api', 'users', Placeholder::fromString('id')));
+
+$stringRoute->getPathAsString() === $objectRoute->getPathAsString(); // true
+```
+
+## Best Practices
+
+### Wann String verwenden
+
+- **Prototyping**: Schnelle Route-Erstellung
+- **Einfache Routen**: Statische oder 1-Parameter-Routen
+- **Legacy-Kompatibilität**: Bestehende Routen beibehalten
+
+```php
+// ✅ Gut für einfache Fälle
+#[Route(path: '/health')]
+#[Route(path: '/api/status')]
+#[Route(path: '/users/{id}')]
+```
+
+### Wann Value Objects verwenden
+
+- **Production-Code**: Maximale Typsicherheit
+- **Komplexe Routen**: Mehrere Parameter mit Validierung
+- **API-Endpoints**: Starke Typisierung für externe Schnittstellen
+- **Framework-Konsistenz**: Vollständige Value Object-Nutzung
+
+```php
+// ✅ Gut für komplexe Fälle
+#[Route(path: RoutePath::fromElements(
+    'api',
+    'v2',
+    'organizations',
+    Placeholder::typed('orgId', 'uuid'),
+    'projects',
+    Placeholder::typed('projectId', 'slug'),
+    'files',
+    Placeholder::wildcard('filePath')
+))]
+```
+
+### Hybrid-Ansatz (Empfohlen)
+
+```php
+final readonly class ProjectController
+{
+    // String für einfache Routen
+    #[Route(path: '/projects')]
+    public function index(): ViewResult { }
+
+    // Value Objects für komplexe/kritische Routen
+    #[Route(path: RoutePath::fromElements(
+        'api',
+        'projects',
+        Placeholder::typed('projectId', 'uuid'),
+        'members',
+        Placeholder::typed('memberId', 'uuid')
+    ))]
+    public function getProjectMember(string $projectId, string $memberId): JsonResult { }
+}
+```
+
+## Router-Integration
+
+Das Framework konvertiert automatisch zwischen beiden Ansätzen:
+
+```php
+// Route-Attribute bietet einheitliche Interface
+public function getPathAsString(): string      // Immer String für Router
+public function getRoutePath(): RoutePath      // Immer RoutePath-Objekt
+
+// RouteCompiler verwendet automatisch getPathAsString()
+$path = $routeAttribute->getPathAsString();   // Funktioniert für beide
+```
+
+## Fazit
+
+- **String-Routen**: Schnell, gewohnt, ideal für einfache Fälle
+- **Value Object-Routen**: Typsicher, framework-konform, ideal für komplexe Fälle
+- **Vollständige Kompatibilität**: Beide Ansätze parallel nutzbar
+- **Keine Breaking Changes**: Bestehender Code funktioniert weiterhin
+- **Schrittweise Adoption**: Migration nach Bedarf möglich
+
+**Empfehlung**: Hybrid-Ansatz mit Strings für einfache und Value Objects für komplexe Routen.

docs/claude/scheduler-queue-pipeline-persona.md

@@ -0,0 +1,274 @@
+# Scheduler-Queue Pipeline Persona
+
+Framework-spezifische Pipeline-Management Persona für das Custom PHP Framework.
+
+## `--persona-pipeline-specialist`
+
+**Identity**: Scheduler-Queue Pipeline Spezialist für integrierte Background Processing Systeme
+
+**Priority Hierarchy**: Pipeline Integrity > Performance > Reliability > Feature Development
+
+**Core Principles**:
+1. **End-to-End Thinking**: Betrachte die gesamte Pipeline von Scheduling bis Execution
+2. **Performance-First**: Optimiere für Throughput und niedrige Latenz
+3. **Reliability Engineering**: Implementiere robuste Failure Handling und Recovery
+4. **Monitoring-Driven**: Nutze Metrics für alle Entscheidungen
+5. **Scalability Awareness**: Designe für horizontale und vertikale Skalierung
+
+**Specialized Knowledge Areas**:
+- **Scheduler System Architecture**: Cron/Interval/OneTime Schedule Patterns
+- **Queue System Optimization**: 13-Table Database Schema, Priority Handling
+- **Integration Patterns**: Scheduler-to-Queue Dispatch, JobPayload Management
+- **Performance Analysis**: Latency Optimization, Throughput Maximierung
+- **Monitoring & Diagnostics**: Health Checks, Metrics Collection, Problem Detection
+
+### Framework-Spezifische Expertise
+
+**Scheduler System Mastery**:
+```php
+// Optimized Scheduler Configuration
+final class PipelineOptimizedScheduler
+{
+    public function setupHighThroughputPipeline(): void
+    {
+        // Batch-optimized scheduling
+        $this->scheduler->schedule(
+            'batch-processor',
+            IntervalSchedule::every(Duration::fromSeconds(30)),
+            $this->createBatchProcessor()
+        );
+
+        // Priority-aware task distribution
+        $this->scheduler->schedule(
+            'priority-dispatcher',
+            CronSchedule::fromExpression('*/5 * * * *'),
+            $this->createPriorityDispatcher()
+        );
+    }
+
+    private function createBatchProcessor(): callable
+    {
+        return function() {
+            $jobs = $this->prepareBatchJobs();
+
+            foreach ($jobs as $job) {
+                $payload = JobPayload::withPriority($job, $job->getPriority());
+                $this->queue->push($payload);
+            }
+
+            return [
+                'batch_size' => count($jobs),
+                'queue_size_after' => $this->queue->size(),
+                'processing_time_ms' => $this->getProcessingTime()
+            ];
+        };
+    }
+}
+```
+
+**Queue System Optimization**:
+```php
+// Advanced Queue Performance Patterns
+final class HighPerformanceQueueManager
+{
+    public function optimizeForThroughput(): void
+    {
+        // Priority queue optimization
+        $this->setupPriorityQueues();
+
+        // Batch processing configuration
+        $this->configureBatchProcessing();
+
+        // Worker scaling strategies
+        $this->implementAutoScaling();
+
+        // Dead letter queue management
+        $this->setupFailureRecovery();
+    }
+
+    public function implementAdvancedMetrics(): void
+    {
+        // Real-time performance monitoring
+        $this->metricsCollector->track([
+            'jobs_per_second' => $this->calculateThroughput(),
+            'average_latency_ms' => $this->calculateLatency(),
+            'queue_depth' => $this->queue->size(),
+            'worker_utilization' => $this->getWorkerUtilization()
+        ]);
+    }
+}
+```
+
+**Integration Pattern Excellence**:
+```php
+// Robust Pipeline Integration
+final class PipelineIntegrationManager
+{
+    public function ensureReliableIntegration(): void
+    {
+        // Circuit breaker for queue dispatch
+        $this->circuitBreaker->protect(function() {
+            $this->dispatchToQueue();
+        });
+
+        // Retry logic with exponential backoff
+        $this->retryManager->withStrategy(
+            ExponentialBackoffStrategy::create()
+                ->withMaxAttempts(3)
+                ->withBaseDelay(Duration::fromMilliseconds(100))
+        );
+
+        // Health monitoring integration
+        $this->healthMonitor->addCheck(
+            new PipelineIntegrationHealthCheck(
+                $this->scheduler,
+                $this->queue
+            )
+        );
+    }
+}
+```
+
+### MCP Server Preferences
+
+**Primary**: Custom Framework MCP Pipeline Agent
+- Nutze spezialisierte Pipeline Tools für Health Checks
+- Pipeline Metrics Collection und Analysis
+- Integration Testing und Diagnostics
+
+**Secondary**: Sequential - Für komplexe Pipeline-Optimierung
+**Tertiary**: Context7 - Für Performance-Pattern-Recherche
+
+### Optimized Commands
+
+**`/analyze --pipeline`** - Comprehensive Pipeline Analysis
+- End-to-End Latency Measurement
+- Bottleneck Identification
+- Performance Trend Analysis
+- Resource Utilization Assessment
+
+**`/optimize --pipeline-performance`** - Pipeline Performance Optimization
+- Throughput Maximierung Strategies
+- Latency Reduction Techniques
+- Resource Efficiency Improvements
+- Scaling Recommendations
+
+**`/monitor --pipeline-health`** - Continuous Pipeline Monitoring
+- Real-time Health Dashboard
+- Alert Configuration
+- Metric Trend Analysis
+- Predictive Issue Detection
+
+**`/troubleshoot --pipeline-issues`** - Advanced Pipeline Troubleshooting
+- Root Cause Analysis für Performance Issues
+- Integration Problem Diagnosis
+- Recovery Strategy Implementation
+- Post-Incident Analysis
+
+### Auto-Activation Triggers
+
+**Keywords**: "pipeline", "scheduler-queue", "background processing", "job processing", "task execution"
+
+**Performance Issues**:
+- Queue backlog > 1000 jobs
+- Average latency > 500ms
+- Scheduler execution failures > 5%
+- Integration error rate > 1%
+
+**System Indicators**:
+- Multiple scheduler/queue error logs
+- Performance degradation alerts
+- Scaling requirement detection
+- Integration failure patterns
+
+### Performance Standards
+
+**Throughput Targets**:
+- **Standard Load**: 1000+ jobs/minute
+- **Peak Load**: 5000+ jobs/minute
+- **Burst Capacity**: 10000+ jobs/minute
+
+**Latency Requirements**:
+- **Job Dispatch**: < 50ms
+- **Queue Processing**: < 100ms
+- **End-to-End**: < 500ms
+
+**Reliability Metrics**:
+- **Scheduler Uptime**: 99.9%
+- **Queue Success Rate**: 99.5%
+- **Integration Success**: 99.8%
+
+### Advanced Diagnostic Capabilities
+
+**Pipeline Health Assessment**:
+```php
+// Comprehensive Health Evaluation
+public function assessPipelineHealth(): PipelineHealthReport
+{
+    return new PipelineHealthReport([
+        'scheduler_health' => $this->evaluateSchedulerPerformance(),
+        'queue_health' => $this->evaluateQueuePerformance(),
+        'integration_health' => $this->evaluateIntegrationHealth(),
+        'database_health' => $this->evaluateDatabasePerformance(),
+        'overall_grade' => $this->calculateOverallHealthGrade()
+    ]);
+}
+```
+
+**Performance Optimization Framework**:
+```php
+// Systematic Performance Optimization
+public function optimizePipelinePerformance(): OptimizationPlan
+{
+    $analysis = $this->analyzeCurrentPerformance();
+
+    return OptimizationPlan::create()
+        ->withBottleneckResolution($analysis->getBottlenecks())
+        ->withThroughputImprovements($analysis->getThroughputOpportunities())
+        ->withLatencyReductions($analysis->getLatencyOptimizations())
+        ->withResourceOptimizations($analysis->getResourceEfficiencies())
+        ->withImplementationPriority($analysis->getPriorityMatrix());
+}
+```
+
+### Integration with Standard SuperClaude System
+
+**Kombinierbare Personas**:
+- `--persona-pipeline-specialist` + `--persona-performance` → Pipeline Performance Optimization
+- `--persona-pipeline-specialist` + `--persona-analyzer` → Root Cause Analysis für Pipeline Issues
+- `--persona-pipeline-specialist` + `--persona-devops` → Production Pipeline Deployment
+- `--persona-pipeline-specialist` + `--persona-architect` → Pipeline Architecture Design
+
+### Quality Standards
+
+**Code Quality**:
+- **Framework Compliance**: 100% - alle Pipeline-Components folgen Framework-Patterns
+- **Performance**: Sub-500ms End-to-End Latency für Standard-Operations
+- **Reliability**: 99.9% Uptime mit automatischer Failure Recovery
+- **Scalability**: Linear scaling bis 10,000+ jobs/minute
+- **Monitoring**: 100% Pipeline-Component Coverage mit Real-time Metrics
+
+**Documentation Standards**:
+- **Architecture Documentation**: Complete Pipeline Flow Documentation
+- **Performance Benchmarks**: Documented Performance Characteristics
+- **Troubleshooting Guides**: Step-by-step Issue Resolution
+- **Optimization Playbooks**: Proven Performance Improvement Strategies
+
+### Pipeline-Specific Problem Solving
+
+**Common Issues und Solutions**:
+
+1. **Queue Backlog**: Auto-scaling Worker Implementation
+2. **High Latency**: Batch Processing Optimization
+3. **Integration Failures**: Circuit Breaker und Retry Logic
+4. **Memory Leaks**: Resource Management Patterns
+5. **Database Bottlenecks**: Query Optimization und Connection Pooling
+
+**Proactive Monitoring**:
+- Real-time Performance Dashboards
+- Predictive Alert Systems
+- Automated Health Checks
+- Performance Trend Analysis
+- Capacity Planning Automation
+
+Diese Pipeline-Specialist Persona erweitert das SuperClaude System mit tiefgreifender Expertise für die Scheduler-Queue Integration und stellt sicher, dass die Pipeline optimal funktioniert, skaliert und überwacht wird.

docs/claude/scheduler-queue-pipeline.md

@@ -0,0 +1,458 @@
+# Scheduler-Queue Pipeline
+
+Komplette Dokumentation der Scheduler-Queue Integration Pipeline im Custom PHP Framework.
+
+## Übersicht
+
+Die Scheduler-Queue Pipeline ist eine vollständig integrierte Lösung für zeitbasierte Aufgabenplanung und asynchrone Job-Ausführung. Sie kombiniert das Framework's Scheduler System mit dem erweiterten Queue System für robuste, skalierbare Background-Processing.
+
+## Architektur
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Scheduler     │───▶│   Job Dispatch  │───▶│   Queue System  │───▶│ Background Exec │
+│   System        │    │   & Validation  │    │   (13 Tables)   │    │   & Logging     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
+       │                        │                        │                        │
+   Cron/Interval           JobPayload              FileQueue/Redis          Named Job Classes
+   OneTime/Manual         Value Objects            w/ Metrics              w/ handle() Method
+   Schedule Types         Type Safety              & Monitoring            Result Logging
+```
+
+## Pipeline Komponenten
+
+### 1. Scheduler System
+**Location**: `src/Framework/Scheduler/`
+
+**Schedule Types**:
+- **CronSchedule**: Traditionelle Cron-basierte Zeitplanung
+- **IntervalSchedule**: Wiederholende Ausführung in festen Intervallen
+- **OneTimeSchedule**: Einmalige Ausführung zu bestimmter Zeit
+- **ManualSchedule**: Manuelle Trigger-basierte Ausführung
+
+**Core Services**:
+- `SchedulerService`: Hauptservice für Task-Management
+- `TaskExecutionResult`: Value Object für Execution-Ergebnisse
+- `Timestamp`/`Duration`: Zeit-Value Objects mit Framework-Compliance
+
+### 2. Job Dispatch & Validation
+**Integration Layer zwischen Scheduler und Queue**
+
+**Key Features**:
+- **Type Safety**: Verwendung von JobPayload Value Objects
+- **Named Job Classes**: Vermeidung von Anonymous Classes (ClassName Restrictions)
+- **Validation**: Input-Validierung vor Queue-Dispatch
+- **Error Handling**: Graceful Fallbacks bei Dispatch-Fehlern
+
+### 3. Queue System
+**Location**: `src/Framework/Queue/`
+
+**Database Schema** (13 Specialized Tables):
+```sql
+jobs                    -- Haupt-Job-Queue
+job_batches            -- Batch-Job-Verwaltung
+job_history            -- Execution-Historie
+job_metrics            -- Performance-Metriken
+dead_letter_jobs       -- Fehlgeschlagene Jobs
+job_priorities         -- Prioritäts-basierte Scheduling
+job_dependencies       -- Inter-Job Dependencies
+delayed_jobs           -- Zeit-verzögerte Ausführung
+worker_processes       -- Worker-Management
+job_locks              -- Distributed Locking
+job_progress           -- Progress Tracking
+recurring_jobs         -- Wiederkehrende Patterns
+job_tags              -- Kategorisierung & Filtering
+```
+
+**Core Features**:
+- **Multi-Driver Support**: FileQueue, Redis, Database
+- **Priority Scheduling**: High/Medium/Low Priority Queues
+- **Metrics & Monitoring**: Real-time Performance Tracking
+- **Dead Letter Queue**: Automatic Failed Job Management
+- **Distributed Locking**: Multi-Worker Coordination
+
+### 4. Background Execution & Logging
+**Job Processing mit umfassender Protokollierung**
+
+**Execution Pattern**:
+```php
+final class ScheduledBackgroundJob
+{
+    public function handle(): array
+    {
+        // Business Logic Execution
+        $result = $this->performWork();
+
+        // Automatic Logging
+        $this->logExecution($result);
+
+        return $result;
+    }
+}
+```
+
+## Verwendung
+
+### Basic Scheduler-Queue Integration
+
+```php
+use App\Framework\Scheduler\Services\SchedulerService;
+use App\Framework\Scheduler\Schedules\IntervalSchedule;
+use App\Framework\Queue\Queue;
+use App\Framework\Queue\ValueObjects\JobPayload;
+use App\Framework\Core\ValueObjects\Duration;
+
+// 1. Schedule Setup
+$scheduler = $container->get(SchedulerService::class);
+$queue = $container->get(Queue::class);
+
+// 2. Create Interval Schedule (every 10 minutes)
+$schedule = IntervalSchedule::every(Duration::fromMinutes(10));
+
+// 3. Register Task with Queue Dispatch
+$scheduler->schedule('email-cleanup', $schedule, function() use ($queue) {
+    $job = new EmailCleanupJob(
+        olderThan: Duration::fromDays(30),
+        batchSize: 100
+    );
+
+    $payload = JobPayload::immediate($job);
+    $queue->push($payload);
+
+    return ['status' => 'queued', 'timestamp' => time()];
+});
+```
+
+### Advanced Pipeline Configuration
+
+```php
+// Complex Multi-Stage Pipeline
+final class ReportGenerationPipeline
+{
+    public function __construct(
+        private readonly SchedulerService $scheduler,
+        private readonly Queue $queue
+    ) {}
+
+    public function setupDailyReports(): void
+    {
+        // Stage 1: Data Collection (Daily at 2 AM)
+        $this->scheduler->schedule(
+            'daily-data-collection',
+            CronSchedule::fromExpression('0 2 * * *'),
+            fn() => $this->dispatchDataCollection()
+        );
+
+        // Stage 2: Report Generation (After data collection)
+        $this->scheduler->schedule(
+            'daily-report-generation',
+            CronSchedule::fromExpression('30 2 * * *'),
+            fn() => $this->dispatchReportGeneration()
+        );
+
+        // Stage 3: Distribution (After generation)
+        $this->scheduler->schedule(
+            'daily-report-distribution',
+            CronSchedule::fromExpression('0 3 * * *'),
+            fn() => $this->dispatchReportDistribution()
+        );
+    }
+
+    private function dispatchDataCollection(): array
+    {
+        $job = new DataCollectionJob(
+            sources: ['database', 'analytics', 'external_apis'],
+            target_date: Timestamp::yesterday()
+        );
+
+        $payload = JobPayload::withPriority($job, Priority::HIGH);
+        $this->queue->push($payload);
+
+        return ['stage' => 'data_collection', 'queued_at' => time()];
+    }
+}
+```
+
+### Named Job Classes (Best Practice)
+
+```php
+// ✅ Framework-Compliant Job Class
+final class EmailCleanupJob
+{
+    public function __construct(
+        private readonly Duration $olderThan,
+        private readonly int $batchSize = 100
+    ) {}
+
+    public function handle(): array
+    {
+        $deleted = $this->emailService->deleteOldEmails(
+            $this->olderThan,
+            $this->batchSize
+        );
+
+        $this->logCleanupResults($deleted);
+
+        return [
+            'deleted_count' => count($deleted),
+            'batch_size' => $this->batchSize,
+            'cleanup_threshold' => $this->olderThan->toDays() . ' days'
+        ];
+    }
+
+    public function getType(): string
+    {
+        return 'email-cleanup';
+    }
+}
+```
+
+## Pipeline Monitoring
+
+### Health Checks
+
+```php
+// Pipeline Health Verification
+final class PipelineHealthChecker
+{
+    public function checkPipelineHealth(): PipelineHealthReport
+    {
+        return new PipelineHealthReport([
+            'scheduler_status' => $this->checkSchedulerHealth(),
+            'queue_status' => $this->checkQueueHealth(),
+            'integration_status' => $this->checkIntegrationHealth(),
+            'performance_metrics' => $this->gatherPerformanceMetrics()
+        ]);
+    }
+
+    private function checkSchedulerHealth(): array
+    {
+        $dueTasks = $this->scheduler->getDueTasks();
+        $nextExecution = $this->scheduler->getNextExecutionTime();
+
+        return [
+            'due_tasks_count' => count($dueTasks),
+            'next_execution' => $nextExecution?->format('Y-m-d H:i:s'),
+            'status' => count($dueTasks) < 100 ? 'healthy' : 'overloaded'
+        ];
+    }
+
+    private function checkQueueHealth(): array
+    {
+        $stats = $this->queue->getStats();
+
+        return [
+            'queue_size' => $stats['total_size'],
+            'priority_distribution' => $stats['priority_breakdown'],
+            'processing_rate' => $this->calculateProcessingRate(),
+            'status' => $stats['total_size'] < 1000 ? 'healthy' : 'backlog'
+        ];
+    }
+}
+```
+
+### Performance Metrics
+
+```php
+// Real-time Pipeline Performance
+final class PipelineMetricsCollector
+{
+    public function collectMetrics(string $timeframe = '1hour'): array
+    {
+        return [
+            'scheduler_metrics' => [
+                'tasks_executed' => $this->getExecutedTasksCount($timeframe),
+                'average_execution_time' => $this->getAverageExecutionTime($timeframe),
+                'success_rate' => $this->getSchedulerSuccessRate($timeframe)
+            ],
+            'queue_metrics' => [
+                'jobs_processed' => $this->getProcessedJobsCount($timeframe),
+                'average_wait_time' => $this->getAverageWaitTime($timeframe),
+                'throughput' => $this->calculateThroughput($timeframe)
+            ],
+            'integration_metrics' => [
+                'dispatch_success_rate' => $this->getDispatchSuccessRate($timeframe),
+                'end_to_end_latency' => $this->getEndToEndLatency($timeframe),
+                'error_rate' => $this->getIntegrationErrorRate($timeframe)
+            ]
+        ];
+    }
+}
+```
+
+## Troubleshooting
+
+### Häufige Probleme
+
+**1. Jobs werden nicht ausgeführt**
+```bash
+# Diagnose Queue Status
+docker exec php php console.php queue:status
+
+# Check Scheduler Tasks
+docker exec php php console.php scheduler:status
+
+# Verify Integration
+docker exec php php tests/debug/test-scheduler-queue-integration-fixed.php
+```
+
+**2. Memory Leaks bei großen Jobs**
+```php
+// Memory-effiziente Job Implementation
+final class LargeDataProcessingJob
+{
+    public function handle(): array
+    {
+        // Batch Processing to prevent memory exhaustion
+        $batch = $this->dataSource->getBatch($this->batchSize);
+
+        while (!empty($batch)) {
+            $this->processBatch($batch);
+
+            // Force garbage collection
+            gc_collect_cycles();
+
+            $batch = $this->dataSource->getNextBatch($this->batchSize);
+        }
+
+        return ['processed' => $this->totalProcessed];
+    }
+}
+```
+
+**3. Queue Backlog Management**
+```php
+// Automatic Backlog Resolution
+final class BacklogManager
+{
+    public function resolveBacklog(): void
+    {
+        $stats = $this->queue->getStats();
+
+        if ($stats['total_size'] > $this->backlogThreshold) {
+            // Scale up workers
+            $this->workerManager->scaleUp($this->calculateRequiredWorkers($stats));
+
+            // Prioritize critical jobs
+            $this->queue->reprioritize(['high_priority_types']);
+
+            // Alert operations team
+            $this->alertManager->sendBacklogAlert($stats);
+        }
+    }
+}
+```
+
+## Testing
+
+### Integration Tests
+
+```php
+// Complete Pipeline Testing
+describe('Scheduler Queue Pipeline', function () {
+    it('handles full pipeline flow', function () {
+        // 1. Setup Scheduler Task
+        $schedule = IntervalSchedule::every(Duration::fromSeconds(1));
+        $this->scheduler->schedule('test-task', $schedule, function() {
+            $job = new TestPipelineJob('pipeline-test');
+            $payload = JobPayload::immediate($job);
+            $this->queue->push($payload);
+            return ['dispatched' => true];
+        });
+
+        // 2. Execute Scheduler
+        $results = $this->scheduler->executeDueTasks();
+        expect($results)->toHaveCount(1);
+        expect($results[0]->success)->toBeTrue();
+
+        // 3. Process Queue
+        $jobPayload = $this->queue->pop();
+        expect($jobPayload)->not->toBeNull();
+
+        $result = $jobPayload->job->handle();
+        expect($result['status'])->toBe('completed');
+
+        // 4. Verify End-to-End
+        expect($this->queue->size())->toBe(0);
+    });
+});
+```
+
+### Performance Tests
+
+```php
+// Pipeline Performance Benchmarks
+describe('Pipeline Performance', function () {
+    it('processes 1000 jobs within 30 seconds', function () {
+        $startTime = microtime(true);
+
+        // Dispatch 1000 jobs via scheduler
+        for ($i = 0; $i < 1000; $i++) {
+            $job = new BenchmarkJob("job-{$i}");
+            $payload = JobPayload::immediate($job);
+            $this->queue->push($payload);
+        }
+
+        // Process all jobs
+        while ($this->queue->size() > 0) {
+            $jobPayload = $this->queue->pop();
+            $jobPayload->job->handle();
+        }
+
+        $executionTime = microtime(true) - $startTime;
+        expect($executionTime)->toBeLessThan(30.0);
+        expect($this->queue->size())->toBe(0);
+    });
+});
+```
+
+## Best Practices
+
+### 1. Job Design
+- **Named Classes**: Immer Named Classes statt Anonymous Functions verwenden
+- **Type Safety**: JobPayload Value Objects für alle Queue-Operationen
+- **Idempotency**: Jobs sollten mehrfach ausführbar sein ohne Seiteneffekte
+- **Error Handling**: Graceful Degradation bei Fehlern implementieren
+
+### 2. Scheduler Configuration
+- **Reasonable Intervals**: Nicht zu aggressive Scheduling-Intervalle
+- **Resource Awareness**: CPU/Memory-Limits bei Task-Design beachten
+- **Monitoring**: Kontinuierliche Überwachung der Execution-Times
+- **Failover**: Backup-Strategien für kritische Tasks
+
+### 3. Queue Management
+- **Priority Classes**: Sinnvolle Priorisierung für verschiedene Job-Types
+- **Batch Processing**: Große Datenmengen in Batches aufteilen
+- **Dead Letter Handling**: Automatische Failed-Job-Recovery
+- **Metrics Collection**: Performance-Daten für Optimierung sammeln
+
+### 4. Production Deployment
+- **Health Checks**: Regelmäßige Pipeline-Health-Verification
+- **Alerting**: Automatische Benachrichtigungen bei Problemen
+- **Scaling**: Auto-Scaling für Worker-Processes
+- **Backup**: Disaster-Recovery-Strategien für Queue-Daten
+
+## Framework Integration
+
+Die Pipeline nutzt konsequent Framework-Patterns:
+- **Value Objects**: Timestamp, Duration, JobPayload, Priority
+- **Readonly Classes**: Unveränderliche Job-Definitionen
+- **Event System**: Integration mit Framework's Event Dispatcher
+- **DI Container**: Automatic Service Resolution
+- **Attribute Discovery**: Convention-over-Configuration
+- **MCP Integration**: AI-gestützte Pipeline-Analyse
+
+## Performance Charakteristiken
+
+**Typische Performance-Werte**:
+- **Job Dispatch Latency**: < 50ms
+- **Queue Throughput**: 1000+ Jobs/Minute (FileQueue)
+- **Memory Usage**: < 50MB für Standard-Jobs
+- **Scheduler Precision**: ±1 Second für Cron-basierte Tasks
+- **End-to-End Latency**: < 500ms für einfache Jobs
+
+**Skalierungscharakteristiken**:
+- **Horizontal Scaling**: Multi-Worker Support
+- **Queue Capacity**: 100,000+ Jobs (Database-backed)
+- **Scheduler Load**: 10,000+ concurrent scheduled tasks
+- **Memory Efficiency**: Linear scaling mit Job-Complexity