ProLibertateGames/CLAUDE.md

Working on this repo (agent notes)

ProLibertateGames — Wallacenet's build of an Android collection of card and board games, playable against AI or over Wi-Fi (LAN). Upstream: adrianoftyriel/ProLibertateGames (GPL-3.0, kept as the upstream remote). Canonical repo: https://git.wallacenet.ca/devadmin/ProLibertateGames.

Ground rules

• Licences travel. LICENSE is GPL-3.0 and must stay. The Uncial Antiqua font ships with its OFL licence at docs/licenses/UncialAntiqua-OFL.txt; never delete or edit either. Attribution to the upstream lives in the README.
• No Catan trademarks or brand assets — the one hard line. The app's own branding is the upstream's, restored (see README → Branding): tartan launcher icon and splash, Wallace clan red on production and hunting green on dev, launcher names Pro Libertate Games / Pro Libertate Games DEV. The installed identity is ca.wallacenet.prolibertategames (+ .dev).
• The existing catalogue is the regression safety net. Keep every game green; new games (Katan) arrive as separate tasks, not edits to old ones. The 22 reference games are available = true; Katan is listed with available = false (Coming soon) until its game task lands.
• Docs conventions: every game gets docs/RULES-<id>.md (index and gaps in docs/README.md); build/CI/release decisions go in docs/CI.md. Update the docs when behaviour changes — they are the check against the rules code.

Build

export JAVA_HOME=...   # JDK 17
export ANDROID_HOME=...  # SDK with platform 34, build-tools 34
./gradlew assembleDebug            # dev-channel APK (default)
PLG_CHANNEL=production ./gradlew assembleDebug   # production APK
./gradlew testDebugUnitTest        # JVM unit tests (rules/AI/net/score)
./gradlew lintDebug                # Android lint (CI runs it)

On the Wallacenet project workspace a ready toolchain sits at ../.toolchain/ (jdk17/, android-sdk/) — export JAVA_HOME and ANDROID_HOME to it rather than installing again. Both variants must build: they install side by side (different applicationId, launcher name, colour).

Channels and OTA

One flag — isDevBuild in app/build.gradle.kts — drives applicationId, launcher name and brand colour together. Never set them individually.

In-app OTA points at this repo's own Gitea releases (/api/v1/repos/devadmin/ProLibertateGames/releases…) and is on: BuildConfig.OTA_ENABLED is true. The channel is a decision already made and recorded — docs/CI.md documents the endpoints, the build-number scheme, and what publishing requires. Setting the flag to false is the kill switch.

CI

.github/workflows/ — Actions-compatible so the Gitea instance runs them. ci.yml: build + test + lint + artifact, and a dev prerelease from dev. release.yml: production release from main. Both publish through scripts/publish-release.sh (Gitea REST API), which is also runnable by hand.

No Actions runner is registered on the instance yet, so the workflows are idle until one is — the local gradle commands above are the source of truth, and CI green means those plus lint. Do not treat a workflow that has never run as evidence.

Code map

• game/ — rules engines and AI, pure Kotlin, no Android types, unit tested. Catalog.kt is the registry (id, title, blurb, options, available).
• net/ — wire protocol, LAN transport (mDNS + TCP), lobby, host-authoritative match driver; score/ the scorekeeper sheet, also pure.
• ui/ — Compose screens; ui/theme/Theme.kt holds the brand palette (BrandField/BrandDeep/BrandAccent) and table accents.
• update/ — OTA policy (UpdatePolicy.kt, pure and tested) and the gated fetch (Updater.kt).
• settings/ — DataStore preferences.

Host is authoritative over the wire; clients send intents, host re-validates against the rules. Keep game/ free of Android imports — the JVM tests depend on it.

Git

• Branches: main (production), dev (integration). Feature branches → PR into dev.
• Commits by Paperclip agents end with Co-Authored-By: Paperclip <[email protected]>.
• Pull upstream fixes with git pull upstream (the GitHub source); do not point origin anywhere but this repo's Gitea URL.

Legacy files

.claude/ and .rtk/ are the upstream author's assistant tooling, harmless and left as inherited. This file supersedes the upstream's CLAUDE.md (which documented their GitHub sandbox; that history is still in git).