docs(ci): add CI_CACHING.md — save/restore design for CI runners (closes #92)

[zackees]

Summary

Adds a decentralized doc that answers how do I persist fbuild's cache across CI runs? — the missing design the #92 issue called out.

Highlights:

• Drop-in GHA snippet at the top that FastLED's matrix (or any consumer) can paste unchanged.
• What to cache / what not to cache table, including the warning that ~/.fbuild/*/daemon/ must be excluded (the daemon port/PID files cause broken-daemon-discovery on the next run if restored).
• Cache-key strategy with OS/arch + fbuild version + graph-input hash + manual-bump sentinel, plus a restore-key fallback chain for partial hits.
• Hermeticity caveats around absolute paths in response files and DWARF — documented honestly, with mitigations.
• Daemon interaction in CI: one-shot-runner flow, why --no-daemon is not needed, and the matrix-sharding concurrency note.
• Smoke test YAML that asserts the second build was warm, so cache breakage surfaces as a failed CI step instead of silent slowness.
• Timings sourced directly from perf(build): investigate warm-pass compilation stall — 30s where cache says <1s #91's profiling data, not guesses.

Wired into docs/INDEX.md (two FAQ rows — cache-how and cache-safe) and docs/README.md (contents list).

Test plan

• lychee-compatible internal links resolve (no new broken links).
• No code changes — markdown-only PR. No clippy/test impact.
• FAQ rows in docs/INDEX.md follow the one-question-per-row convention.

Related

• Closes docs(ci): document cache save/restore design for CI runners (GH Actions, etc.) #92.
• Builds on the warm-path measurements from perf(build): investigate warm-pass compilation stall — 30s where cache says <1s #91 (now fully closed by perf(cli): strip Windows handle inheritance + fast daemon health probe (partial #91) #97 + perf(cli): drop redundant daemon banner + shorten self-eviction (closes #91) #99).

[coderabbitai]

Warning

Rate limit exceeded

@zackees has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 56 minutes and 27 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 56 minutes and 27 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7c2c536d-b46a-421c-b94f-16c98a6e4e43

📥 Commits

Reviewing files that changed from the base of the PR and between bd4b3a1 and 1436018.

📒 Files selected for processing (3)

• docs/CI_CACHING.md
• docs/INDEX.md
• docs/README.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/92-ci-caching

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}