diff --git a/CLAUDE.md b/CLAUDE.md
index 57ae030..4c1a917 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -89,9 +89,10 @@ release.yml  (on: push to master; also workflow_dispatch w/ `force`)
   if TAG already exists (and not forced): NO-OP, nothing is published
   else: creates annotated tag v<version>, generates notes from
         git log <prev-tag>..HEAD, publishes a GitHub Release
-        │  (GitHub Release "created" event)
+        │  ⚠️ the "created" event does NOT auto-run maven-publish (see gotchas)
         ▼
-maven-publish.yml  (on: release created; also workflow_dispatch w/ `tag_version`)
+maven-publish.yml  (declares `on: release created`, but in practice must be
+                    run MANUALLY via workflow_dispatch w/ `tag_version`)
   build  : mvn -B package
   test   : mvn -B verify   (integration tests, creds from Doppler)
   deploy : mvn deploy -Dmaven.test.skip.exec -s settings.xml
@@ -103,10 +104,13 @@ maven-publish.yml  (on: release created; also workflow_dispatch w/ `tag_version`
 
 1. Bump `<version>` in `pom.xml` (semver: `feat:` commits since the last tag → minor, `fix:`/`chore:` only → patch).
 2. Open a PR with the bump. PR title must be a conventional commit (enforced by `pr-title.yml`), e.g. `chore(release): bump version to 1.10.0`.
-3. Merge to `master`. The merge triggers `release.yml`, which tags `v<version>`, cuts the GitHub Release, and that in turn triggers `maven-publish.yml` to build → test → deploy.
-4. Verify: `gh run list --workflow=release.yml`, `gh release view v<version>`, and that the deploy job in `maven-publish.yml` succeeded.
+3. Merge to `master`. The merge triggers `release.yml`, which tags `v<version>` and cuts the GitHub Release.
+4. **Publish manually** (this does NOT happen on its own — see gotcha): `gh workflow run maven-publish.yml -f tag_version=v<version>`.
+5. Verify: `gh release view v<version>`, the `maven-publish.yml` deploy job is green, and the version shows in `gh api /orgs/pluggyai/packages/maven/ai.pluggy.pluggy-java/versions`.
 
 **Gotchas:**
+- **The GitHub Release does NOT auto-publish to Packages — you must dispatch `maven-publish.yml` yourself.** `release.yml` creates the Release using the default `GITHUB_TOKEN`, and GitHub deliberately does not fire workflow triggers (including `maven-publish`'s `release: created`) for events raised by `GITHUB_TOKEN`, to prevent recursive runs. So the deploy step never triggers automatically — every real publish has been a manual `workflow_dispatch`. After tagging, run `gh workflow run maven-publish.yml -f tag_version=v<version>`. A tagged release with nothing in Packages is this bug, not a build failure. *Permanent fix (not yet applied): create the Release with a PAT instead of `GITHUB_TOKEN`, or add a step at the end of `release.yml` that dispatches `maven-publish.yml`.*
+- **CI uses a GitHub Actions allowlist (`allowed_actions: selected`).** Only GitHub-owned actions plus a short pinned list (currently `dopplerhq/cli-action@v1`, `softprops/action-gh-release@v1`) are permitted. Any non-allowlisted action — or a *bumped version* of an allowlisted one (e.g. `dopplerhq/cli-action@v4`) — makes the whole workflow fail at **`startup_failure` with no jobs**. This is why `dependabot.yml` ignores `semver-major`; if a workflow suddenly won't start, check `gh api repos/pluggyai/pluggy-java/actions/permissions/selected-actions` and either pin back or add the action (repo admin: Settings → Actions → Allowed actions).
 - **Forgetting the bump is a silent no-op.** If the pom version already has a tag, the push to master publishes nothing. Don't bump the version unless you intend to cut a release, and *do* bump it when you do.
 - The `maven-release-plugin` is configured in `pom.xml` (`tagNameFormat = v@{project.version}`) but is **not** used by CI — tagging is done by `release.yml`'s shell, not `mvn release:*`.
 - Manual escape hatches: run `release.yml` via `workflow_dispatch` with `force=true` to re-release an existing tag; run `maven-publish.yml` via `workflow_dispatch` with a `tag_version` input to re-deploy an existing tag without re-tagging.