documentation update with module guidelines

docs/howto-lokale-entwicklung.md

@@ -1,6 +1,6 @@
 # Lokale Entwicklung
 
-Letzte Aktualisierung: 2026-03-09
+Letzte Aktualisierung: 2026-03-18
 
 ## Ziel
 
@@ -21,6 +21,18 @@ Bei inkonsistentem Laufzeitverhalten:
 docker compose restart php nginx
 ```
 
+## Module-Sync
+
+Nach Aenderungen an Modulen, Manifesten oder `APP_ENABLED_MODULES`:
+
+```bash
+docker compose exec php php bin/module-runtime-sync.php
+```
+
+Dieser Befehl fuehrt automatisch aus: `migrate` → `permissions-sync` → `build` → `assets-sync`.
+
+Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist der Sync noetig.
+
 ## Schema-Stand
 
 - Basis-Schema + Seeds: `db/init/init.sql`
@@ -42,6 +54,12 @@ docker compose exec php vendor/bin/phpunit
 docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
 ```
 
+Bei Modul-/Manifest-Aenderungen zusaetzlich:
+
+```bash
+docker compose exec php php bin/module-runtime-sync.php
+```
+
 Bei JS-Änderungen zusätzlich Browser-Smoke mit DevTools-Console (keine JS-Errors).
 
 ## Struktur-Gates (empfohlen)

docs/reference-konventionen.md

@@ -1,6 +1,6 @@
 # Konventionen (kurz und verbindlich)
 
-Letzte Aktualisierung: 2026-03-17
+Letzte Aktualisierung: 2026-03-18
 
 ## 1) Code
 
@@ -48,8 +48,20 @@ Letzte Aktualisierung: 2026-03-17
 - Runtime-Komponenten nur über Lifecycle-Contract (`init(root, config)` + `destroy()`), ohne komponenteneigenen Auto-Init.
 - Host-gebundene Runtime-Komponenten über `data-app-component` markieren; nur echte Global-Utilities ohne Host als runtime-global registrieren.
 
-## 6) Mindestchecks vor Merge
+## 7) Module
+
+- Namespace: `MintyPHP\Module\<Name>\*` — nie Core-Namespaces (`MintyPHP\Service\*`, `MintyPHP\Repository\*`).
+- Verzeichnis: `modules/<id>/lib/Module/<Name>/` (Service, Repository, Providers, Support).
+- Session-Keys: Prefix `module.<id>.*`.
+- UI-Integration nur ueber Plattform-Slots (`aside.tab_panel`, `topbar.right_item`, `layout.head_style`, `runtime.component`, etc.).
+- Kein Modul-spezifisches Markup in Core-Templates.
+- Tests: `modules/<id>/tests/` (werden von `phpunit.xml` automatisch entdeckt via `modules/*/tests`).
+- Modul-Actions importieren nie `OperationsAuthorizationPolicy::ABILITY_*` — eigene Policy nutzen.
+- Manifest-Contract: `/docs/reference-module-manifest-contract.md`.
+
+## 8) Mindestchecks vor Merge
 
 - `docker compose exec php vendor/bin/phpunit`
 - `docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress`
+- bei Modul-/Manifest-Aenderungen: `docker compose exec php php bin/module-runtime-sync.php`
 - bei JS-Änderungen: Browser-Smoke mit DevTools-Console (keine JS-Errors)

docs/reference-module-manifest-contract.md

@@ -1,4 +1,4 @@
-# Module Manifest Contract (V1.1)
+# Module Manifest Contract (V1.2)
 
 Letzte Aktualisierung: 2026-03-18
 
@@ -11,6 +11,26 @@ Verbindlicher Contract fuer `modules/*/module.php`, damit Module zur Runtime det
 Dieses Dokument ist die kanonische (normative) Quelle fuer Manifest-, Runtime- und Guard-Regeln des Modul-Systems.
 `/docs/reference-extension-readiness.md` referenziert diesen Contract und dupliziert keine Felddefinitionen.
 
+## Namespace-Konvention
+
+Alle PHP-Klassen eines Moduls muessen den Namespace `MintyPHP\Module\<Name>\*` verwenden.
+Core-Namespaces (`MintyPHP\Service\*`, `MintyPHP\Repository\*`, `MintyPHP\Support\*`) sind fuer Modul-Code verboten.
+
+Verzeichnis-Layout:
+
+```
+modules/<id>/lib/Module/<Name>/
+  Service/              # BookmarkService, Factory, etc.
+  Repository/           # Repository + Interfaces
+  Providers/            # SessionProvider, LayoutProvider, SearchProvider
+  Support/              # Modul-spezifische Utilities
+  <Name>ContainerRegistrar.php
+  <Name>AuthorizationPolicy.php
+```
+
+Der `ModuleAutoloader` mappt `MintyPHP\*` → `modules/<id>/lib/` per PSR-4.
+Enforcement: `ModuleStructureContractTest::testModuleClassesUseModuleNamespace`.
+
 ## Aktivierung (`APP_ENABLED_MODULES`)
 
 - nicht gesetzt: `config/modules.php` gilt.
@@ -86,6 +106,26 @@ Abgrenzung CSS:
 - Layout-Provider duerfen reservierte Core-Keys nicht ueberschreiben (`moduleSlots`, `csrfKey`, `currentTenant`, ...).
 - Layout-Provider-Top-Level-Keys muessen namespaced sein (`<module_id>.<key>`).
 
+## Runtime-Fingerprint
+
+`web/index.php` validiert bei jedem Request, dass der Runtime-Stand zur aktuellen Modul-Konfiguration passt.
+
+- `bin/module-build.php` schreibt nach jedem Build `storage/runtime/.module-fingerprint` (sortierte Modul-IDs, kommasepariert).
+- `web/index.php` vergleicht den Fingerprint mit der erwarteten Modul-Liste.
+- Bei Mismatch: `RuntimeException` mit Hinweis auf `php bin/module-runtime-sync.php`.
+- Kein Auto-Build im Request-Pfad — Build ist ausschliesslich CLI-Aufgabe.
+
+Methoden: `ModuleRuntimePageBuilder::expectedFingerprint()`, `readFingerprint()`, `writeFingerprint()`.
+
+## API-Channel-Isolation
+
+API-Requests (`api/`-Prefix) ueberspringen den gesamten Web-Session-Flow:
+
+- Kein `Session::start()`, kein Cookie-Setting, kein CSRF-Token
+- Kein Remember-Me, kein Session-Timeout, kein Tenant-UI-Refresh
+- API-Auth erfolgt ueber `ApiBootstrap.php` (Bearer-Token)
+- `AccessControl` listet `api/` als always-public
+
 ## Standard-Runbook
 
 `php bin/module-runtime-sync.php` fuehrt in fester Reihenfolge aus: