Bring CLAUDE.md back in line with what CI does

[hacker-cb]

Six places in CLAUDE.md drifted while the CI refactor landed — three of them
contradicting another rule in the same file, which is the worst kind: an agent
reading top-down hits the stale one first.

The contradictions

needs: <base>-manifest was still stated as the rule for a derived image,
forty lines above the paragraph describing esp-matter-build depending on
esp-idf-build. The dependency changed because what that job needs is the base
image, and images are pushed by digest on every run while tags stay master-only.

The publishing gates were described as "login and push, master only". That
stopped being true when esp-idf-build began pushing on every run so ESP-Matter
could be validated on pull requests. Rewritten to separate three questions that
were being conflated: who runs at all, which tags get written, and whether the
image is uploaded — the last one differing per image, with the reason.

The platform-to-pool mapping was described as copied into each build job. It
moved into versions.json two PRs ago and is generated from there.

The stale facts

The esp-matter timeout rationale said the figure stays generous "until the native
arm64 leg has been measured". It has been: 7–11 minutes on both architectures,
against a ceiling of 180 set when the QEMU leg took 337. Recorded, along with why
it is written down rather than changed — an unused ceiling costs nothing, while a
wrong one fails invisibly.

Local workflow said building esp-matter cannot exercise a locally built esp-idf. It
can, via BASE_IMAGE — and on a version-bump branch it must, because the
Dockerfile default names a tag that only exists once the branch lands.

Plus one placeholder spelling throughout (sha-<short-commit>), and a note that
ARG PIO_ENVS reads like a pre-warm that happens and is in fact dead code behind a
commented-out block.

Reviewed by

codex-review (xhigh), which found two factual slips in this patch itself:

• timeout_minutes in versions.json governs build jobs only — the manifest
  matrix carries no such field and both workflows hardcode timeout-minutes: 10,
  so someone following the sentence as written would edit the data file and see
  nothing change. Verified: the generated manifest matrix has no timeout_minutes.
• platformio does ship a compiler — build-essential is installed and the
  verification layer runs gcc --version, so native unit tests work out of the
  box. Verified in the built image: gcc 12.2.0, g++, make. What is deferred to the
  user's first build is the ESP32 cross-toolchains.

Documentation only — !images/**/*.md keeps this out of the image workflows, so
nothing rebuilds.

[Copilot]

Pull request overview

Updates CLAUDE.md to match the current CI/workflow behavior for the Docker image publishing pipeline, removing several now-stale or internally contradictory statements so contributors don’t follow incorrect operational guidance.

Changes:

• Corrects derived-image workflow chaining guidance to depend on <base>-build (digest-producing job) rather than <base>-manifest.
• Clarifies publishing semantics by separating (a) who runs, (b) which tags are written (master-only), and (c) whether images are pushed (varies by image; esp-idf pushes by digest on every run).
• Refreshes operational details that had drifted (runner mapping source, timeout behavior, PlatformIO compiler/toolchain notes, local esp-matter build with BASE_IMAGE, and sha-<short-commit> placeholder wording).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.