Initial module scaffold

README.md

@@ -0,0 +1,45 @@
+# Kosmos Storage Audit
+
+Dieses Verzeichnis enthaelt einen ersten Modul-Prototypen fuer die Analyse von Medienreferenzen und riskanten Ablageorten in FoundryVTT.
+
+## Foundry Manifest
+
+- Manifest-URL:
+  - `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/raw/branch/main/module.json`
+- Download-URL:
+  - `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/archive/main.zip`
+
+## Ausrichtung
+
+- Das Zielprodukt ist ein online nutzbares Foundry-Modul.
+- Die Kernlogik unter `scripts/core/` ist bewusst runtime-neutral gehalten.
+- `scripts/adapters/foundry-runtime.js` bindet die Kernlogik an die laufende Foundry-Instanz.
+- `tools/offline-analyze.mjs` ist nur ein Entwicklungs-Harness, um Parser und Matching lokal gegen eine gestoppte Instanz zu pruefen.
+
+## Erste Kernbausteine
+
+- `path-utils.js`
+  - Normalisierung auf `data:` und `public:`
+- `reference-extractor.js`
+  - rekursive String- und Attribut-Extraktion aus JSON/Objekten
+- `finding-engine.js`
+  - Klassifizierung von Broken References, Orphans und Fremdverweisen
+- `analyzer.js`
+  - Orchestrierung von Dateien, Quellen und Findings
+
+## Wichtige Heuristik
+
+- Bei mehreren Welten versucht das Tool nicht, globale "echte Orphans" im gesamten `data`-Root zu behaupten.
+- Orphans werden nur in klar eingrenzbaren Bereichen gemeldet:
+  - weltlokale Bereiche
+  - explizit riskante Paket-`storage`-Ordner
+  - nicht offensichtliche `public`-Bereiche
+- Weltverweise auf Modul- oder Systemassets gelten nicht pauschal als Problem.
+- Sie werden erst dann hochgezogen, wenn das Zielasset im owning Paket selbst nicht sichtbar referenziert ist.
+
+## Noch offen
+
+- bessere Laufzeitabdeckung fuer Welteinstellungen und Compendien
+- robustere Erkennung von Directory- und Wildcard-Referenzen
+- UI in Foundry
+- Aktionen zum sicheren Verschieben oder Migrieren