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).
- **Umfang und Phasen stehen in `PLAN.md`** (vereinbart 2026-11-13): 9×9, nur Englisch, Karte des Tages mit
  Bestenliste, Streak und Ergebniskarte, kein Menü/Footer. Spieldesign entscheidet weiterhin der Besitzer.

## 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: GPL-3.0** (entschieden 2026-11-13). Das Gerüst der Vorlage bleibt BSD-3-Clause (`LICENSE-TEMPLATE.md`).
  Fremd-Assets mit Nachweis in `CREDITS.md`: Musik CC BY-SA 4.0 (Nennung im Spiel nötig), Sprites CC0.

## Jam – Regeln (Stand 2026-11-13)

Quelle: Übersichtsseite, vom Besitzer kopiert nach `rules/` (lokal, in `.gitignore`). Devpost blockt automatische
Abrufe (403).

- **Abgabe: 9. Dezember 2026, 03:00 MEZ** (Jam 11. Nov. bis 8. Dez.).
- Aufgabe: ein **Daily Game** auf Devvit Web (Interactive Posts): kurzer täglicher Ablauf, frische Inhalte (tägliche
  Challenges, Rätsel, Karten), leicht zu lernen, wiederspielbar.
- **Portierung erlaubt**: eigene Kategorie „Best Ported Daily Game“ (6.000 $). Das Original (die IP) muss man selbst
  besitzen; bei der Einreichung **angeben, dass es eine Portierung ist**.
- Einreichung: **App-Listing** auf developers.reddit.com und **Demo-Post** (Link zu einem Subreddit mit öffentlichem
  Post, in dem das Spiel läuft – danach wird bewertet, also selbsterklärend machen). Optional: Feedback-Umfrage.
  **Kein Repo-Link, kein Video verlangt.**
- **Nicht veröffentlichen** (`devvit publish` / App Review): hochladen und playtesten reicht, die App darf privat
  bleiben.
- Bewertung: Delightful UX, Polish (nahe an Veröffentlichungsqualität, Devvit-Regeln einhalten), „Reddit-y“
  (Gemeinschaft, eigene Identität), Daily Content.
- Pluspunkte: schneller Einstieg ohne Textwände, klare eigene Optik, Startbildschirm mit Name/Datum/Statistik,
  **Ergebniskarte** am Ende (Statistik, Streak, Kommentar, Abo-Hinweis), **Devvit Journeys** für Ereignisse,
  Bestenliste und Streaks; Reddit-Funktionen wie Flair, Kommentare, Snoovatare.
- Nicht gewollt: offensichtliche „KI-Optik“ (KI-Nutzung ist erlaubt), Reddit-Klischees als Thema, bekannte
  Spielideen ohne eigenen Dreh, Spiele, die nicht auf Reddit laufen.
- **Offizielle Regeln** (`rules/…rules.md`, vom Besitzer kopiert):
  - Einreichung bis Di 8. Dez. 18:00 PT (= 9. Dez. 03:00 MEZ); **Bewertung 9.–16. Dez.**, Gewinner ca. 17. Dez. Das
    Spiel muss während der Bewertung laufen (Tagesposts, Bestenliste) – in dieser Zeit keine riskanten Uploads.
  - **Bestehende Projekte** zählen nur, wenn sie ab dem 11. Nov. „significantly updated“ wurden, und das muss in der
    Einreichung erklärt werden. Die Devvit-Portierung ist eine neue Codebasis – das in der Beschreibung ausführen.
  - Pflicht: Textbeschreibung, App-Link `developers.reddit.com/apps/ninelands-game`, **ausführliche `README.md` im
    Repo-Wurzelverzeichnis** (Spiel und Anleitung, Englisch), Demo-Post in einem **öffentlichen Subreddit mit
    < 200 Mitgliedern** (oder App `dr-admin-approve` installieren).
  - Optional: Video (< 1 min, öffentlich auf YouTube/Vimeo), öffentliches Repo, Feedback-Umfrage. Die Jury darf auch nur
    nach Beschreibung, Bildern und Video urteilen → Video und Screenshots lohnen sich.
  - Nur Material mit passenden Rechten (Sprites CC0, Musik CC BY-SA mit Nennung – erfüllt). Ein Projekt gewinnt höchstens
    einen Preis. Teilnahme als Einzelperson oder Organisation (StackTeam) – entscheidet der Besitzer bei der Anmeldung.
  - Gleichstand: entscheidet zuerst „Delightful UX“.

## 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: Die `parallel:`-Stufe der Vorlage ersetzt (Forgejo-Runner v13: „Invalid run/uses syntax“), Schritte laufen
  nacheinander.
- `PLAN.md` angelegt, Lizenz auf GPL-3.0 umgestellt.
- Nächste Schritte: offene Fragen in `PLAN.md` klären, dann Phase 0 (Sync-Skript, Engine, Assets).
- Subreddit `r/Ninelands` ist frei (Besitzer hat nachgesehen); anlegen erst für den Demo-Post.

Diese Datei bei neuen Arbeitsregeln und Entscheidungen aktualisieren.