docs(ci): document cache save/restore design for CI runners

[zackees]

Closes #92.

Adds docs/CI_CACHING.md (559 lines) covering how to persist fbuild's local disk cache across CI runs so a cold runner is effectively warm on the second build. Unblocks FastLED's CI from realising fbuild's cache advantages.

Sections

• What to cache — paths, exclusions (daemon.port, fbuild_daemon.pid, daemon.log*, locks, leases), Windows vs Unix, size expectations
• Cache key strategy — primary key inputs in priority order + restore-key fallback chain
• Hermeticity — byte-identical-output caveats, runner-embedded paths
• Invalidation — disk_cache::budget behavior, reconcile_on_open cost, pinning
• Daemon interaction — --foreground --oneshot / --no-daemon options for CI
• Worked examples — drop-in actions/cache@v4 YAML snippet for a FastLED-style matrix
• Related tooling audit — fbuild cache export/import, lease locking under concurrent shards

Notes

• 10 TODO: verify items flagged in-doc where behavior wasn't obvious from the code
• 6 candidate follow-up issues listed in the doc's "Open questions" section (not filed — will triage)
• Pure docs PR. No source code touched.
• Adds two rows to docs/INDEX.md for discoverability

Verify

• uv run cargo check --workspace --all-targets
• uv run cargo clippy --workspace --all-targets -- -D warnings
• uv run cargo fmt --all

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@zackees has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 9 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 23 minutes and 9 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: 2284a478-e79a-44c6-92d3-2b4613ee2084

📥 Commits

Reviewing files that changed from the base of the PR and between d37995b and aba288a.

📒 Files selected for processing (2)

• docs/CI_CACHING.md
• docs/INDEX.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.}

[zackees]

Superseded by #100 (docs/CI_CACHING.md merged independently, 181 lines vs this PR's 559 — if more detail is wanted, happy to resurface content from this branch as a follow-up).