documentation update with module guidelines

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: