documentation update with module guidelines

CLAUDE.md

@@ -25,6 +25,9 @@ docker compose exec php vendor/bin/phpunit
 # Run PHPStan (level 5)
 docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
 
+# Sync module runtime (after module changes or APP_ENABLED_MODULES change)
+docker compose exec php php bin/module-runtime-sync.php
+
 # Check unused Composer packages
 docker compose exec php vendor/bin/composer-unused
 ```
@@ -34,30 +37,40 @@ docker compose exec php vendor/bin/composer-unused
 ```
 lib/                    # All backend PHP (namespace MintyPHP\)
   App/                  # DI container + bootstrap (AppContainer, Container/Registrars/)
+    Module/             # Module platform (Registry, Manifest, Autoloader, Builder)
   Repository/           # SQL queries, prepared statements, filters/paging
   Service/              # Business logic, validation, orchestration
   Http/                 # Auth guards, API auth, request helpers
     Input/              # Request input handling (RequestInput, FormErrors)
   Support/              # Crypto, flash, guard, search, helpers
-pages/                  # Actions (controllers) — file-based routing
+modules/                # Self-contained feature modules (namespace MintyPHP\Module\<Name>\)
+  <id>/module.php       # Module manifest (routes, slots, providers, permissions)
+  <id>/lib/             # Module PHP classes (Service, Repository, Providers)
+  <id>/pages/           # Module actions + views (symlinked into runtime)
+  <id>/templates/       # Module-specific templates
+  <id>/web/             # Module CSS/JS (published to web/modules/<id>/)
+  <id>/tests/           # Module PHPUnit tests
+pages/                  # Core actions (controllers) — file-based routing
   pages/**/*.php        # Action files (read input, check permissions, call services)
   pages/**/*.phtml      # View files (rendering only, no DB calls)
-templates/              # Layouts and partials
+templates/              # Core layouts and partials
   partials/             # Reusable UI components
   emails/               # Email HTML templates
   pdfs/                 # PDF templates (Dompdf)
-config/                 # App config (routes, assets, settings cache, themes)
+config/                 # App config (routes, assets, settings cache, themes, modules)
 web/                    # Document root (entry point, CSS, JS, static assets)
-  js/core/              # DOM utilities, Grid.js factory
+  js/core/              # DOM utilities, Grid.js factory, component runtime
   js/components/        # Reusable UI components
   css/                  # Layered CSS (base → components → layout → pages)
-storage/                # Uploaded files (branding/, imports/, tenants/, users/)
+  modules/              # Published module assets (symlinks to modules/<id>/web/)
+storage/                # Uploaded files + runtime state
+  runtime/pages/        # Symlinked page tree (core + modules, built by module-build)
 db/init/init.sql        # Full schema + seed data (no migration framework)
 db/updates/             # Idempotent SQL update scripts for existing installs
 tests/                  # PHPUnit tests (namespace MintyPHP\Tests\)
 docs/                   # German-language documentation (Markdown)
 i18n/                   # Translation files (de, en)
-bin/                    # CLI scripts (scheduler, doctor.php health check)
+bin/                    # CLI scripts (scheduler, module-runtime-sync, doctor.php)
 tools/                  # Dev tooling scripts
 docker/                 # Dockerfiles, Nginx configs, PHP configs
 ```
@@ -77,16 +90,30 @@ docker/                 # Dockerfiles, Nginx configs, PHP configs
 5. **View** (`pages/**/*.phtml`): Pure rendering. **No DB calls.** HTML escaping via `e(...)`.
 6. **Template** (`templates/`): Layouts and partials.
 
+### Modules
+
+- Modules are self-contained feature packages under `modules/<id>/`
+- **Namespace:** `MintyPHP\Module\<Name>\*` — never use core namespaces (`MintyPHP\Service\*`, `MintyPHP\Repository\*`)
+- **Manifest:** `module.php` declares routes, UI slots, providers, permissions, scheduler jobs
+- **UI integration:** Only via platform slots (`aside.tab_panel`, `topbar.right_item`, `layout.head_style`, `runtime.component`, etc.) — no core template hardcoding
+- **Session keys:** Prefixed with `module.<id>.*`
+- **Activation:** `config/modules.php` or `APP_ENABLED_MODULES` env override
+- **Runtime sync:** `php bin/module-runtime-sync.php` after any module/manifest change (builds page symlinks, syncs permissions, publishes assets)
+- **Fingerprint guard:** `web/index.php` validates runtime state matches active modules; fails fast if stale
+- **API isolation:** API requests (`api/` prefix) skip session/auth/cookie flows entirely; modules using API endpoints rely on `ApiBootstrap.php`
+
 ### Routing
 
 - File-based: `pages/admin/users/edit($id).php` → URL parameter `id`
+- Module pages: `modules/<id>/pages/` symlinked into `storage/runtime/pages/` at build time
 - `...(none).phtml` → no template layout
 - `data().php` suffix → data/AJAX endpoints
 - Named aliases in `config/routes.php` with `public` flag for auth guard
+- Module routes declared in manifest, merged at boot (fail-fast on collision)
 
 ### PHP Conventions
 
-- PSR-4 autoload: `MintyPHP\` → `lib/`, `MintyPHP\Tests\` → `tests/`
+- PSR-4 autoload: `MintyPHP\` → `lib/`, `MintyPHP\Module\*` → `modules/*/lib/`, `MintyPHP\Tests\` → `tests/`
 - All user-facing text uses `t('key')` translation helper
 - Permissions + tenant scope enforced in actions/services, never just in UI
 - Security/integration settings stay in DB, not in `config/settings.php` file cache
@@ -115,7 +142,7 @@ docker/                 # Dockerfiles, Nginx configs, PHP configs
 
 ## Quality Gates
 
-- **PHPStan level 5** — scans `config/`, `lib/`, `pages/`, `tests/`
+- **PHPStan level 5** — scans `config/`, `lib/`, `modules/`, `pages/`, `tests/`
 - **PHPUnit 11** — bootstrap: `tests/bootstrap.php`
 - **Frontend Smoke-Check** — browser console bleibt fehlerfrei in Kernflows
 - **composer-unused** — periodic check for unused dependencies