diff --git a/.cursor/rules/pnpm-is-the-package-manager.mdc b/.cursor/rules/pnpm-is-the-package-manager.mdc
new file mode 100644
index 0000000..0552d2b
--- /dev/null
+++ b/.cursor/rules/pnpm-is-the-package-manager.mdc
@@ -0,0 +1,4 @@
+---
+alwaysApply: true
+---
+The required package manager for this repository is `pnpm`. Do not use any other package managers like npm, bun, etc.
diff --git a/dev/CLAUDE.md b/dev/CLAUDE.md
new file mode 100644
index 0000000..30196fb
--- /dev/null
+++ b/dev/CLAUDE.md
@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Astro 5 blog with Cloudflare Pages deployment. Uses PNPM as package manager.
+
+## Commands
+
+```bash
+pnpm dev        # Start dev server at localhost:4321
+pnpm build      # Build production site to ./dist/
+pnpm preview    # Build and preview locally via Wrangler
+pnpm deploy     # Build and deploy to Cloudflare Pages
+pnpm cf-typegen # Generate Wrangler types for Cloudflare bindings
+```
+
+## Architecture
+
+### Content System
+- Blog posts in `src/content/blog/` as Markdown/MDX files
+- Content schema defined in `src/content.config.ts` with Zod validation
+- Required frontmatter: `title`, `description`, `pubDate`
+- Optional frontmatter: `updatedDate`, `heroImage`
+
+### Routing
+- `src/pages/` - File-based routing
+- `src/pages/blog/[...slug].astro` - Dynamic blog post routes
+- `src/pages/rss.xml.js` - RSS feed endpoint
+
+### Components
+- `src/components/BaseHead.astro` - SEO metadata, og:image, Twitter cards
+- `src/layouts/BlogPost.astro` - Blog post layout template
+- `src/consts.ts` - Site title and description constants
+
+### Styling
+- Tailwind CSS via Vite plugin
+- Design tokens in `src/styles/global.css` as CSS custom properties
+- Current accent color: `#2337ff` (blue)
+- Max content width: 720px
+
+### Cloudflare Integration
+- Adapter: `@astrojs/cloudflare` with platform proxy enabled
+- Wrangler config: `wrangler.jsonc`
+- Environment types: `src/env.d.ts`
+- Node.js compatibility enabled via `nodejs_compat` flag
+
+## Design Specification
+
+`design.json` contains V7 Industrial Dark Mode system specification (not yet implemented):
+- Dark mode native with `#0B0D11` primary background
+- Orange/yellow accent `#FFB84C` for CTAs
+- Brutalist/industrial aesthetic with visible grid structure
+- Heavy typography emphasis
+
+## Key Configuration
+
+- **Site URL**: Currently `https://example.com` in `astro.config.mjs` - update for production
+- **Project name**: `nicholai-work-2026` in `wrangler.jsonc`
+- **TypeScript**: Strict mode with Astro and Cloudflare Worker types