# CLAUDE.md — mana-swift-core

Guidance für Claude Code in diesem Repo.

> **Übergeordneter Plan:** `../mana/docs/MANA_SWIFT.md` ist die SOT für
> die ganze native-App-Plattform. Dieses CLAUDE.md ist die Repo-lokale
> Konventionen-Doku.

## Was dieses Repo ist

Swift-Package-Plattform für alle nativen mana-e.V.-Apps. Enthält genau
zwei Library-Products:

- **ManaCore** — Auth (mana-auth-Login, JWT-Refresh, Keychain),
  Transport (URLSession-Wrapper mit 401-Retry).
- **ManaTokens** — Verein-Designwerte. Spiegelt `mana/docs/THEMING.md`.

Wird konsumiert von `memoro-native`, geplant `cards-native`,
`nutriphi-native` und weiteren.

## Status

**v1.0.0 — initiale Extraktion aus memoro-native (2026-05-12).**

Phase α aus `mana/docs/MANA_SWIFT.md` — wortwörtliche Verschiebung
von `Core/Auth`, `Core/API/Transport`, plus `ManaTokens` neu aus
`mana/docs/THEMING.md`. Keine spekulativen Verallgemeinerungen.

## Architektonische Invarianten

Nicht ohne explizite Diskussion antasten:

1. **Genau zwei Library-Products.** ManaCore + ManaTokens. Ein
   `ManaUI`-Komponenten-Package entsteht später in einem **eigenen**
   Repo, nicht hier (`mana/docs/MANA_SWIFT.md` Phase ε).
2. **Keine externen Dependencies.** ManaCore darf nur Foundation,
   Security, OSLog, Combine importieren. Kein Alamofire, kein Sentry,
   kein nichts. Compliance (`mana/docs/COMPLIANCE.md`) + Build-Stabilität.
3. **Public API ist `Sendable`.** Jeder Cross-Actor-Type. Swift-6-
   Concurrency-Korrektheit.
4. **Keine app-spezifischen Annahmen.** ManaCore weiß nichts über
   Memos, Decks, Meals. PRs, die "irgendwas für Memoro" hinzufügen
   wollen, gehören in memoro-native, nicht hier.
5. **mana-auth-Wissen ist erlaubt.** Endpoint-Pfade `/api/v1/auth/login`,
   `/api/v1/auth/refresh`, Wire-Format mit `accessToken`/`refreshToken`.
   Das ist Verein-Plattform-Konstante, nicht App-Detail.
6. **OSLog statt print/Sentry.** ManaCore loggt intern unter Subsystem
   `ev.mana.core`. Apps haben ihr eigenes Subsystem.
7. **App injiziert ihre Config.** ManaCore hardcoded *nichts* (außer
   die mana-auth-Endpoint-Pfade als Konstante). `authBaseURL`,
   `keychainService`, `keychainAccessGroup` kommen vom App-Caller.
8. **Tests gegen reine Logik.** JWT-Decode, Token-Expiry, Keychain-
   Key-Mapping. URLSession-Calls werden über Protokoll-Injection
   getestet, nicht über echtes Netzwerk.

## Versionierung

- **Semver strikt.** Patch = Bugfix ohne API-Änderung. Minor = neue
  API additiv. Major = breaking.
- **Git-Tag nach jedem Sinn-Abschnitt** auf `main`. Nicht jeden Commit.
- **CHANGELOG.md pflicht.** Was hat sich geändert, müssen Apps was anpassen.
- **Pflege-Politik:** Letzte zwei Major-Versionen werden mit Patches
  bedient. Ältere nicht.

## Konventionen

- **Swift 6.0**, Strict Concurrency komplett
- **iOS 18 / macOS 15** Minimum (gleiche Targets wie memoro-native)
- **SwiftFormat** mit `.swiftformat` (4-space, 120-col, sorted imports)
- **SwiftLint** mit `.swiftlint.yml`
- **Doc-Comments** pflicht auf jedem `public`-Symbol (`///`)
- **Lokalisierung:** Public-API-Strings auf Deutsch (Verein-Konvention),
  Code-Identifier auf Englisch

## Lokal entwickeln

```bash
swift build                          # baut beide Targets
swift test                           # Unit-Tests
swift package generate-xcodeproj     # optional, für Xcode
```

Für die Integration in eine App (memoro-native, cards-native):

- Dev-Cycle: in `project.yml` der App `path: ../mana-swift-core` setzen
- Release: `from: 1.0.0` mit Git-Tag

## Wenn eine neue Funktion dazukommt

1. Frage: gehört das wirklich in ManaCore/ManaTokens, oder ist es
   App-spezifisch? Wenn unsicher: in die App, später extrahieren.
2. Public API mit Doc-Comments.
3. Unit-Tests gegen die State-Machine, nicht gegen echtes Netzwerk.
4. CHANGELOG.md ergänzen.
5. Bei Breaking-Change: Major-Bump-Plan in `mana/docs/MANA_SWIFT.md`
   notieren, alle aktiven Apps informieren.

## Wichtige Cross-Repo-Doks

- `mana/docs/MANA_SWIFT.md` — Plattform-SOT für native Apps
- `mana/docs/MANA_AUTH_FEDERATION.md` — Auth-Protokoll
- `mana/docs/THEMING.md` — Token-SOT, spiegelt sich in ManaTokens
- `mana/docs/COMPLIANCE.md` — Telemetrie/Crash-Reporter-Regeln
- `mana/services/mana-auth/CLAUDE.md` — Server-Konventionen, §
  "Native-App-Koordination" beschreibt die Refresh-Token-Invariante
- `memoro-native/CLAUDE.md` — erste Konsumenten-App, Konventionen
  hier sind aus deren PLAN.md gewachsen