diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7b7016d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,62 @@
+# CMMID site — dev guide
+
+Jekyll site, deploys to https://cmmid.github.io via GitHub Pages on push to `master`.
+
+Use the README for detailed instructions to add new posts. 
+
+## Local dev
+
+```bash
+make setup   # first time: bundle install
+make run     # bundle exec jekyll serve -w → http://localhost:4000
+```
+
+Requires Ruby + Bundler.
+
+## Adding a post
+
+1. Create `topics/{topic}/_posts/YYYY-MM-DD-{slug}.md`
+2. Copy front-matter from `/topics/YYYY-MM-DD-post-template.md`
+3. Place figures in `topics/{topic}/figures/`, reports in `topics/{topic}/reports/` (use unique filenames)
+
+Front-matter example:
+
+```yaml
+---
+title: Post title
+description: One-line summary
+status: paper-under-peer-review
+update: YYYY-MM-DD
+tags: [transmission-dynamics]
+authors:
+  - id: author_id
+---
+```
+
+**Status options:** `paper-under-peer-review`, `paper-accepted-at-journal`, `paper-published-at-journal`, `real-time-report`, `report`, `comment-opinion-online`, `comment-opinion-journal`
+
+**Tags:** `transmission-dynamics`, `severity`, `lmic-considerations`, `control-measures`, `mixing-patterns`, `healthcare-settings`, `comments-opinions`, `forecasts-and-projections`
+
+Author IDs come from `_data/authors.yml`. Special group IDs: `ncov-group` (CMMID COVID-19 working group, 48 members), `chil-group`.
+
+For R Markdown HTML fragment output: set `rmarkdown_html_fragment: true` in front-matter.
+
+## Adding a Shiny app
+
+Copy `_shinyapp/template.md` to a new file in `_shinyapp/`, edit `shinyurl` and `title` only.
+
+## Adding a tag
+
+Two steps required — both must be present before tag appears:
+1. Create topic page in `topics/{topic}/` with `tag_filter` matching the new tag
+2. Add entry to `_data/translations.yml` with `id` matching the tag and `en-gb` value
+
+## Key files
+
+| Path | Purpose |
+|------|---------|
+| `_config.yml` | Site config, plugins, permalink structure |
+| `_data/authors.yml` | All author IDs and metadata |
+| `_data/translations.yml` | Tag display names and i18n strings |
+| `topics/YYYY-MM-DD-post-template.md` | Post template |
+| `Makefile` | `make run` / `make setup` |
diff --git a/README.md b/README.md
index abbaf0c..00d9cb6 100755
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ The source for the [web page](https://cmmid.github.io/) advertising assorted [CM
 
 # Adding NEW posts
 
-To add a new post to the website, add a new markdown or html file to `/topics/covid19/_posts` using the template [/topics/YYYY-MM-DD-post-template.md](https://github.com/cmmid/cmmid.github.io/blob/master/topics/YYYY-MM-DD-post-template.md)..
+To add a new post to the website, add a new markdown or html file to `/topics/{topic}/_posts` using the template [/topics/YYYY-MM-DD-post-template.md](https://github.com/cmmid/cmmid.github.io/blob/master/topics/YYYY-MM-DD-post-template.md).
 
 Front-matter variables are optional, but the following are available:
 
@@ -42,12 +42,12 @@ authors:
 If you want to use mathjax, tabs, or other objects regularly used in Rmarkdown html files:
  1. set 'output: html_fragment' in your rmarkdown file
  2. set rmarkdown_html_fragment: true in the front-matter of your post
- 
 
 # Figures and attachments
 
-Copy your figures and attachments into the `/topics/covid19/figures` and `/topics/covid19/reports` directories accordingly. Make sure they have a unique name (chances are someone else has already generated a `figure1.png` file), or create under `/topics/covid19/figures` specifically for your figures. The template contains some example markup demonstrating this.
-
+Copy your figures and attachments into the `/topics/{topic}/figures` and `/topics/{topic}/reports` directories accordingly. 
+Make sure they have a unique name (chances are someone else has already generated a `figure1.png` file), or create a subdirectory under `/topics/{topic}/figures` specifically for your figures. 
+The template contains some example markup demonstrating this.
 
 # Adding TRANSLATED posts