docs: document cross-run CI cache strategy for fbuild consumers #152

Problem

After #146, #148, #149, and #150 land, fbuild's build cache will survive tar-extract and (where zccache allows) cross-runner restore. Consumers (FastLED master, downstream projects) need a canonical doc describing:

1. Which directories to cache:

   • ~/.fbuild/ — toolchain + daemon state
   • \${{ steps.fbuild-setup.outputs.zccache-store-path }} — per-TU objects
   • <project>/.build/pio/<board>/ — per-project build outputs + fingerprint

2. Cache key composition: runner.os, runner.arch, fbuild version hash, board. Do not include workspace path.

3. Expected cold vs warm numbers (from [META] Fastest possible FastLED examples CI rebuild — profile + benchmark #112 final iter).

4. Invalidation pattern: CACHE_BUST env var for manual busts; version-prefix (v1, v2) for schema changes.

5. Common pitfalls:

   • Do not cache <project>/.build/pio/<board>/.fbuild/build/<board>/release/firmware.* without the companion fingerprint — leads to stale artifacts.
   • zccache cache is only useful cross-runner after build: audit zccache per-TU cache keys for cross-runner stability #150 confirms key stability.

Sub-task of #147.

Deliverable

docs/CI_CACHE.md plus a link from docs/CLAUDE.md's "Other docs" section. Include a copy-pasteable actions/cache block for the common case (single-board, same runner image).

Out of scope

• Caching strategy for non-GitHub-Actions CI (GitLab, CircleCI). Those can follow the same directory list but the YAML isn't portable.

Related

• [META] fbuild build cache must survive CI tar-extract / cross-runner restore #147 — meta.
• [META] Fastest possible FastLED examples CI rebuild — profile + benchmark #112 — benchmark provides the numbers this doc cites.