diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..636123e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+A single-purpose repository that builds a **CI base image**: `eclipse-temurin:17`
+(Java 17) extended with Node.js and the Docker CLI/daemon (via `get.docker.com`).
+The resulting image is meant to be used as a build/runner environment that needs
+Java, Node, and Docker-in-Docker available together.
+
+There is no application code, no test suite, and no build tooling — the entire
+deliverable is the [Dockerfile](Dockerfile). "Building" means building the Docker
+image; "shipping" means pushing it to the Gitea container registry.
+
+## Commands
+
+```bash
+# Build locally (mirror what CI does)
+docker build -t gitea.tail276105.ts.net/boxi/ci-image:local .
+```
+
+CI builds and pushes automatically — see below. There is nothing to lint or test.
+
+## CI/CD — Gitea Actions
+
+[.gitea/workflows/docker.yml](.gitea/workflows/docker.yml) runs on every push to
+`main` and: logs in to the registry → builds the image → tags it as both
+`${GITHUB_RUN_NUMBER}` and `latest` → pushes both → logs out.
+
+Target registry: `gitea.tail276105.ts.net`, image path `boxi/ci-image`
+(derived from `${{ gitea.repository }}`, lowercased).
+
+### Registry auth — important gotchas
+The push step is the fragile part. Login can succeed while the push fails with
+`401 Unauthorized` on `blobs/uploads`. That is **not** a workflow bug — it means
+the credentials authenticate but lack write access to the `boxi` package
+namespace. Requirements:
+- `REGISTRY_USER` must be the **namespace owner** (`boxi`) or a user with write
+  access to that namespace — a separate service user cannot push to `boxi/...`.
+- `REGISTRY_PASSWORD` should be a Gitea **access token with `write:package`
+  scope** (Gitea → Settings → Applications → Manage Access Tokens). The plain
+  account password fails when 2FA is enabled.
+
+### Package ↔ repository linking
+A pushed package shows up under the **user namespace**, not automatically under
+the repository's **Packages** tab. Auto-linking via the
+`org.opencontainers.image.source` label in the Dockerfile is unreliable here
+because BuildKit produces a multi-arch manifest list with an attestation
+manifest, which Gitea's label-based linking does not reliably read. Link the
+package to the repo **manually once** in the Gitea UI (Package → Package
+Settings → Repository); the link then persists across future pushes.
+
+## Conventions
+- Commits & pushes are done by the maintainer manually — do not commit or push
+  unless explicitly asked.
+- Node 16 in the Dockerfile is EOL; bumping the `setup_NN.x` version is a known
+  pending improvement but is intentionally left untouched to keep scope small.