Rewrite README for GMs

README.md

@@ -1,50 +1,100 @@
 # Kosmos Storage Audit
 
-Dieses Verzeichnis enthaelt einen ersten Modul-Prototypen fuer die Analyse von Medienreferenzen und riskanten Ablageorten in FoundryVTT.
+`Kosmos Storage Audit` hilft Spielleitern dabei, fehlende, veraltete und moeglicherweise verwaiste Mediendateien in einer FoundryVTT-Installation zu finden.
 
-## Foundry Manifest
+Das Modul ist als Pruefwerkzeug gedacht. Es aendert keine Weltdaten und verschiebt oder loescht keine Dateien.
 
-- 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`
+## Installation
 
-## Ausrichtung
+Manifest-URL:
 
-- 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.
+```text
+https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/raw/branch/main/module.json
+```
 
-## Erste Kernbausteine
+Alternativ:
 
-- `path-utils.js`
-  - Normalisierung auf `data:` und `public:` inklusive URL-Decoding und Unicode-Normalisierung
-- `reference-extractor.js`
-  - rekursive String- und Attribut-Extraktion aus JSON/Objekten inklusive Wildcard-Erkennung
-- `finding-engine.js`
-  - Klassifizierung von Broken References, Orphans und Fremdverweisen mit Wildcard-Matching
-- `analyzer.js`
-  - Orchestrierung von Dateien, Quellen und Findings
-- `audit-report-app.js`
-  - Foundry-UI mit Fortschrittsanzeige, gruppierter Arbeitsansicht, JSON-Export und lokalisierter Oberfläche
+- Projektseite: `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit`
+- ZIP-Download: `https://gitea.kosmos.ac/kosmos/kosmos-storage-audit/archive/main.zip`
 
-## Wichtige Heuristik
+## Was das Modul prueft
 
-- 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.
-- Wildcard-Pfade wie `Ork*_Token.webp` werden nicht als kaputt markiert, solange mindestens eine passende Datei im gescannten Root existiert.
-- Dieselben Wildcard-Referenzen zaehlen auch als eingehende Referenz fuer passende Dateien und verhindern damit false-positive `orphan-file`-Treffer.
-- URL-encodierte oder unterschiedlich normalisierte Umlaute sollen auf dieselbe kanonische Pfadform zusammengefuehrt werden.
-- Die UI unterstuetzt konsistent Deutsch und Englisch ueber Foundry-Sprachdateien.
+Der Report zeigt drei Arten von Problemen:
 
-## Noch offen
+- `Fehlt`
+  Dateien werden noch von Objekten in der Welt verwendet, sind aber im geprueften Bestand nicht vorhanden.
+- `Veraltet`
+  Die Welt verweist auf Dateien in Modul- oder Systemordnern, die dort nicht mehr wie regulaerer Paketinhalt aussehen.
+- `Verwaist`
+  Dateien liegen noch im Storage, fuer die im aktuell geprueften Datenbestand keine Verwendung mehr gefunden wurde.
 
-- bessere Laufzeitabdeckung fuer Welteinstellungen und weitere Referenzquellen
-- optional zusaetzliche Exportformate neben JSON
-- Aktionen zum sicheren Verschieben oder Migrieren
+## Wobei das hilft
+
+Typische Faelle sind:
+
+- kaputte Bilder, Videos oder Sounds
+- Uploads eines Spielleiters in ungeeignete Modulordner
+- Dateien aus alten Modulversionen, die noch in Weltdaten referenziert werden
+- Altlasten, die sich ueber Jahre in `data` oder `public` ansammeln
+
+## Was der Report nicht macht
+
+- keine Dateien loeschen
+- keine Referenzen automatisch reparieren
+- keine Weltdaten migrieren
+- keine Dateien verschieben oder kopieren
+
+Das Modul zeigt nur, was geprueft werden sollte.
+
+## Hinweise zur Auswertung
+
+`Fehlt`
+
+- Diese Treffer sollte man in der Regel zuerst anschauen.
+- Meist wurde eine Datei geloescht, verschoben oder durch ein Update ersetzt.
+
+`Veraltet`
+
+- Diese Treffer deuten oft auf alte Moduldateien oder unguenstige Upload-Orte hin.
+- In manchen Faellen kann eine neue Initialisierung oder ein erneuter Import des betroffenen Moduls helfen.
+
+`Verwaist`
+
+- Diese Treffer sind bewusst vorsichtiger zu lesen.
+- Das Modul kann derzeit technisch nicht pruefen, ob eine Datei eventuell noch im Kontext einer anderen Welt verwendet wird.
+
+## Hinweise im Report
+
+Im Abschnitt `Hinweise` tauchen Faelle auf, die absichtlich nicht als Findings gezaehlt werden, zum Beispiel:
+
+- Verweise auf Dateien aus inaktiven Modulen
+- Verweise auf Modulordner, die von Foundry derzeit nicht mehr als installierte Module erkannt werden
+
+Diese Hinweise sollen beim Einordnen helfen, ohne die eigentliche Ergebnisliste mit moeglichen False Positives aufzublaehen.
+
+## Filter fuer Verwaist
+
+Bei `Verwaist` kann man bestimmte Pfadgruppen direkt ausblenden, zum Beispiel:
+
+- `modules/*`
+- `systems/*`
+- `canvas/cards/docs/icons/nue/sounds/toolclips/ui`
+
+Das ist hilfreich, wenn man sich zuerst auf spielleiternahe Upload-Bereiche konzentrieren moechte.
+
+## Sicherheit
+
+Der aktuelle Stand des Moduls ist reine Analyse.
+
+Es werden:
+
+- Dateien gelesen
+- Referenzen ausgewertet
+- Findings angezeigt
+- Reports exportiert
+
+Es werden keine Daten veraendert.
+
+## Sprache
+
+Die Oberflaeche unterstuetzt Deutsch und Englisch und richtet sich nach der eingestellten Foundry-Sprache.