# AGENTS.md — Astro

- Default to zero client-side JavaScript: Astro renders components to HTML & CSS and strips JS.
- A `.astro` file = component script in a `---` fence (runs at build/server time, stripped from output) + an HTML template with `{ }` expressions.
- Read props from `Astro.props`; type them with `interface Props`. Use `<slot />` and named slots for composition.
- Add interactivity only as islands: framework components marked with a `client:*` directive ship JS, nothing else does.
- Choose the lightest directive: `client:load` (immediate), `client:idle` (browser idle), `client:visible` (in viewport), `client:media={QUERY}`, `client:only="framework"` (client-only render).
- No directive means the framework component renders to static HTML with no JS — keep it that way unless interactivity is required.
- Plain `.astro` components cannot take `client:*`; only framework components hydrate. Use `server:defer` for dynamic server islands.
- Only Astro components can combine multiple UI frameworks; framework components cannot import `.astro` files.
- Props to a hydrated island must be serialisable (no functions). Pass children via `children` (React/Preact/Solid) or `<slot />` (Svelte/Vue).
- Store structured content in content collections, outside `src/pages/`.
- Define collections in `src/content.config.ts` with `defineCollection()`, a loader (`glob()`/`file()`), and a Zod `schema` for type-safe frontmatter.
- Query collections with `getCollection()` / `getEntry()` and render entries with `await render(entry)` (the `{ Content }` it returns), all from `astro:content`.
- Don't add `client:*` to non-interactive UI, pass functions as island props, or skip the collection schema.