diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f991155
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Workspaces Images is the catalog of pre-built Kasm workspace images (applications and full desktops) published to DockerHub and Quay. Each image layers application-specific install scripts on top of a base image from [workspaces-core-images](https://gitlab.com/kasm-technologies/internal/workspaces-core-images).
+
+## Repository Layout
+
+```
+dockerfile-kasm-<name>      # Flat Dockerfile per image at repo root
+src/
+  ubuntu/install/<app>/     # Install scripts for Ubuntu-based images
+  common/                   # Shared scripts used across distros
+  alpine/, opensuse/, ...   # Distro-specific install scripts
+ci-scripts/
+  template-vars.yaml        # Image manifest: name, base, dockerfile, changeFiles, runset
+  template-gitlab.py        # Generates gitlab-ci.yml from template-vars.yaml
+  build.sh                  # Builds + pushes to cache registry
+  test.sh                   # Runs post-build smoke tests via AWS/curl
+  manifest.sh               # Creates and pushes multi-arch manifests
+  weekly-manifest.sh        # Scheduled rolling-tag manifest updates
+```
+
+## Building Images Locally
+
+```bash
+# Build a single image (run from repo root)
+sudo docker build -t kasmweb/firefox:dev -f dockerfile-kasm-firefox .
+
+# Run it locally
+sudo docker run --rm -it --shm-size=512m -p 6901:6901 -e VNC_PW=password kasmweb/firefox:dev
+# Access via browser: https://<IP>:6901  (user: kasm_user, password: password)
+```
+
+The `BASE_TAG` build arg controls which core image tag is pulled (default: `develop`). Override with `--build-arg BASE_TAG=<tag>` to build against a specific core release.
+
+## Adding a New Image
+
+1. Create `dockerfile-kasm-<name>` at the repo root. Use an existing dockerfile as a template — the pattern is:
+   - Set `ARG BASE_IMAGE` / `ARG BASE_TAG` and `FROM kasmweb/$BASE_IMAGE:$BASE_TAG`
+   - Add install scripts under `src/<distro>/install/<name>/`
+   - Copy scripts into `$INST_SCRIPTS`, run them, then delete them
+   - Fix ownership with `chown 1000:0 $HOME` and run `set_user_permission.sh`
+   - End with `USER 1000`
+
+2. Add an entry to `ci-scripts/template-vars.yaml`:
+   ```yaml
+   - name: <name>
+     runset: set-a          # or set-b — distributes load across CI run sets
+     singleapp: true        # false for full desktop images
+     base: core-ubuntu-jammy  # or core-ubuntu-noble, core-debian-bookworm, etc.
+     dockerfile: dockerfile-kasm-<name>
+     changeFiles:
+       - dockerfile-kasm-<name>
+       - src/ubuntu/install/<name>/**
+   ```
+
+3. The CI pipeline is generated — do **not** edit `gitlab-ci.yml` directly; edit `template-vars.yaml` and `template-gitlab.py` instead.
+
+## CI/CD
+
+The pipeline runs in two stages:
+
+1. **template** — `template-gitlab.py` reads `template-vars.yaml` and generates `gitlab-ci.yml` as a CI artifact.
+2. **run** — triggers a child pipeline from the generated `gitlab-ci.yml`.
+
+Key CI variables (set in GitLab or pipeline triggers):
+- `BASE_TAG` — core image tag to build against (default: `develop`)
+- `USE_PRIVATE_IMAGES` — set to `1` to pull from private registry
+- `KASM_RELEASE` — release version string for test installer
+- `RUN_SET` — restrict CI to `set-a` or `set-b` image subsets
+- `MIRROR_ORG_NAME` — DockerHub org for mirror pushes (default: `kasmtech`)
+
+On `develop` and `release/*` branches, images are pushed publicly to DockerHub and Quay. Feature branches push only to an internal cache registry tagged `<arch>-<name>-<branch>-<pipeline_id>`.
+
+## Image Naming Conventions
+
+- Single-app images use `singleapp: true` and strip the XFCE panel for a focused UI.
+- Desktop images (`singleapp: false`) ship the full XFCE desktop environment.
+- Base image names follow `core-<distro>-<codename>` (e.g. `core-ubuntu-jammy`, `core-ubuntu-noble`, `core-debian-bookworm`).
+- Published tags: `kasmweb/<name>:<branch>` for branch builds, `kasmweb/<name>:<version>` for releases.
+
+## Distro Support
+
+Install scripts are organized under `src/<distro>/install/<app>/`. Ubuntu scripts (jammy/noble) are the most common. When adding support for a new distro, add scripts under the appropriate `src/<distro>/` subtree and reference them in the dockerfile.