kaboom

AGENTS.md

@@ -0,0 +1,53 @@
+# Portfolio Website — Linda Adel
+
+Oil painting artist portfolio. Astro 6 SSG with Keystatic CMS.
+
+## Stack
+
+- **Astro 6.4.8** — static output (`output: "static"`)
+- **Keystatic** — local git-backed CMS, loaded only in dev via `NODE_ENV=development`
+- **React** — only for Keystatic admin UI (`@astrojs/react`)
+- **TypeScript**, **plain CSS** (no Tailwind)
+- Pastel pink-purple palette (see `global.css` vars)
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `astro.config.mjs` | Astro config — react + conditional Keystatic integration |
+| `keystatic.config.ts` | CMS schema — paintings collection + about singleton |
+| `src/content.config.ts` | Custom loaders for both collections (reads `.yaml` directly) |
+| `src/site-config.ts` | All site strings: name, email, tagline, location, etc. |
+| `src/styles/global.css` | All styles — pastel palette, responsive breakpoints |
+
+## Content Layer — Pure YAML, No Frontmatter
+
+Both collections use **pure `.yaml` files** (no `---` frontmatter). Keystatic's `format: "yaml"` (the default) expects the entire file to be valid YAML. Astro uses custom loaders that parse YAML directly.
+
+**Paintings** (`src/content/paintings/*.yaml`): `title`, `image`, `year`, `medium`, `dimensions`, `featured`, `description` — all top-level YAML keys. Custom `yamlGlobLoader` discovers `.yaml` files, parses each, stores by filename stem as entry ID.
+
+**About** (`src/content/about/index.yaml`): `photo`, `bio` as top-level YAML keys. Custom `about-loader` reads the single file. Bio paragraphs split on `\n\n`.
+
+## Why Custom Loaders
+
+Keystatic's `format: "md"` passes entire files to js-yaml, which **throws on `---` frontmatter delimiters** ("expected a single document"). Using `format: "yaml"` avoids this, but Astro's built-in loaders don't support `.yaml` files. Custom loaders bridge the gap.
+
+Shared `yamlGlobLoader(base, pattern, ctx)` function in `src/content.config.ts` handles discovery, parsing, and hot reload for any YAML-based collection.
+
+## Dev Workflow
+
+```sh
+npm run dev       # NODE_ENV=development astro dev
+npm run build     # static build (Keystatic excluded)
+npm run preview   # preview static build
+```
+
+Keystatic admin at `/keystatic` — only available in dev mode.
+
+## Important
+
+- Restart dev server after changing `keystatic.config.ts` (Vite caches it). If things break, delete `node_modules/.vite/` and `.astro/`.
+- All content files are pure YAML — **no `---` frontmatter**. Don't add it.
+- Don't use Keystatic `fields.document()` — Astro's content layer doesn't support `.mdoc` extension.
+- All artist-facing strings in `src/site-config.ts` — edit there, not in templates.
+- Dev command: `NODE_ENV=development astro dev` — required for Keystatic integration to load.