Astro static site

# AGENTS.md: Astro static site

Static output (`output: "static"`, the default). The built site is plain HTML/CSS in `dist/`.

## Principles
- **Ship no JavaScript unless a feature needs it.** `.astro` components render to HTML at build time.
  A UI framework component (React, Svelte, Vue) only runs in the browser with a `client:*` directive — use
  `client:visible` or `client:idle` over `client:load`, and only for genuinely interactive parts.
- Small inline `<script>` tags in `.astro` files are fine for simple interactivity (menus, copy buttons). Astro bundles them.
- Do not add a UI framework integration just for one widget.

## Layout
```
src/pages/          routes (file-based). [slug].astro + getStaticPaths for dynamic pages
src/layouts/        page shells (Base.astro holds <head>, meta tags, header, footer)
src/components/     .astro components
src/content/        markdown/MDX/JSON content
src/content.config.ts   collection definitions with zod schemas
src/styles/         global CSS (tokens as custom properties)
public/             copied as-is: favicon, robots.txt, _headers, _redirects
```

## Content collections
- Anything list-like (posts, projects, docs) is a collection defined in `src/content.config.ts` with a `glob()` loader and a `schema`.
- Read with `getCollection("blog")` / `getEntry(...)`; render markdown with `render(entry)`.
- Add new frontmatter fields to the schema first. The build should fail on bad content, not render `undefined`.

## Pages and SEO
- Every page sets a unique `<title>` and `<meta name="description">` via the layout props.
- Set `site` in `astro.config.mjs` so canonical URLs, sitemaps and RSS work.
- Use `@astrojs/sitemap` for a sitemap; add `robots.txt` in `public/`.
- Internal links are root-relative (`/about/`). Respect the configured `trailingSlash` setting.

## Images and assets
- Local images live in `src/assets/` and go through `<Image />` / `<Picture />` from `astro:assets` (sizes, formats, lazy loading).
- Always set meaningful `alt` text (empty `alt=""` for decorative images).
- Self-host fonts or use system fonts; preload only the one font file used above the fold.

## HTML and CSS
- Semantic HTML: one `<h1>`, landmarks (`header`, `main`, `nav`, `footer`), real `<button>`s and `<a>`s.
- Component styles in `<style>` (scoped by default). Global tokens (colours, spacing, fonts) as CSS custom properties.
- Check colour contrast and visible focus states. Respect `prefers-reduced-motion`.

## Before you say "done"
`npm run build` passes with no warnings you introduced, and `npm run preview` shows the change. Mention any new page or route.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `cloudflare-pages-deploy`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Astro static site" v1.0.0 — https://loadout.jnw-it.com/loadouts/astro-static-site/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `cloudflare-pages-deploy`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Astro static site" v1.0.0 — https://loadout.jnw-it.com/loadouts/astro-static-site/ -->

---
description: Astro component conventions
globs: "**/*.astro"
alwaysApply: false
---

- Frontmatter (between `---`) runs at build time only. Never put secrets in client `<script>` tags; frontmatter is fine.
- Type props: `interface Props { title: string; tags?: string[] }` then `const { title, tags = [] } = Astro.props;`.
- Use `class:list={[...]}` for conditional classes and `set:html` only with trusted, sanitised HTML.
- Framework components need a `client:*` directive to be interactive; omit it when the component is static.
- Prefer `<Image />` from `astro:assets` over `<img>` for local images.
- Keep components small and composable; use `<slot />` (and named slots) instead of passing HTML strings as props.
- Scoped `<style>` by default; `:global()` only when styling slotted or third-party markup.

---
name: cloudflare-pages-deploy
description: Deploy a static site (Astro, Vite or plain HTML) to Cloudflare Pages, with headers, redirects and a custom domain. Use when the user asks to deploy, host or publish a static site on Cloudflare.
---

# Deploy a static site to Cloudflare Pages

## 1. Confirm the build
- Build command and output folder: Astro `npm run build` → `dist`; Vite `npm run build` → `dist`; plain HTML: no build, output is the folder.
- Run the build locally and check the output folder has `index.html`.
- Set the Node version Cloudflare should use: add a `.nvmrc` (e.g. `22`) or the `NODE_VERSION` environment variable in the project settings.

## 2. Add Pages config files to `public/` (copied into the output)
`public/_headers`:
```
/*
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  X-Frame-Options: DENY

/_astro/*
  Cache-Control: public, max-age=31536000, immutable
```
`public/_redirects` (only if needed):
```
/old-page /new-page/ 301
```

## 3. Choose a deploy route (ask the human which they prefer)
**A. Git integration (recommended for ongoing sites):** the human connects the repo in the Cloudflare dashboard
(Workers & Pages → Create → Pages → Connect to Git), sets the build command and output directory from step 1.
Every push to the production branch deploys; other branches get preview URLs.

**B. Direct upload with Wrangler:**
```sh
npx wrangler login                     # human does this once, in a browser
npx wrangler pages project create <project-name> --production-branch main
npx wrangler pages deploy dist --project-name <project-name>
```
Never paste or store a Cloudflare API token in the repo. In CI, use the `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` secrets.

## 4. Custom domain
In the Pages project → Custom domains → add `sub.example.com`. If the zone is on the same Cloudflare account, the DNS record is
created automatically; otherwise the human adds a CNAME to `<project>.pages.dev`. Certificates take a few minutes.

## 5. Verify
- Open the `*.pages.dev` URL and the custom domain. Check a deep link, the 404 page, and response headers
  (`curl -sI https://sub.example.com/ | grep -i x-content-type`).

## 6. Report
Project name, production URL, preview URL pattern, and anything the human still needs to click.