diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 0000000..7fa7712
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1,57 @@
+# AGENT.md
+
+This file provides guidance to AI agents like Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Blazestar.net is a personal blog/homepage built with **Astro v5** (static site generator). It uses React for interactive components, CSS v4 for styling, and MDX for markdown with JSX support.
+
+## Commands
+
+```bash
+npm run dev       # Start dev server at localhost:4321
+npm run build     # Build production site to ./dist/
+npm run preview   # Preview production build locally
+```
+
+Linting and formatting tools (ESLint, Prettier) are available via the Nix dev environment (`nix develop` or direnv). No npm scripts are configured for them.
+
+## Architecture
+
+### Content Collections
+
+Defined in `src/content.config.ts`. Two collections:
+
+- **blog** — Markdown/MDX posts in `src/content/blog/`. Drafts live in `src/content/blog/drafts/` and are excluded from production builds.
+- **page** — Static pages in `src/content/page/` (about, values).
+
+Blog post frontmatter: `title` (required), `description` (required), `pubDate`, `updatedDate`, `heroImage`, `tags[]`.
+
+### Routing
+
+- `/` — Home (`src/pages/index.astro`)
+- `/blog/` — Post listing (`src/pages/blog/index.astro`)
+- `/blog/[slug]/` — Individual posts (`src/pages/blog/[...slug].astro`)
+- `/blog/tag/[tag]/` — Tag listing pages (`src/pages/blog/tag/[...tag].astro`)
+- `/blog/tag/[tag].rss.xml` — Per-tag RSS feeds
+- `/rss.xml` — Main RSS feed
+
+### Key Utilities
+
+- `src/lib/blog.ts` — Functions for fetching/sorting posts and extracting tag data
+- `src/consts.ts` — Global constants (`SITE_TITLE`, `SITE_DESCRIPTION`)
+
+### Layouts & Components
+
+- `src/layouts/RootLayout.astro` — Root HTML shell; all pages use this
+- `src/layouts/BlogPost.astro` — Layout for individual blog posts (h-entry microformat)
+- `src/layouts/BlogList.astro` — Layout for post listing pages
+- `src/components/` — Shared components (Header, Footer, Sidebar, etc.)
+
+### Styling
+
+Tailwind CSS v4 via Vite plugin (`@tailwindcss/vite`). Global CSS and custom properties in `src/styles/global.css`. Custom fonts in `public/fonts/`.
+
+### IndieWeb
+
+The site supports IndieWeb standards: h-card and h-entry microformats in layouts, IndieAuth endpoint pointing to indieauth.com.