diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d05046f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,38 @@
+# chrisdoescloud.com
+
+Personal static site deployed to AWS (S3 + CloudFront via SAM).
+
+## How it works
+
+- `build.py` — Python script that converts Markdown → HTML and writes to `dist/`
+- `posts/*.md` — blog posts with YAML frontmatter
+- `about/index.md` — about page
+- `cv/` — CV page (toggled via `CV_PUBLISHED` flag in `build.py`)
+- `src/styles/main.css` — site stylesheet
+- `static/` — assets copied verbatim to `dist/`
+- `template.yaml` — AWS SAM template (S3 bucket + CloudFront distribution)
+- `samconfig.toml` — SAM deploy config
+- `.github/workflows/` — CI/CD via GitHub Actions with OIDC auth
+
+## Common tasks
+
+```bash
+make build      # run build.py, output goes to dist/
+make deploy     # sam build + sam deploy
+```
+
+## Adding a post
+
+Create `posts/<slug>.md` with frontmatter:
+
+```markdown
+---
+title: My Post
+date: 2026-01-01
+draft: false
+---
+```
+
+## Stack
+
+Python 3.x · AWS SAM · S3 · CloudFront · GitHub Actions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..83b0fea
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# chrisdoescloud.com
+
+Personal site — static HTML generated from Markdown, hosted on S3 + CloudFront.
+
+## Prerequisites
+
+- [uv](https://github.com/astral-sh/uv)
+- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html)
+- AWS credentials with access to the `chrisdoescloud-site` stack
+
+## Local development
+
+```bash
+make serve   # build + serve at http://localhost:8080
+```
+
+## Deploy
+
+```bash
+make deploy  # build, sync to S3, invalidate CloudFront
+```
+
+To provision or update infrastructure:
+
+```bash
+make infra   # sam deploy (CloudFormation stack)
+```
+
+## Adding a post
+
+Create `posts/<slug>.md` with YAML frontmatter:
+
+```markdown
+---
+title: My Post Title
+date: 2026-01-01
+draft: false
+---
+
+Post content here.
+```
+
+Set `draft: true` to exclude from the build.
+
+## Project layout
+
+```
+posts/          Markdown blog posts
+about/          About page
+cv/             CV page (disabled by default)
+src/styles/     CSS
+static/         Assets copied verbatim to dist/
+build.py        Static site generator
+template.yaml   AWS SAM / CloudFormation template
+Makefile        Common tasks
+```