diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c668bdf
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+Context for future agent work in this repo. The README covers consumer-facing
+usage; this file covers things that aren't obvious from reading the code.
+
+## Where this action runs
+
+Hosted on a self-hosted Gitea at `git.lair.cafe` (remote name `origin`,
+SSH url `gitea@git.internal:actions/copr-publish.git`). Consumers reference
+it by fully-qualified URL (`uses: https://git.lair.cafe/actions/copr-publish@v1`)
+because Gitea's `DEFAULT_ACTIONS_URL` points at github.com.
+
+There is **no CI on this repo itself**. The action is tested by running it
+from a consumer repo (primarily `helexa/cortex`). When debugging, fetch job
+logs via the `gitea-mcp` tools against the consumer repo, not this one —
+e.g. `mcp__gitea-mcp__actions_run_read` with `owner=helexa`, `repo=cortex`.
+
+## Tagging & release workflow
+
+We use a **floating major tag** alongside specific semver tags:
+
+- `v1.0.0`, `v1.0.1`, ... — immutable, annotated, per release.
+- `v1` — floating annotated tag, moved forward to the latest `v1.x.y` on
+  every v1 release. This is what `@v1` consumers resolve to.
+
+When cutting a patch/minor release within v1:
+
+```bash
+git tag -a v1.0.N -m "v1.0.N\n\n<summary>" <sha>
+git tag -a v1 -f -m "v1 (floating): latest v1.x release" <sha>
+git push origin main v1.0.N
+git push origin v1 --force     # floating tag move requires --force
+```
+
+The `--force` on the `v1` push is expected and authorized — that's how the
+floating tag works. Do **not** force-push `main` or immutable `vX.Y.Z` tags.
+
+A `v2` is reserved for the live-streaming behaviour change tracked in
+issue #1 (stdout timing differs enough that consumers should opt in). Do
+not quietly land that on `v1`.
+
+## The COPR builder-live.log gotcha
+
+The on-mirror file served by `copr-cli download-build` is
+`builder-live.log.gz` for completed builds — not plain `builder-live.log`.
+The script in `scripts/copr-build.sh` handles both, preferring `.gz` with
+`zcat`. If you add log handling for other COPR artifacts (`build.log`,
+`root.log`, `backend.log`), assume they are gzipped too.
+
+The **HTTP live endpoint** at
+`https://download.copr.fedorainfracloud.org/results/<owner>/<project>/<chroot>/<build_id>-<pkg>/builder-live.log`
+serves plaintext during and after the build — that's the path issue #1's
+live-streaming approach would use, sidestepping the `.gz`-on-disk issue.
+
+## Testing a change
+
+There is no local harness. To verify a change end-to-end:
+
+1. Commit + push + tag as above (or push a branch and reference it by
+   commit SHA from the consumer).
+2. Trigger a workflow in the consumer repo (e.g. push to `helexa/cortex`).
+3. Inspect the job log via `gitea-mcp` — note that job logs come back
+   base64-ish wrapped in a JSON envelope and with `\r`/`\n` escapes; pipe
+   through `jq -r '.[].text'` then `sed 's/\\r/\n/g; s/\\n/\n/g'` to get
+   something greppable.
+
+Syntax-only check locally: `bash -n scripts/copr-build.sh`.