7479c5e82b
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>
Starlight Starter Kit: Basics
npm create astro@latest -- --template starlight
🧑🚀 Seasoned astronaut? Delete this file. Have fun!
🚀 Project Structure
Inside of your Astro + Starlight project, you'll see the following folders and files:
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ └── docs/
│ └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.
Images can be added to src/assets/ and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the public/ directory.
🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
|---|---|
npm install |
Installs dependencies |
npm run dev |
Starts local dev server at localhost:4321 |
npm run build |
Build your production site to ./dist/ |
npm run preview |
Preview your build locally, before deploying |
npm run astro ... |
Run CLI commands like astro add, astro check |
npm run astro -- --help |
Get help using the Astro CLI |
👀 Want to learn more?
Check out Starlight’s docs, read the Astro documentation, or jump into the Astro Discord server.