docs(agents): add AGENTS.md documentation files for site agents

AGENTS.md

@@ -0,0 +1,47 @@
+<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
+
+# prad.nu
+
+## Purpose
+Personal CV / portfolio site for Prad Nukala (https://prad.nu). A static [Astro](https://astro.build) v6 site (forked from the Astro Cactus theme) organised into four content sections — **Projects**, **Experience**, **Writing**, **Speaking** — where Experience entries double as a cross-linking taxonomy. See `README.md` for the human-facing overview.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `package.json` | Dependencies and scripts (pnpm). |
+| `astro.config.ts` | Astro integrations (MDX, sitemap, icon, robots, webmanifest, expressive-code), markdown remark/rehype pipeline, Satori OG fonts. |
+| `tailwind.config.ts` | Tailwind v4 config (most styling is in `src/styles/global.css`). |
+| `tsconfig.json` | TypeScript config; defines the `@/*` → `src/*` path alias. |
+| `biome.json` | Biome linter/formatter config (`pnpm check` / `pnpm lint`). |
+| `mise.toml` / `pnpm-workspace.yaml` | Toolchain + workspace config. |
+| `README.md` | Project purpose, content model, frontmatter reference. |
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `src/` | All application source (see `src/AGENTS.md`). |
+| `public/` | Static assets served as-is (see `public/AGENTS.md`). |
+
+## For AI Agents
+
+### Working In This Directory
+- Package manager is **pnpm**. Output is **static** (`output: 'static'`, `./dist`) — no SSR adapter.
+- Import from source via the `@/` alias (e.g. `@/site.config`), not long relative paths.
+- Most site-wide config (title, url, `socialLinks`, `streamOrigin`, `menuLinks`) lives in `src/site.config.ts`.
+
+### Testing Requirements
+- `pnpm build` is the primary correctness gate — it runs `astro check`-level content validation and fails on bad frontmatter, broken collection refs, or type errors.
+- `pnpm check` runs `astro check` + Biome. `pnpm dev` serves locally for visual checks.
+
+### Common Patterns
+- Content lives in Content Collections; schema is defined once in `src/content.config.ts`.
+- `is:inline` is required on `<script type="application/ld+json">` and similar non-bundled scripts.
+
+## Dependencies
+
+### External
+- `astro` v6, `tailwindcss` v4 — framework + styling.
+- `@astrojs/mdx`, `@astrojs/rss`, `@astrojs/sitemap`, `astro-icon`, `astro-webmanifest`, `astro-robots-txt`, `astro-expressive-code`.
+- `satori` + `sharp` — OG image generation. `pagefind` — static search. `@mux`? no — speaking uses Cloudflare Stream via an iframe (no player dep).
+
+<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->

public/AGENTS.md

@@ -0,0 +1,22 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
+
+# public
+
+## Purpose
+Static assets copied verbatim to the site root at build time (served at `/`).
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `avatar.png` | Personal avatar used as the header logo (`src/components/layout/Header.astro`, referenced as `/avatar.png`) and in the homepage `Person` JSON-LD. |
+| `icon.svg` | Source icon; `astro-webmanifest` generates favicons / apple-touch / manifest icons from it at build (referenced in `BaseHead.astro`). |
+| `social-card.png` | Default Open Graph image when a page/post supplies no `ogImage`. |
+
+## For AI Agents
+
+### Working In This Directory
+- Reference these with absolute root paths (`/avatar.png`), not the `@/` alias — they are not processed by Astro's asset pipeline.
+- Replacing `icon.svg` changes all generated favicons/manifest icons; keep it roughly square (build warns otherwise).
+
+<!-- MANUAL: -->

src/AGENTS.md

@@ -0,0 +1,50 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
+
+# src
+
+## Purpose
+All application source: configuration, content collections, pages/routes, layouts, components, data helpers, styles, and build plugins.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `site.config.ts` | Site metadata (`siteConfig`), `socialLinks`, `streamOrigin` (Cloudflare Stream origin), `menuLinks`, and Expressive Code options. Primary place to edit site-wide settings. |
+| `content.config.ts` | Content Collection definitions + Zod schemas for `writing`, `projects`, `experience`, `speaking`. Experience refs are validated via `reference("experience")`. |
+| `types.ts` | Shared TS types (`SiteConfig`, `SiteMeta`, webmention types, `AdmonitionType`). |
+| `env.d.ts` | Ambient type declarations. |
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `assets/` | Build-time assets, currently OG fonts (see `assets/AGENTS.md`). |
+| `components/` | Reusable `.astro` components (see `components/AGENTS.md`). |
+| `content/` | Markdown content for the four collections (see `content/AGENTS.md`). |
+| `data/` | Collection query helpers (see `data/AGENTS.md`). |
+| `layouts/` | Page shells (see `layouts/AGENTS.md`). |
+| `pages/` | File-based routes + endpoints. **No `AGENTS.md` here** — any `.md` under `src/pages` becomes a public route, so docs for this dir live in this file (see "Routing & OG images" below). |
+| `plugins/` | Custom remark plugins (see `plugins/AGENTS.md`). |
+| `styles/` | Global CSS + block/component styles (see `styles/AGENTS.md`). |
+| `utils/` | Pure helper functions (see `utils/AGENTS.md`). |
+
+## For AI Agents
+
+### Working In This Directory
+- Collection **keys match their content dir and route**: `writing`→`/writing`, `projects`→`/projects`, `experience`→`/experience`, `speaking`→`/speaking`.
+- When changing a collection schema in `content.config.ts`, run `pnpm build` to regenerate `astro:content` types and catch frontmatter mismatches.
+
+### Routing & OG images (`src/pages`)
+- Any `.md`/`.mdx`/`.astro` under `src/pages` becomes a route — do **not** put `AGENTS.md` or other docs there (they'd ship as public pages). Document `pages/` here instead.
+- Each section has `[...page].astro` (paginated list) + `[...slug].astro` (detail); plus `rss.xml.ts` feeds and a dynamic OG-image endpoint.
+- `og-image/[...slug].png.ts` generates per-entry social images for **all** collections (namespaced `/og-image/<type>/<id>.png`) via Satori + Sharp, cached by `_cacheUtil.ts` (bump `CACHE_VERSION` when changing `_ogMarkup.ts`). Files prefixed `_` are private modules, not routes.
+- The `/experience/[...slug]` page is the taxonomy hub (`getContentForExperience`), listing related projects/writing/talks.
+
+### Common Patterns
+- The `experiences` frontmatter array (on projects/writing/speaking) holds `reference("experience")` entries, resolved with `getEntries`.
+
+## Dependencies
+
+### Internal
+- Nearly everything imports `@/site.config` and `@/content.config`-derived collection types.
+
+<!-- MANUAL: -->

src/pages/tags/index.astro

@@ -0,0 +1,31 @@
+---
+import { getTagIndex, getTaggedCollections } from "@/data/tags";
+import PageLayout from "@/layouts/Base.astro";
+
+const cols = await getTaggedCollections();
+const tags = [...getTagIndex(cols).entries()]
+	.map(([slug, { label, count }]) => ({ slug, label, count }))
+	.sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+
+const meta = {
+	description: "Browse projects, experience, writing, and talks by skill and topic.",
+	title: "Tags",
+};
+---
+
+<PageLayout meta={meta}>
+	<h1 class="title mb-6">Tags</h1>
+	<p class="text-muted mb-8">Skills and topics spanning my projects, experience, writing, and talks.</p>
+	<ul class="flex flex-wrap gap-x-4 gap-y-2">
+		{
+			tags.map(({ slug, label, count }) => (
+				<li>
+					<a class="cactus-link before:content-['#']" href={`/tags/${slug}/`}>
+						{label}
+					</a>
+					<span class="text-muted text-sm"> {count}</span>
+				</li>
+			))
+		}
+	</ul>
+</PageLayout>

src/plugins/AGENTS.md

@@ -0,0 +1,27 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
+
+# plugins
+
+## Purpose
+Custom remark plugins wired into Astro's markdown pipeline (`astro.config.ts` → `markdown.remarkPlugins`).
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `remark-admonitions.ts` | Turns `:::tip`/`:::note`/`:::important`/`:::caution`/`:::warning` directives into styled admonition blocks. Types defined in `@/types` (`AdmonitionType`); styled by `src/styles/components/admonition.css`. |
+| `remark-github-card.ts` | Renders a GitHub repo card from a directive. Styled by `src/styles/components/github-card.css`. |
+| `remark-reading-time.ts` | Computes reading time (via `reading-time`) and injects it into frontmatter; surfaced as `remarkPluginFrontmatter.readingTime` in `BlogPost.astro`. |
+
+## For AI Agents
+
+### Working In This Directory
+- These use the unified/mdast ecosystem (`unist-util-visit`, `mdast-util-directive`, `hastscript`). Directive syntax requires `remark-directive` (already configured).
+- Adding/removing a plugin requires editing `astro.config.ts`. Add matching CSS under `src/styles/components/` for any new block type.
+
+## Dependencies
+
+### External
+- `unified`, `unist-util-visit`, `mdast-util-directive`, `mdast-util-to-string`, `hastscript`, `reading-time`.
+
+<!-- MANUAL: -->

src/utils/AGENTS.md

@@ -0,0 +1,29 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-30 | Updated: 2026-06-30 -->
+
+# utils
+
+## Purpose
+Pure, framework-agnostic helper functions used across components, pages, and data helpers.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `date.ts` | `getFormattedDate` (locale-aware, per `siteConfig.date`) and `collectionDateSort` — sorts `writing`/`projects`/`speaking`/etc. by `publishDate` descending. |
+| `generateToc.ts` | Builds a nested table-of-contents tree from Astro markdown headings (used by `TOC.astro`). |
+| `remark.ts` | Shared remark/markdown helpers. |
+| `domElement.ts` | Small DOM helpers for client-side scripts. |
+| `webmentions.ts` | Fetches and caches webmentions from webmention.io for the webmention components. |
+
+## For AI Agents
+
+### Working In This Directory
+- `collectionDateSort` is typed for entries with a `publishDate`; experience entries (which use `startDate`/`endDate`) are sorted in `@/data/experience.ts` instead.
+- Keep these pure and side-effect-free where possible; `webmentions.ts` is the exception (network + cache).
+
+## Dependencies
+
+### Internal
+- `@/site.config` (date locale), `@/types`.
+
+<!-- MANUAL: -->