# 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](https://github.com/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.pilgrimsofkatan` (+ `.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

```sh
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 <noreply@paperclip.ing>`.
- 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).