CLAUDE.md: local build, Gitea shipping flow and Katan rule sets

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016eTor2tpxKb4dXbd8RqnvZ

CLAUDE.md

@@ -1,78 +1,61 @@
-> **Moved to Gitea.** CI now runs on Gitea Actions at
-> `git.wallacenet.ca/devadmin/ProLibertateGames`, publishing to Cloudflare Pages
-> (`plg.wallacenet.ca`) only. The sandbox notes below describe the earlier GitHub
-> setup (no CI run from session pushes, `workflow_dispatch` as the workaround);
-> re-verify them against Gitea before relying on them.
-
 # Working on this repo with Claude
 
-## Nothing a session does triggers CI. Dispatch it explicitly.
+CI runs on **Gitea Actions** at `git.wallacenet.ca/devadmin/ProLibertateGames`
+(workflows in `.github/workflows/`), publishing to Cloudflare Pages
+(`plg.wallacenet.ca`). The workflow below was measured on the dev machine
+(`~/ProLibertateGames`); it replaces the earlier GitHub-sandbox notes, which no
+longer apply.
 
-GitHub creates **no workflow run** for anything this sandbox does — pushing a
+## Build, test and lint locally
-branch, opening a pull request, or merging one. All of it goes through the same
-integration, and GitHub suppresses event-triggered runs from it. The pull
-request will say it was opened by the repo owner; that is only how the UI
-attributes it, and it does not change the suppression.
 
-This was measured, not assumed:
+Gradle works on the dev machine. Two environment variables are required: the
+default JDK is 25, which Gradle 8.14 cannot use, and the Android SDK lives in the
+home directory.
 
-| Action | Result |
+```
-| --- | --- |
+export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
-| Human pushes a Claude-authored commit (`d165e5ef`, `469c900e`) | CI runs |
+export ANDROID_HOME=$HOME/android-sdk      # platform 34, build-tools 34.0.0
-| Session pushes `dev` / `main` (`43394b8`, `742add4`) | no run |
+./gradlew testDebugUnitTest lintDebug assembleDebug
-| Session opens a PR against `dev` (#1) | no run |
+```
-| Session calls `workflow_dispatch` | **runs** |
 
-`workflow_dispatch` works because it creates a run directly instead of relying
+The Katan tests run in seconds; a clean build takes a few minutes. Run the full
-on an event. It is the only mechanism available from a session, so every build
+suite, lint and `assembleDebug` before pushing: they are what CI runs. There is
-has to be asked for by hand.
+no KVM, so no emulator; the engine and the UI logic are covered by unit tests
+(see `docs/UI-catan.md`).
 
-## Verify before merging, without publishing
+## Shipping: branch, PR, CI, merge
 
-`ci.yml` builds, tests and lints on any ref, but its staging and publishing
+1. Branch from `dev`; before pushing, merge `origin/dev` in (it moves between
-steps are gated on `github.ref == 'refs/heads/dev'`. Dispatching it on a
+   sessions).
-**feature branch** therefore gives the full check — build, unit tests, Android
+2. Plain `git push` has no credentials. Use the Gitea token as a one-off header:
-lint — and publishes nothing.
+   `git -c "http.extraheader=Authorization: token $(cat ~/.config/gitea/token)" push -u origin <branch>`.
-
+3. Open the PR with `POST /api/v1/repos/devadmin/ProLibertateGames/pulls`
-So the working loop is:
+   (same token, `Authorization: token ...`). CI (`ci.yml`) runs on the PR: build,
-
+   unit tests and Android lint; it publishes nothing. Poll
-1. Commit and push the feature branch.
+   `/actions/runs` until it completes (about 7 minutes).
-2. Dispatch `ci.yml` on that branch. Wait for green. This is the real review
+4. Merge with `POST .../pulls/N/merge {"Do":"merge"}`. The push to `dev` runs
-   gate, and it is the only verification that exists (see below).
+   `ci.yml` again and publishes the build (about 9 minutes).
-3. Open the PR through the API and merge it there, so the change is reviewable
-   and the merge commit is honest about what happened. Neither step builds
-   anything.
-4. Dispatch the target branch's workflow to actually build and publish:
-   `ci.yml` on `dev`, `release.yml` on `main`.
-
-Skipping step 4 leaves a branch whose head was never built and no release.
 
 ## Merging is a shipping action
 
 Both long-lived branches publish, so a merge is a release, not just an
 integration:
 
-- **`dev`** → `ci.yml` publishes a `v<series>.N-dev` **prerelease**, offered by the
+- **`dev`** publishes a `v<series>.N-dev` build to
-  in-app updater to anyone on the Dev channel.
+  `https://plg.wallacenet.ca/dev/latest.json`, offered by the in-app updater to
-- **`main`** → `release.yml` publishes a **production** release, which the
+  anyone on the Dev channel.
-  updater installs for everyone on the Production channel.
+- **`main`** runs `release.yml` and publishes a **production** release for
+  everyone on the Production channel. Confirm before merging to `main`.
+  `release.yml` runs `assembleDebug` only (no tests, no lint), so a `main`
+  release is only as verified as the `dev` build it replays.
 
-Confirm before shipping to `main`. Note that `release.yml` runs `assembleDebug`
+## Katan
-only — no tests, no lint — so a `main` release is only as verified as the `dev`
-build it replays.
 
-## Gradle does not run in the sandbox
+The island game is catalogue id `catan`, shown as **Katan**. It has two rule
-
+sets chosen at setup: the base game (`docs/RULES-catan.md`) and Cities & Knights
-`./gradlew` cannot resolve the Android plugin here: the proxy blocks
+(`docs/RULES-catan-ck.md`, code in `game/catan/CatanCk*.kt`, state behind
-`dl.google.com` with a 403. No local build, no local test run, no local lint. A
+`CatanState.ck`, which is null in the base game). The screen is layered; see
-dispatched CI run is the only way to find out whether a change compiles.
+`docs/UI-catan.md` before changing it.
-
-## A permanent fix, if you want one
-
-The suppression is a property of the sandbox's credential, so it cannot be
-fixed from inside a session. Giving the environment a personal access token to
-push with would make pushes and PRs behave normally for everyone. Until then,
-the dispatch step above is the workaround.
 
 ## Bash output is filtered before it reaches the model