docs: cross-links updated to 3-level structure

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Vielen Dank für dein Interesse an der hightrusted CAPTURE API.
+
+## Wer kann beitragen
+
+Diese Repositorys werden primär von hightrusted GmbH gepflegt. Wir freuen uns
+über Bug-Reports, Verbesserungsvorschläge und Pull-Requests aus der Community.
+
+## Issues
+
+- **Bug-Report:** beschreibe das erwartete vs. tatsächliche Verhalten und liefere
+  einen reproduzierbaren Code-Schnipsel mit. Bitte keine API-Keys mit posten.
+- **Feature-Request:** beschreibe den Use-Case — wir entscheiden, ob das Feature
+  in das SDK gehört oder besser direkt gegen die API umgesetzt wird.
+
+## Pull Requests
+
+1. Fork und Branch (`feat/...`, `fix/...`, `docs/...`).
+2. Tests anpassen oder ergänzen.
+3. Lokale Build-Pipeline grün bekommen (siehe README).
+4. **Commits signieren** — sowohl GPG als auch X.509 werden akzeptiert. Unsignierte
+   Commits werden nicht gemerged.
+5. PR öffnen mit klarer Beschreibung: Was ändert sich, warum, Breaking Change ja/nein.
+
+## Code-Stil
+
+Jede Sprache hat ihre eigene Konvention — siehe README des jeweiligen Repos.
+Tendenziell: Pflegt euch an den Standards, die wir bereits im Code verwenden.
+
+## Lizenz
+
+Beiträge gehen unter der MIT-Lizenz ein (siehe `LICENSE`). Mit dem Öffnen eines
+PRs bestätigst du, dass du das Recht hast, deinen Beitrag unter diese Lizenz zu
+stellen.
+
+## Kontakt
+
+`developers@hightrusted.net`

README.md

@@ -1,3 +1,113 @@
-# capture-openapi
+# hightrusted CAPTURE — OpenAPI Specification
 
-OpenAPI 3.1 Spezifikation der hightrusted CAPTURE API
+> **Status:** v0.1 Preview — API stabil, Spec ist Single Source of Truth für alle SDKs
+
+OpenAPI 3.1 Spezifikation der [hightrusted CAPTURE API](https://capture.hightrusted.net) —
+forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.
+
+Diese Spec ist die **maschinenlesbare Referenz**, aus der wir alle anderen Artefakte
+ableiten: SDKs, Client-Bibliotheken, Postman-Collection, gerenderte Doku.
+
+**Made in Germany.** Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter
+in der Verarbeitungskette.
+
+## Inhalt
+
+- `openapi.yaml` — die OpenAPI 3.1 Spec
+- `examples/` — Beispiel-Requests und -Responses für jeden Endpoint
+- `CHANGELOG.md` — Versions-History der Spec
+
+## Validierung
+
+```bash
+# Mit redocly cli
+npx @redocly/cli lint openapi.yaml
+
+# Oder mit spectral
+npx @stoplight/spectral-cli lint openapi.yaml
+```
+
+## Doku rendern
+
+```bash
+# HTML-Doku mit Redoc bauen
+npx @redocly/cli build-docs openapi.yaml -o ./docs/index.html
+```
+
+Ergebnis: statische HTML-Datei mit kompletter API-Doku, die du auf jedem Webserver
+ablegen kannst.
+
+## Client-Generierung
+
+Aus dieser Spec lassen sich automatisch Clients für 50+ Sprachen erzeugen
+(siehe https://openapi-generator.tech). Wir pflegen offizielle Clients für
+Python, Node.js und PHP — siehe [Verwandte Repositorys](#verwandte-repositorys).
+
+```bash
+# Beispiel: Go-Client erzeugen
+openapi-generator-cli generate \
+  -i openapi.yaml \
+  -g go \
+  -o ./clients/go
+```
+
+## Versionierung
+
+API-Versionen sind im Pfad: `/api/v1/...`
+
+- **Breaking Changes** → neue Major-Version (`/api/v2`), alte Major bleibt 24 Monate erreichbar
+- **Non-Breaking Changes** (neue Felder, neue Endpoints) → ohne Versionssprung
+
+Diese OpenAPI-Spec verfolgt die API 1:1. Änderungen sind in `CHANGELOG.md`
+nachvollziehbar.
+
+## Endpoints (Übersicht)
+
+| Endpoint                       | Beschreibung                          | Auth   |
+|--------------------------------|---------------------------------------|--------|
+| `POST /captures`               | Capture erstellen (sync/async/webhook)| Bearer |
+| `GET /captures/{id}`           | Status & Metadaten abrufen            | Bearer |
+| `GET /captures/{id}/pdf`       | PDF herunterladen                     | Bearer |
+| `GET /captures/{id}/verify`    | Capture verifizieren                  | —      |
+| `GET /usage`                   | eigenen Verbrauch abrufen             | Bearer |
+
+## Webhook-Events
+
+| Event             | Wann                                    |
+|-------------------|-----------------------------------------|
+| `capture.ready`   | PDF und Zeitstempel fertig              |
+| `capture.failed`  | Fehler beim Rendern oder TSA            |
+
+Webhook-Retry: 3 Versuche mit exponentiellem Backoff (1 min, 5 min, 30 min).
+
+## Verwandte Repositorys
+
+**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):
+
+- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
+- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen
+- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK
+- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK
+- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK
+
+**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):
+
+- [`platform`](https://git.hightrusted.net/hightrusted/platform) — Plattform-Übersicht, Architektur, Produkt-Liste
+- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal) — gemeinsame Konventionen, Auth, Errors, Rate-Limits
+- [`compliance`](https://git.hightrusted.net/hightrusted/compliance) — DSGVO, AGB-Templates, Whitepaper
+
+## Support
+
+- **Doku:** https://capture.hightrusted.net/api/docs
+- **Status-Page:** https://status.hightrusted.net
+- **Developer Support:** developers@hightrusted.net
+- **Sicherheitslücken:** siehe [SECURITY.md](./SECURITY.md)
+
+## Lizenz
+
+MIT — siehe [LICENSE](./LICENSE).
+
+---
+
+**hightrusted GmbH** — *The European Trust Infrastructure.*
+Made in Germany. DSGVO-nativ. eIDAS-konform.

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Sicherheitslücken melden
+
+Wenn du eine Sicherheitslücke in diesem SDK oder in der hightrusted CAPTURE API
+findest, **öffne kein öffentliches Issue**. Stattdessen:
+
+- **E-Mail:** `security@hightrusted.net`
+- **PGP-Key:** veröffentlicht auf https://hightrusted.net/.well-known/security.txt
+
+Bitte gib in der Meldung an:
+
+- Betroffenes Repository / SDK-Version
+- Beschreibung der Schwachstelle und potenzielle Auswirkung
+- Schritte zur Reproduktion
+- Falls vorhanden: Proof-of-Concept-Code
+
+Wir bestätigen den Eingang innerhalb von 48 Stunden und arbeiten an einer
+zeitnahen Behebung. Verantwortliche Offenlegung wird honoriert — wir nennen
+Reporter (auf Wunsch) in den Release-Notes.
+
+## Unterstützte Versionen
+
+Während der `v0.x`-Phase werden nur die jeweils aktuellste Minor-Version und
+deren letzte zwei Patch-Versionen aktiv mit Sicherheits-Updates versorgt.
+
+Ab `v1.0` gilt: aktuelle Major + vorherige Major (12 Monate Übergangsfrist).
+
+## Out of Scope
+
+Diese Policy gilt für die SDKs in diesem Repository und die zugehörige
+hightrusted CAPTURE API. Für Schwachstellen in anderen hightrusted-Produkten
+(SIGN, ID, MEET, PAY, …) gilt jeweils die dortige `SECURITY.md`.