Originated from issue #438 ("Will newly created files be missing from
query results if sync is not manually run?"). Real users are second-
guessing whether their agent's freshly-created files are getting
indexed. They shouldn't have to test for themselves to find out.
## site/src/content/docs/guides/indexing.md
Expanded the existing 2-sentence "Stay fresh automatically" section
into the full three-layer explanation:
1. File watcher with debounced auto-sync (default 2000ms, tunable
via CODEGRAPH_WATCH_DEBOUNCE_MS, clamp [100ms, 60s]).
2. Per-file staleness banner (#403) — covers the debounce window.
Quoted the actual banner format + the verified Claude Code
follow-up Read behaviour.
3. Connect-time catch-up (#414) — covers gaps when the MCP server
wasn't running.
Plus: how to verify state via codegraph_status (### Pending sync:),
when manual codegraph sync DOES make sense (watcher disabled / CI
scripting), and a link out to the v0.9.5 release notes.
## README.md
Added a <details><summary> collapsible right under the Key Features
table — primed by the existing 'Always Fresh' row in that table.
Condensed to ~10 lines covering the same three layers + a code-block
flow diagram + the verify command, with a deep link to the full guide.
GitHub renders <details> blocks natively, so the section is collapsed
by default and doesn't make the README scroll-length grow visibly.
Heading kept as 'Stay fresh automatically' (single-word slug) so the
README's deep-link anchor is predictable; the longer tagline lives on
its own line below.
940/942 tests still pass; no code changes.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7479c5e82b