diff --git a/NEXT_STEPS.md b/NEXT_STEPS.md
new file mode 100644
index 0000000..e2edd9b
--- /dev/null
+++ b/NEXT_STEPS.md
@@ -0,0 +1,123 @@
+# Next Steps
+
+## Issue Drafts (Ready for Gitea/GitHub)
+
+### 1) Enable strict types + typed signatures
+- Aufwand: `M`
+- Labels: `quality`, `refactor`
+- Ziel: Konsistente Typen und weniger implizite Typfehler.
+- Akzeptanzkriterien:
+- Alle PHP-Dateien starten mit `declare(strict_types=1);` (wo kompatibel).
+- Oeffentliche Funktionen erhalten Rueckgabe-/Parameter-Typen.
+- Inkompatible Stellen sind dokumentiert oder angepasst.
+
+### 2) Define unified error strategy
+- Aufwand: `M`
+- Labels: `quality`, `api`
+- Ziel: Einheitliches Verhalten bei Fehlern.
+- Akzeptanzkriterien:
+- ADR/kurze Doku: wann `null/false`, wann Exception.
+- `sql.php`, `link-meta.php`, `troy-api.php` folgen derselben Strategie.
+- Mindestens 3 Beispiele in `README.md` dokumentiert.
+
+### 3) Expand README with runnable examples
+- Aufwand: `S`
+- Labels: `docs`
+- Ziel: Schnellere Nutzung ohne Code-Lesen.
+- Akzeptanzkriterien:
+- Pro Modul mindestens 1 kurzes Copy/Paste-Beispiel.
+- Abschnitt "Konfiguration" mit `secret.php`-Feldern vorhanden.
+- Abschnitt "Known limitations" ergaenzt.
+
+### 4) Complete `secret.php.example`
+- Aufwand: `S`
+- Labels: `docs`, `config`
+- Ziel: Vollstaendige Vorlagedatei fuer lokale Setups.
+- Akzeptanzkriterien:
+- Alle erwarteten Variablen aus `sql.php`, `mail.php`, `troy-api.php` enthalten.
+- Jede Variable hat kurzen Kommentar.
+- Dateiformat entspricht direkt nutzbarer Vorlage.
+
+### 5) Remove `@` error suppression incrementally
+- Aufwand: `M`
+- Labels: `quality`, `safety`
+- Ziel: Fehler sichtbar und kontrolliert behandeln.
+- Akzeptanzkriterien:
+- Alle `@`-Operatoren inventarisiert.
+- Ersetzungen mit explizitem Error-Handling umgesetzt.
+- Keine neue `@`-Verwendung in geaenderten Dateien.
+
+## 2) Sicherheit und Robustheit
+
+### 6) Harden URL fetching against SSRF
+- Aufwand: `M`
+- Labels: `security`, `network`
+- Akzeptanzkriterien:
+- Private/loopback ranges werden blockiert.
+- Optionales Host-Allowlist-Feature vorhanden.
+- Tests fuer geblockte und erlaubte Ziele vorhanden.
+
+### 7) Prevent mail header injection
+- Aufwand: `S`
+- Labels: `security`, `mail`
+- Akzeptanzkriterien:
+- Empfaenger/Betreff/From werden validiert.
+- CRLF-Injection wird abgefangen.
+- Fehlerfall ist dokumentiert.
+
+### 8) Centralize HTTP limits (timeout/redirect/size)
+- Aufwand: `S`
+- Labels: `robustness`, `network`
+- Akzeptanzkriterien:
+- Eine zentrale Konfiguration fuer HTTP-Limits.
+- `og.php` und `link-meta.php` nutzen dieselben Limits.
+- Default-Werte sind in README dokumentiert.
+
+### 9) Improve SQL error handling + logging
+- Aufwand: `M`
+- Labels: `sql`, `robustness`
+- Akzeptanzkriterien:
+- `prepare()`/`execute()`-Fehler werden explizit behandelt.
+- Fehler enthalten Query-Kontext ohne Secrets.
+- Verhalten entspricht der definierten Error-Strategie.
+
+### 10) Replace fragile HTML allowlist sanitizer
+- Aufwand: `M`
+- Labels: `security`, `string`
+- Akzeptanzkriterien:
+- `onlySimpleHTML()` wird durch robusteren Ansatz ersetzt.
+- Erlaubte Tags sind konfigurierbar dokumentiert.
+- Regression-Tests fuer typische Eingaben vorhanden.
+
+## 3) Code-Qualitaet
+
+- Sammel-Issue: Naming-Konvention, SQL-Binding-Refactor, Legacy-Markierung, Markdown-Konsolidierung, klare Modulgrenzen.
+- Aufwand: `L`
+- Empfehlung: in 3-5 Unter-Issues aufteilen.
+
+## 4) Tests und Tooling
+
+### 11) Bootstrap test/tooling baseline
+- Aufwand: `M`
+- Labels: `testing`, `ci`
+- Akzeptanzkriterien:
+- PHPUnit laeuft lokal mit ersten Smoke-Tests.
+- PHPStan/Psalm auf niedriger Stufe integriert.
+- CI fuehrt mindestens Lint + Tests bei Push aus.
+
+## 5) Mittelfristige Architektur
+
+### 12) Prepare Composer + namespace migration path
+- Aufwand: `L`
+- Labels: `architecture`
+- Akzeptanzkriterien:
+- Vorschlag fuer Zielstruktur (`src/`, namespaces, autoload).
+- Migrationsplan fuer prozedurale Helfer zu Klassen.
+- Konfigurationsobjekt und HTTP-Adapter als Zielbild beschrieben.
+
+## Empfohlene Reihenfolge
+
+1. `#1` bis `#5` (kurzfristig, hoher Hebel)
+2. `#6` bis `#10` (Sicherheit/Robustheit)
+3. `#11` (Tests + CI als Guardrail)
+4. `#12` und Sammel-Issue aus Abschnitt 3
diff --git a/README.md b/README.md
index 3dfc899..601ce20 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,68 @@
 # php-func-lib
+
+Kleine PHP-Utility-Bibliothek mit wiederverwendbaren Helfern fuer:
+
+- Strings und einfache Sanitization
+- Zahlenformatierung
+- SQL-Zugriffe (mysqli + prepared statements)
+- Mailversand
+- Link/OpenGraph-Metadaten
+- Debug-Helfer
+- Troy-/Gitea-API-Aufrufe
+
+## Installation
+
+Als Git-Submodule in ein Projekt einbinden:
+
+```bash
 git submodule add https://git.seemsleg.it/pub/php-func-lib lib
+```
+
+Danach je nach Bedarf einzelne Dateien einbinden oder zentral ueber `_func.php` laden.
+
+## Schnellstart
+
+```php
+<?php
+include_once __DIR__ . '/lib/_func.php';
+
+echo shortener("Ein sehr langer Text", 10); // "Ein sehr..."
+echo decade(12345);                         // "12.345 K" (je nach PHP-Konvertierung)
+```
+
+## Module
+
+- `string.php`: String-Helfer (`shortener`, `onlyAlpha`, `startsWith`, `endsWith`, `linkify`, ...)
+- `numbers.php`: Zahlen-Helfer (`decade`, `onlyNumeric`)
+- `sql.php`: Klasse `SQL` fuer Datenbankzugriffe (`get`, `single`, `list`, `keyval`, `set`)
+- `mail.php`: Mailfunktionen (`send_mail`, `send_html_mail`, `send_php_mail`)
+- `link-meta.php`: URL-Validierung, Fetching, Meta-Parsing, Bilddownload, Tag-Sanitization
+- `og.php`: Einfacher OG-Scan (`scanOG`)
+- `troy-api.php`: API-Helfer fuer Troy/Gitea (`sendToTroy`, `sendToGitea`)
+- `debug.php`: Cookie-basierte Debug-Ausgabe
+- `markdown.php`: einfache Markdown-nahe Formatierung (`md`)
+
+## Konfiguration
+
+Einige Module erwarten ein lokales `secret.php` (siehe `secret.php.example`), z. B. fuer:
+
+- SQL-Zugangsdaten in `sql.php`
+- optionale Absenderadresse in `mail.php`
+- Gitea-Parameter in `troy-api.php`
+
+## Beispiel: Seitenmetadaten lesen
+
+```php
+<?php
+include_once __DIR__ . '/lib/link-meta.php';
+
+$info = getPageInfo('https://example.org');
+if ($info['ok']) {
+    echo $info['title'];
+}
+```
+
+## Hinweise
+
+- Die Bibliothek ist bewusst leichtgewichtig und ohne Composer-Setup gehalten.
+- Einzelne Funktionen sind historisch gewachsen; fuer geplante Verbesserungen siehe `next_steps.md`.