From 636d07bcbaaf93132e9d9c7d318e03b95a6b654c Mon Sep 17 00:00:00 2001
From: "Gan, Jimmy" <jimmy.gan@adidas.com>
Date: Wed, 8 Jul 2026 02:22:42 +0800
Subject: [PATCH] docs: expand README + add CLAUDE.md for dev guidance

---
 CLAUDE.md | 36 ++++++++++++++++++++++++++++++++++++
 README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..683234c
--- /dev/null
+++ b/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.
diff --git a/README.md b/README.md
index 53552a0..0c58e5e 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,46 @@
-# Jimmy Gan Blog
\ No newline at end of file
+# 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.