diff --git a/README.md b/README.md
new file mode 100644
index 0000000..beddf02
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# doki-theme-gitea
+
+A collection of [Doki Theme](https://github.com/doki-theme/doki-master-theme) colour palettes ported to Gitea CSS themes — 88 themes across 40+ anime and game series.
+
+Tested on Gitea **1.26**.
+
+## Installation
+
+1. Generate the theme files (requires Node.js 22+):
+
+   ```bash
+   git submodule update --init
+   npm install
+   npm run generate
+   ```
+
+2. Copy the generated CSS files to your Gitea custom directory:
+
+   ```bash
+   cp output/theme-doki-*.css /path/to/gitea/custom/public/assets/css/
+   ```
+
+3. Select a theme from **Settings → Appearance** in Gitea. All themes appear under the `Doki Theme:` prefix in the picker.
+
+No Gitea restart is required — themes are picked up on the next request.
+
+## Themes
+
+Themes are named `Doki Theme: {Series}: {Character}` (or `… ({variant})` for characters with multiple palettes). Dark and light variants are available for many characters.
+
+The `doki-master-theme` repository is included as a Git submodule. Run `git submodule update --remote` to pull in new palettes when the upstream repo is updated, then regenerate.
+
+## Credits
+
+Character colour palettes are from [doki-master-theme](https://github.com/doki-theme/doki-master-theme) by Unthrottled, used under its original licence.
+
+The Gitea port (theme generator and colour mapping) was written with [Claude Code](https://claude.ai/code).