docs: add CLAUDE.md with hosting, tagging, and testing context

Capture the non-obvious details of working in this repo: Gitea hosting,
the floating-v1-tag release workflow, the builder-live.log.gz gotcha,
and how to fetch consumer-job logs for verification.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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`.

scripts/copr-build.sh

@@ -47,17 +47,22 @@ copr-cli download-build --dest "$LOG_DIR" "$BUILD_ID" || {
   echo "warning: failed to download build artifacts" >&2
 }
 
-# Dump each chroot's builder-live.log as a collapsible group.
+# Dump each chroot's builder-live.log as a collapsible group. COPR stores
+# the log gzipped on the mirror once the build has finished; fall back to
+# the plain file in case a backend version ever serves it uncompressed.
 for chroot_dir in "$LOG_DIR"/*/; do
   [ -d "$chroot_dir" ] || continue
   chroot=$(basename "$chroot_dir")
-  log="${chroot_dir}builder-live.log"
-  if [ -f "$log" ]; then
   echo
   echo "::group::${chroot} builder-live.log"
-    cat "$log"
-    echo "::endgroup::"
+  if [ -f "${chroot_dir}builder-live.log.gz" ]; then
+    zcat "${chroot_dir}builder-live.log.gz"
+  elif [ -f "${chroot_dir}builder-live.log" ]; then
+    cat "${chroot_dir}builder-live.log"
+  else
+    echo "(no builder-live.log found for ${chroot})"
   fi
+  echo "::endgroup::"
 done
 
 exit "$STATUS"