ninelands-reddit/CLAUDE.md

# CLAUDE.md – Ninelands für Reddit (Devvit)

Diese Datei lädt Claude Code in jeder Sitzung. Sie hält fest, **was** dieses Projekt ist, **wie** gearbeitet wird und
**wo** wir stehen. Stand: 2026-11-13, frisch angelegt aus der Devvit-Vorlage **Bare**.

## Projekt

- **Ninelands auf Reddit**: eine Basic-Version von [Ninelands](https://ninelands.stackteam.at) als Reddit-Spiel
  (Devvit Web) für den Jam **Reddit Game of the Day 2026** – https://redditgameofday2026.devpost.com/ (Regeln:
  `/rules`). Besitzer: Lukas Müllner (StackTeam). Mit dem Besitzer **Deutsch** sprechen.
- App-Name in `devvit.json`: `ninelands-game`. Ordner: `/data/Documents/projects/ninelands-game`.
- Repo: `git@git.stackteam.at:DieLustigeTierwesen/ninelands-reddit.git` (Forgejo, privat, angelegt 2026-11-13).
- **Was die Basic-Version können soll, ist noch offen** – das klären wir zuerst gemeinsam (Spieldesign entscheidet der
  Besitzer). Vorher nichts Spielerisches bauen.

## Woher Fragen beantwortet werden

- **Das Hauptspiel** (Regeln, Engine, Gestaltung): Repo `DieLustigeTierwesen/DokuHive`, lokal
  `/data/Documents/projects/hivedoku` – dort `README.md`, `hicedoku_plan.md` (Entscheidungen „as built“),
  Leitfaden `guide/chapters/`. Bei Fragen zu Regeln oder Absicht **dort nachlesen**, nicht raten.
- **Allgemeiner Spiele-Blueprint** (Arbeitsweise, Fallstricke, Releases): Repo `DieLustigeTierwesen/game-blueprint`,
  lokal `/data/Documents/projects/game-blueprint/AGENT.md`. Erkenntnisse, die für künftige Spiele gelten (z. B. „wie
  baut man ein Devvit-Spiel“), dort nachtragen.

## Grenzen zum Hauptspiel

- **In `/data/Documents/projects/hivedoku` nichts ändern, committen oder pushen.** Jeder Push auf dessen `main`
  deployt die Live-Seite; Releases dort (itch, Desktop, Android) laufen über `npm run release` und gehören nicht zu
  diesem Projekt.
- Die Engine von Ninelands (`hivedoku/src/core`, reines TypeScript ohne DOM/Server, seeded RNG, `applyMove`,
  `legalMoves`, Replay) darf übernommen werden – als **Kopie mit festem Stand** (z. B. Sync-Skript, das `src/core` von
  einem Ninelands-Tag holt und den Tag notiert). Die Kopie hier **nicht von Hand ändern**; Änderungen an der Engine
  gehören ins Hauptspiel. Achtung: `src/core` importiert JSON aus `../campaign/` und `../puzzles/` – nur mitnehmen,
  was die Basic-Version braucht.
- **Lizenz klären, bevor Engine-Code kopiert wird:** Ninelands steht unter **GPL-3.0**, diese Vorlage unter
  **BSD-3-Clause** (`LICENSE` stammt aus der Devvit-Vorlage). Kopierte GPL-Teile machen das Ganze GPL – die Lizenz
  entscheidet der Besitzer (auch, ob der Jam eine Open-Source-Lizenz verlangt).

## Jam – vor der Arbeit prüfen

Die Devpost-Seiten blockieren automatische Abrufe (403). Der Besitzer liefert die Regeln; offen sind:

- Darf ein **bestehendes Spiel** (Basic-Version von Ninelands) eingereicht werden, oder nur während des Jams
  Entstandenes? Muss Vorhandenes angegeben werden?
- Abgabefrist, Pflichtteile der Einreichung (Video, Repo-Link, Test-Subreddit, Beschreibung), Bewertungskriterien,
  Regeln zu KI-Nutzung und Fremdcode.

Ergebnis hier unter „Stand“ festhalten.

## Technik (Vorlage Bare)

- Devvit Web: Client `src/client/` (Splash `splash.ts` → `public/splash.html`, Spiel `game.ts` → `public/game.html`),
  Server `src/server/` (`index.ts`, `server.ts`, Speicher `db.ts`), gemeinsame Typen `src/shared/api.ts`.
  Gebaut mit **esbuild** nach `public/` und `dist/server/`.
- Werkzeuge der Vorlage beibehalten: **Biome** (Lint + Format, `npm run lint` / `npm run format`) statt Prettier,
  Tests mit `node --test` (`*.test.ts`), Typprüfung `tsc --build`.
- Befehle: `npm run test` (Typen, Lint, Unit-Tests, Build – **das ist die Prüfung vor jedem Merge**),
  `npm run playtest [r/sub]` (baut, lädt hoch, installiert im Test-Subreddit), `npm run publish` (lädt hoch und
  stellt einen **Review-Antrag** bei Reddit – nur nach Rückfrage beim Besitzer).
- Node 24 über nvm (global ist 20): Befehle mit `source ~/.nvm/nvm.sh && nvm use 24 >/dev/null &&` beginnen.
- Kein eigener Server, keine eigene Datenbank, keine eigenen Konten: Spieler sind Reddit-Nutzer, gespeichert wird
  über Devvit (Redis). Externe Netzaufrufe sind bei Devvit eingeschränkt – vor jeder Idee, die das Ninelands-Backend
  anspricht, in der Devvit-Doku prüfen (https://developers.reddit.com/docs).
- Aktuelle Devvit-Doku lesen, bevor etwas gebaut wird – die Plattform ändert sich schnell; nicht aus dem Gedächtnis
  arbeiten.
- `.github/workflows/ci.yaml` stammt aus der Vorlage. Forgejo führt `.github/workflows` aus, wenn es kein
  `.forgejo/workflows` gibt; `runs-on: ubuntu-latest` ist der gemeinsame Hetzner-Runner (für `npm run test` reicht er).

## Arbeitsweise

- **Ein Branch pro Änderung** (`feat/…`, `fix/…`, `chore/…`), auch für Doku.
- **Merge nur, wenn `npm run test` mit Exit-Code 0 endet.** Ausgabe in eine Log-Datei, dann `$?` prüfen – nie mit
  `| grep … &&` oder `;` verketten. Muster: `npm run test > log 2>&1; code=$?; if [ $code -eq 0 ]; then … merge; fi`.
- `git merge --no-ff`, Branch löschen, `main` pushen (sobald ein Remote existiert), im Bericht erwähnen.
- Conventional Commits; Ende jeder Nachricht: `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
- Code-Kommentare auf Deutsch.
- Größere Entscheidungen und Fallstricke in `PLAN.md` (Abschnitt „as built“, Deutsch) festhalten; am Ende eines
  Schritts Erkenntnisse von sich aus nennen.
- Innerhalb eines vereinbarten Plans selbstständig weitermachen; anhalten bei Spieldesign, Geschmack, externen Konten,
  Geld, Lizenz und allem, was öffentlich wird (`devvit publish`, Posts in echten Subreddits).
- **Kein Geld ausgeben.**

## Geheimnisse – nie ausgeben, nie committen

- Devvit-Token `~/.devvit/token` (Reddit-Anmeldung des Besitzers): nie lesen, ausgeben oder kopieren; die
  `devvit`-Befehle nutzen ihn selbst.
- Forgejo-Token `~/.config/forgejo-token`: nur innerhalb von Befehlen lesen.
- Nutzer sollen nie Schlüssel in den Chat kopieren.

## Stand (2026-11-13)

- Vorlage **Bare** committet, Repo `DieLustigeTierwesen/ninelands-reddit` angelegt, `main` gepusht. Lint der Vorlage
  repariert (Biome-Schema 2.6.4 → 2.6.6, `package.json` ohne Schlusszeilenumbruch); `npm run test` lokal grün.
- **CI auf Forgejo rot** (Lauf 1 und 2, Workflow aus der Vorlage). Verdacht: die `parallel:`-Stufe in
  `.github/workflows/ci.yaml` (GitHub-Neuheit, Forgejo kennt sie vermutlich nicht) oder die per SHA gepinnten Actions
  (`checkout` v7, `setup-node` v6). Log-Zeilen vom Besitzer aus dem Browser holen, dann gezielt reparieren.
- Nächste Schritte:
  1. CI reparieren (siehe oben).
  2. Jam-Regeln vom Besitzer übernehmen (siehe oben).
  3. Mit dem Besitzer festlegen, was die Basic-Version kann.
  4. Lizenz entscheiden, dann Engine-Kopie + Sync-Skript.

Diese Datei bei neuen Arbeitsregeln und Entscheidungen aktualisieren.