diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a38e5a4
--- /dev/null
+++ b/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://git@192.168.68.76: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.