diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md
new file mode 100644
index 00000000..552f9296
--- /dev/null
+++ b/.github/workflows/CLAUDE.md
@@ -0,0 +1,24 @@
+# GitHub Workflows
+
+Guidance for the 11 workflows in this directory, grouped into five buckets. The root `CLAUDE.md` has the canonical release pipeline details — this file is a map and a source of intent.
+
+## Buckets
+
+| Bucket | Files | Trigger | Purpose |
+|---|---|---|---|
+| CI | `ci.yml` | `push: main`, `pull_request` | Build/test/lint with `dorny/paths-filter` so each tool only runs when its paths (or `shared/`) change. |
+| Auto-release | `auto-release-{cfl,jtk}.yml` | `push: main` | Dual-gate tag creation: path gate (Go code only) + commit gate (`feat:`/`fix:`). Creates `{tool}-v{base}.{run}` tags that trigger the release workflow. |
+| Release | `release-{cfl,jtk}.yml` | Tag push (`cfl-v*`, `jtk-v*`) | GoReleaser matrix build (darwin/linux/windows × amd64/arm64), GitHub release, Homebrew cask push. Uses the tag-rename trick (see Pitfalls). |
+| Packaging publish | `chocolatey-publish-{cfl,jtk}.yml`, `winget-publish-{cfl,jtk}.yml` | `workflow_dispatch` only | Publish to Chocolatey / submit to winget-pkgs. Called manually after a release; depends on release artifacts existing at the expected tag. |
+| Packaging validation | `test-chocolatey.yml`, `test-winget.yml` | `push: main` with path filter on `tools/*/packaging/{chocolatey,winget}/**` | Post-merge dry-run validation (nuspec XML, PowerShell syntax, `choco pack`, winget manifest schema). These files aren't covered by `go test` or lint, so this is the only gate on them. |
+
+## History
+
+The packaging test workflows originally fired on `pull_request` (since Jan 2026, PR #11), spinning up `windows-latest` on every PR that touched packaging files. Issue #223 / PR #224 (Apr 2026) stripped that trigger — validation now runs only on `push: main`. PR #100 simplified the Chocolatey packaging itself (removed the custom uninstall script and `.ignore` file) per reviewer feedback from the Chocolatey community maintainer. The release workflow's tag-rename dance is a GoReleaser-Free constraint from the monorepo split — GoReleaser needs a semver tag (`v1.0.150`) but the project ships tool-prefixed tags (`cfl-v1.0.150`), so a temporary semver tag is created, consumed, then renamed.
+
+## Pitfalls
+
+- **Don't re-add `pull_request` to `test-chocolatey.yml` / `test-winget.yml`.** That undoes PR #224 and burns `windows-latest` runners on every packaging-touching PR.
+- **New packaging integrations must account for the tag rename.** GoReleaser runs *before* the tag is renamed from `v1.0.150` to `{tool}-v1.0.150`. Any download URLs generated by GoReleaser must use `url.template` to pin the final tool-prefixed tag, otherwise they reference the deleted temporary tag and 404. See `homebrew_casks` in `.goreleaser-{tool}.yml`.
+- **`jira-ticket-cli.rb` is auto-generated from `jtk.rb`** via `sed` in `release-jtk.yml` because GoReleaser Free doesn't support `alternative_names` for casks.
+- **Publish workflows are manual.** They don't fire automatically after a release — run them via `gh workflow run` once the release assets are in place.