docs: explain auto-syncing in site guide + README collapsible#457
Merged
Conversation
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>
fuentesgomezabnerelfdk-blip
approved these changes
May 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Originated from #438 ("Will newly created files be missing from query results if sync is not manually run?"). The answer to that question is no, the watcher handles it — but 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.
Changes
site/src/content/docs/guides/indexing.md— "Stay fresh automatically"Expanded the existing 2-sentence section into the full three-layer explanation:
CODEGRAPH_WATCH_DEBOUNCE_MS, clamp[100ms, 60s]).Plus: how to verify state via
codegraph_status's### Pending sync:section, when manualcodegraph syncDOES make sense (watcher disabled / CI scripting), and a link out to v0.9.5 release notes.README.md— collapsible "How auto-syncing works"Added a
<details><summary>block 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 flow diagram + the verify command + a deep link to the full guide.<details>is collapsed by default on GitHub so the README's visible scroll length doesn't grow. Anyone curious about auto-sync clicks once and sees the full explanation; anyone who isn't worried about it doesn't even notice it's there.Why both
940/942 tests still pass (2 pre-existing skips); no code changes.
🤖 Generated with Claude Code