# Code Guardian — Updates automatisch beziehen

Diese Datei ist eine Handlungsanweisung für Claude Code. Sie beschreibt,
wie sich die jeweils neueste berechtigte Version des Code-Guardian-Pakets
mit einem Lizenzschlüssel abrufen, prüfen und installieren lässt.

Stand dieser Datei: Version **v16.151** ist derzeit die neueste
veröffentlichte. Verlassen Sie sich nicht auf diese Zahl — fragen Sie den
Endpunkt.

---

## 1. Einrichtung beim Kunden

Der Lizenznehmer trägt diese vier Zeilen in seine `~/.claude/CLAUDE.md`
(oder eine projektlokale `CLAUDE.md`) ein:

```markdown
## Code Guardian — Updates
Anleitung: https://www.provimedia.de/code-guardian/update_skill.md
Lizenzschlüssel: CGRD-XXXXX-XXXXX-XXXXX-XXXXX
Bei einer Update-Anfrage zuerst die Anleitung lesen und ihr folgen.
```

Den Schlüssel findet er in seinem Portal: https://www.provimedia.de/code-guardian/portal

**Der Schlüssel ist ein Zugangsmittel.** Er gehört nicht in ein
Repository, nicht in einen Commit und nicht in eine geteilte Datei.
Besser als die `CLAUDE.md` ist eine Umgebungsvariable, wenn das Projekt
eine hat. Ist ein Schlüssel abhandengekommen, erzeugt der Kunde im Portal
einen neuen; der alte verfällt im selben Moment.

---

## 2. Authentifizierung

Jeder Aufruf trägt den Schlüssel im Header — wahlweise:

```
Authorization: Bearer CGRD-XXXXX-XXXXX-XXXXX-XXXXX
```
```
X-Licence-Key: CGRD-XXXXX-XXXXX-XXXXX-XXXXX
```

Groß-/Kleinschreibung, Leerzeichen und fehlende Bindestriche werden
toleriert. Der Schlüssel steht **nie** in der URL — sonst landet er in
Server-Logs und in der Shell-History.

---

## 3. Die drei Endpunkte

### GET https://www.provimedia.de/api/code-guardian/status

Lizenz, Update-Zeitraum und Abo-Zustand. Der Einstieg für „wie steht es?".

```bash
curl -s -H "Authorization: Bearer $CG_KEY" \
  https://www.provimedia.de/api/code-guardian/status
```

```json
{
  "product": "Code Guardian",
  "licence": { "company": "Beispiel GmbH", "purchased_at": "2026-07-31", "perpetual": true },
  "updates": {
    "entitled_until": "2026-08-30",
    "active": true,
    "days_remaining": 30,
    "subscription": {
      "active": true,
      "status": "trialing",
      "cancels_at_period_end": false,
      "current_period_end": "2026-08-30"
    }
  },
  "latest_entitled": {
    "version": "v16.151",
    "published_at": "2026-07-30T15:22:42+00:00",
    "size_bytes": 1625012,
    "sha256": "0add9708cbda5c977a607402d7a9f3e2be4cd75c3293fa02153e1ae9bbc1d30d",
    "changelog": "…",
    "download_url": "https://www.provimedia.de/api/code-guardian/download/v16.151"
  },
  "latest_available": { "version": "v16.151", "published_at": "2026-07-30T15:22:42+00:00" },
  "newer_version_requires_subscription": null,
  "portal_url": "https://www.provimedia.de/code-guardian/portal"
}
```

`latest_entitled` ist die neueste Version, die diese Lizenz laden **darf**.
`latest_available` ist die neueste, die es **gibt**. Weichen beide
voneinander ab, nennt `newer_version_requires_subscription` die Version,
die ein aktives Update-Abo erfordert.

Diese API weiß **nicht**, welche Version lokal installiert ist. Den
Abgleich macht der Aufrufer (siehe Abschnitt 4).

### GET https://www.provimedia.de/api/code-guardian/latest

Direkt die neueste berechtigte Version, ohne den Rest.

```bash
curl -s -H "Authorization: Bearer $CG_KEY" \
  https://www.provimedia.de/api/code-guardian/latest
```

Antwort wie `latest_entitled` oben, zusätzlich `portal_url` und
`newer_version_requires_subscription`.

### GET https://www.provimedia.de/api/code-guardian/download/{version}

Liefert das ZIP. Ohne Versionsangabe die neueste berechtigte, mit
Versionsangabe genau diese — auch eine ältere, falls ein Rückbau auf
einen früheren Stand nötig ist.

```bash
curl -fsSL -H "Authorization: Bearer $CG_KEY" \
  -o code-guardian-update.zip \
  https://www.provimedia.de/api/code-guardian/download/v16.151
```

---

## 4. Der Ablauf für ein Update

1. **Installierten Stand feststellen.** Die Version steht in der ersten
   Zeile von `~/.claude/skills/code-guardian/SKILL.md` in der Form
   `# Code Guardian (vX.Y)`. Fehlt die Datei, ist noch nichts
   installiert — dann ist jede Version ein Update.

2. **Berechtigten Stand abfragen:** `GET https://www.provimedia.de/api/code-guardian/latest`.

3. **Vergleichen.** Stimmen installierte und berechtigte Version
   überein, ist nichts zu tun. Sagen Sie das dem Nutzer und hören Sie
   auf — laden Sie nicht „sicherheitshalber" trotzdem.

4. **Laden**, wenn die berechtigte Version neuer ist: `download_url` aus
   der Antwort verwenden, nicht selbst zusammenbauen.

5. **Prüfsumme kontrollieren.** Das `sha256`-Feld aus der Antwort muss
   zur geladenen Datei passen:

   ```bash
   shasum -a 256 code-guardian-update.zip
   ```

   Weicht sie ab, **nicht installieren** — Datei löschen, erneut laden,
   und bei erneuter Abweichung den Nutzer informieren.

6. **Entpacken und installieren.** Im entpackten Paket liegt
   `install.sh`; führen Sie es aus. Was sich geändert hat, steht in der
   beiliegenden `UPDATE-ANLEITUNG.md` — lesen Sie sie und fassen Sie dem
   Nutzer die Änderungen zusammen.

7. **Aufräumen.** ZIP und Entpack-Verzeichnis entfernen.

---

## 5. Fehlercodes

Jede Fehlerantwort ist JSON mit `error`, `message` und `hint`.

| HTTP | `error` | Bedeutung und richtige Reaktion |
|---|---|---|
| 401 | `missing_licence_key` | Kein Header gesetzt. Prüfen, ob der Schlüssel in der `CLAUDE.md` steht. |
| 401 | `invalid_licence_key` | Unbekannter Schlüssel — meist ein Tippfehler oder ein im Portal neu erzeugter Schlüssel. Den Nutzer bitten, ihn im Portal nachzusehen. Nicht wiederholt probieren. |
| 403 | `licence_not_paid` | Zahlung noch nicht verbucht. Später erneut versuchen, nichts weiter tun. |
| 403 | `subscription_required` | Die gewünschte Version erschien nach dem Ende des Update-Zeitraums. Siehe Abschnitt 6. |
| 404 | `no_entitled_release` | Für diese Lizenz ist derzeit keine Version freigegeben. |
| 404 | `release_not_found` | Diese Versionsnummer gibt es nicht. Verfügbare Versionen über `/status` erfragen. |
| 404 | `release_file_missing` | Serverseitiges Problem. Dem Nutzer melden, an info@provimedia.de zu schreiben. |
| 429 | — | Zu viele Anfragen. Einmal abwarten, nicht in einer Schleife wiederholen. |

---

## 6. Wenn eine neuere Version das Abo braucht

Kommt `subscription_required` oder ist
`newer_version_requires_subscription` gesetzt, sagen Sie dem Nutzer
sinngemäß:

> Ihre Lizenz umfasst Version *X*. Version *Y* ist erschienen, nachdem
> Ihr Update-Zeitraum am *TT.MM.JJJJ* endete. Mit einem Update-Abo für
> 25,00 € netto im Monat steht sie sofort bereit — starten oder
> kündigen können Sie es jederzeit selbst unter https://www.provimedia.de/code-guardian/portal.

Wichtig und ausdrücklich zu erwähnen: **die Lizenz läuft nicht ab.**
Alle Versionen, die während des bezahlten Zeitraums erschienen sind,
bleiben dauerhaft abrufbar — auch nach einer Kündigung und auch auf einem
neuen Rechner. Ohne Abo kommen lediglich keine neueren hinzu.

Installieren Sie in diesem Fall die berechtigte Version, statt gar nichts
zu tun.

---

## 7. Grenzen

- Diese API liefert ausschließlich Code-Guardian-Pakete.
- Ein Lizenzschlüssel gehört zu genau einem Unternehmen. Er darf im
  lizenzierten Unternehmen beliebig oft eingesetzt werden, aber nicht
  darüber hinaus weitergegeben werden.
- Der Zugriff wird protokolliert (Zeitpunkt der letzten Nutzung je
  Lizenz), nicht jedoch, welches Projekt oder welcher Rechner anfragt.

Fragen zur Lizenz: info@provimedia.de