docs: a CLAUDE.md for agents working in this repository

What the repository is and where things are, the release rules agents
must never bend (a version is used once, nothing is rebuilt, a person
runs every release step), branches, the checks that exist and what each
proves, and the working conventions, including filing an issue for what
is found outside the task at hand.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other coding agents) working in this repository. It points at the
+authoritative sources rather than restating them, because restated details drift. Inspect the actual
+source, tests, scripts, and workflows before relying on anything here or on memory of a prior
+session.
+
+## What this repository is
+
+**Ekklesia Classroom**: the `ekklesia-classroom` Debian package (amd64, Debian 13 "trixie") that turns
+a laptop or desktop into a locked-down KDE Plasma (Wayland) classroom machine for a church: a
+teacher's launcher, the classroom browser and Wonder Ink, Presentations, DVD playback, printing,
+Parent Call messaging, networking and Wi-Fi adoption, a display-size setting, and an updater that
+installs new releases unattended. Machines receive it over the air from the update server
+(`https://updates.riverofglorymn.org`), on the **stable** or **canary** ("Preview") channel.
+
+It is a separate product from the Ekklesia platform repository (`Zayin/Ekklesia`) and its modules,
+and shares no code with them. The platform roadmap (`../ROADMAP.md`, section *Classroom*) plans
+Classroom as a future first-party module whose scope is deliberately **not locked yet**. Do not build
+platform integration (modules, platform devices, accounts) here speculatively; that starts from a
+scope decision, not from code.
+
+Where things are:
+
+| Path | What |
+| --- | --- |
+| `scripts/` | Everything installed as a command: the session, launcher, browser, updater, admin tools |
+| `lib/` | The Python modules those commands share (`classroom_config.py`, printing, presentations, …) |
+| `config/`, `systemd/` | Plasma, SDDM, polkit, D-Bus, udev, and systemd units the package installs |
+| `packaging/debian/` | `control.template` and `postinst` |
+| `tests/test-*.sh` | Every automated test; each runs with no screen and no container |
+| `tools/` | `check.sh`, `build-release.sh`, `release-gate.sh`, the release tooling, and `lab/` |
+| `docs/` | How each feature works and why. `releasing.md` and `testing.md` are the process |
+
+## Releases are never rebuilt, and a person makes every decision
+
+Read `docs/releasing.md` before touching anything release-shaped. Its rules are not negotiable:
+
+- **A version is used once.** Once a file of that name has been on the update server, it is never
+  rebuilt or replaced. Tags (`v` + version) are never moved.
+- **The file the gate passed is the file every room installs**, byte for byte. Nothing is rebuilt
+  after Release 1.
+- **A person runs every release step**: the Release workflows, `update_canary.sh`,
+  `update_stable.sh`, and the physical checks in `docs/testing.md`. Never run them, publish to the
+  update server, reach a classroom machine or the church server (`10.40.0.2`), or create or push a
+  tag. Tests use stand-in servers; keep it that way.
+
+## Branches
+
+`master` is the next feature release; `release/X.Y` is a maintenance line (fixes only). A fix made on
+`release/X.Y` is merged **forward** into `master`, never cherry-picked backwards. `experiment/*` is
+never built as a release. See `docs/releasing.md` → *Branches*.
+
+## Verification
+
+`tools/check.sh` is the one list of checks, run by CI and by every release build:
+
+```bash
+tools/check.sh                 # sources, the manual, every tests/test-*.sh
+tools/check.sh --base <ref>    # and the change since <ref> is clean (git diff --check, no build output)
+```
+
+Beyond that: `tools/build-release.sh VERSION` builds the package (after `check.sh`);
+`tools/release-gate.sh` installs it on a clean Debian container, fresh and as an upgrade (needs
+Docker); `tools/lab/` exercises the real Plasma session and needs the nested session on the
+development VM; and real hardware is `docs/testing.md`. Unit checks passing is not evidence that a
+desktop behaviour works; say which of these you ran.
+
+CI is `.gitea/workflows/ci.yml` (checks, then package and container gate) on the `ekklesia-ci`
+runner. Read its open issues before trusting a red or green run.
+
+## Working conventions
+
+- Canonical remote: `ssh://[email protected]:2222/Zayin/Classroom_Desktop.git` (web and API:
+  `https://git.zayin.net`). The default branch is `master`. Branch from an up-to-date `origin/master`
+  (or `origin/release/X.Y` for a maintenance fix), one branch per pull request. Never push to
+  `master` or `release/*`, never merge your own pull request.
+- Every defect fix gets a test in `tests/`; `check.sh` picks it up with nothing else to edit.
+- Plain language in anything a teacher sees.
+- Report what you find. A defect, flaky test, documentation conflict, or CI problem outside the task
+  at hand gets an issue in the repository it belongs to, as soon as you find it. Search for an
+  existing issue first; something fixed in the same pull request goes in its description instead. Be
+  descriptive: what you saw, the evidence (run and job links, commit, file and line), how to
+  reproduce it, the impact, and options, and never a secret. Label it `found-by-claude` (an agent
+  that cannot apply labels ends the body with a line saying so), leave it unassigned, and list what
+  you filed when you report back.