docs: expand README + add CLAUDE.md for dev guidance

CLAUDE.md

@@ -0,0 +1,36 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Start Dev Server**: `npm run dev`
+- **Build Site**: `npm run build`
+- **Local Preview**: `npm run preview` (Uses Wrangler to simulate Cloudflare environment)
+- **Deploy**: `npm run deploy` (Builds and deploys to Cloudflare Pages)
+- **Type Check & Deploy Dry-run**: `npm run check`
+- **Generate Types**: `npm run types` (Generates Wrangler/Cloudflare types)
+
+## Architecture & Structure
+
+This is an **Astro 5** project configured for **Cloudflare Pages/Workers (SSR)**.
+
+### Core Structure
+- `src/content/`: Content collections for blog posts. Schema-driven via Astro's Content Layer.
+- `src/pages/`: File-based routing. Includes `.astro`, `.md`, and `.mdx` files.
+- `src/components/`: Reusable Astro components.
+- `src/layouts/`: Global page wrappers.
+- `wrangler.json`: Cloudflare Pages configuration.
+- `astro.config.mjs`: Astro configuration using the `@astrojs/cloudflare` adapter.
+
+### Technology Stack
+- **Framework**: Astro (SSR Mode)
+- **Deployment**: Cloudflare Pages
+- **Styling**: Standard CSS (within Astro components)
+- **Content**: MDX, Markdown
+- **Language**: TypeScript (Strict mode)
+
+### Key Patterns
+- **Content Collections**: Use `getCollection('blog')` to fetch content.
+- **SSR**: The project is configured for server-side rendering on Cloudflare Workers.
+- **Wrangler**: Used for local simulation of Cloudflare features and deployment.

README.md

@@ -1 +1,46 @@
 # Jimmy Gan Blog
+
+Personal website and blog built with [Astro](https://astro.build/) and deployed on [Cloudflare Pages](https://pages.cloudflare.com/).
+
+## 🚀 Features
+
+- **Astro 5**: Modern web framework for content-driven websites.
+- **TypeScript**: Typed JavaScript for better developer experience.
+- **Cloudflare Pages**: High-performance hosting with SSR support.
+- **MDX Support**: Use React components in Markdown.
+- **Sitemap & RSS**: Built-in support for SEO and feed readers.
+
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js (Latest LTS recommended)
+- npm
+
+### Setup
+
+```bash
+npm install
+```
+
+### Commands
+
+| Command | Action |
+| :--- | :--- |
+| `npm run dev` | Starts local dev server at `localhost:4321` |
+| `npm run build` | Build your production site to `./dist/` |
+| `npm run preview` | Preview your build locally with Wrangler |
+| `npm run deploy` | Build and deploy to Cloudflare Pages |
+| `npm run check` | Run type-checks and dry-run deployment |
+
+## 📁 Project Structure
+
+- `src/content/`: Blog posts and other content collections.
+- `src/pages/`: File-based routing for your pages.
+- `src/components/`: Reusable Astro components.
+- `src/layouts/`: Page layouts.
+- `public/`: Static assets like images and favicons.
+
+## 📄 License
+
+All rights reserved.