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/guides/README-static-site.md

@@ -0,0 +1,118 @@
+# Static Site Generator
+
+Diese Komponente ermöglicht die Generierung statischer HTML-Seiten aus den dynamischen Routen der Anwendung, die mit dem `#[StaticPage]` Attribut markiert sind.
+
+## Funktionsweise
+
+Der Static Site Generator identifiziert alle Controller-Methoden, die mit dem `#[StaticPage]` Attribut markiert sind, und erzeugt für jede entsprechende Route eine statische HTML-Datei im `public/static` Verzeichnis. Die Verzeichnisstruktur wird entsprechend der URL-Struktur erstellt.
+
+## Markieren von Routen als statische Seiten
+
+Um eine Route als statische Seite zu kennzeichnen, füge das `#[StaticPage]` Attribut zur Controller-Methode hinzu:
+
+```php
+use App\Framework\Attributes\StaticPage;
+use App\Framework\Attributes\Route;
+
+class HomeController
+{
+    #[Route('/')]
+    #[StaticPage]
+    public function index()
+    {
+        // Diese Seite wird als statische Seite generiert
+        return new ViewResult(new HomeViewModel());
+    }
+
+    #[Route('/about')]
+    #[StaticPage(outputPath: 'ueber-uns')]
+    public function about()
+    {
+        // Diese Seite wird mit benutzerdefiniertem Pfad generiert
+        return new ViewResult(new AboutViewModel());
+    }
+
+    #[Route('/dynamic-content')]
+    public function dynamic()
+    {
+        // Diese Seite wird NICHT als statische Seite generiert
+        return new ViewResult(new DynamicViewModel());
+    }
+}
+```
+
+## Verwendung
+
+### Über die Kommandozeile
+
+```bash
+# Nur mit #[StaticPage] markierte Routen generieren (Standard)
+php bin/generate-static.php
+
+# Oder mit Composer
+composer generate-static
+
+# Alle GET-Routen generieren (ignoriert #[StaticPage] Attribut)
+php bin/generate-static.php --all
+
+# Mit benutzerdefinierten Optionen
+php bin/generate-static.php --manual-routes=config/static-routes.json --output=public/static --exclude="\/api\/.*,\/admin\/.*"
+```
+
+### Verfügbare Optionen
+
+- `--manual-routes=<datei>`: Pfad zu einer JSON-Datei mit zu generierenden Routen (überschreibt Attributerkennung)
+- `--output=<ordner>`: Ausgabeverzeichnis (Standard: public/static)
+- `--exclude=<muster>`: Kommagetrennte Liste von Regex-Mustern für auszuschließende Routen
+- `--all`: Alle GET-Routen generieren (ignoriert #[StaticPage] Attribut)
+- `--help`: Hilfe anzeigen
+
+### Programmatisch verwenden
+
+```php
+use App\Framework\StaticSite\StaticSiteGenerator;
+use App\Framework\StaticSite\StaticPageCollector;
+
+// Anwendung initialisieren
+$app = /* ... */;
+
+// Routen mit StaticPage-Attribut sammeln
+$router = $app->getContainer()->get(HttpRouter::class);
+$staticPageCollector = new StaticPageCollector($router);
+$routes = $staticPageCollector->collectStaticPages();
+
+// Oder alle GET-Routen sammeln
+// $routes = $staticPageCollector->collectAllGetRoutes();
+
+// Generator initialisieren
+$generator = new StaticSiteGenerator($app, $routes);
+
+// Optional: Ausgabeverzeichnis anpassen
+$generator->setOutputDirectory(__DIR__ . '/path/to/output');
+
+// Statische Seiten generieren
+$generator->generate();
+```
+
+## Ausgabestruktur
+
+Für jede markierte Route wird eine entsprechende Datei oder Verzeichnisstruktur erstellt:
+
+- `/` → `/public/static/index.html`
+- `/about` → `/public/static/about/index.html` (oder benutzerdefinierter Pfad, wenn im Attribut angegeben)
+- `/blog/post-1` → `/public/static/blog/post-1/index.html`
+
+## Erweitertes StaticPage-Attribut
+
+Das `#[StaticPage]` Attribut unterstützt folgende Parameter:
+
+- `outputPath`: Optionaler benutzerdefinierter Ausgabepfad für die statische Seite
+- `prerender`: Ob die Seite beim Deployment vorgerendert werden soll (Standard: true)
+
+## Vorteile statischer Seiten
+
+- Verbesserte Performance durch Wegfall der dynamischen Verarbeitung
+- Geringere Serverlast
+- Einfacheres Hosting (statische Dateien können überall gehostet werden)
+- Verbesserte Sicherheit durch Reduzierung der Angriffsfläche
+- Bessere SEO durch schnellere Ladezeiten