diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7f21781
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# Norrisizer
+
+A small, silly web app that generates absurd, hyperbolic "Chuck Norris Facts" using
+Google's Gemini API — and quietly personalizes them to your taste over time.
+
+Built as a weekend project for **Google AI Dojo Season 2**.
+
+## What it does
+
+- Generates a one-liner Chuck Norris-style joke, optionally themed around a topic you type in.
+- You rate each joke (`Love it` / `Too much!` / `Needs more` / `Not for me`).
+- Under the hood, an LLM call turns your ratings into a running bullet-point list of
+  your taste, which is folded back into the system prompt for future jokes —
+  no fine-tuning, just prompt-based personalization that evolves per session.
+- Jokes you loved get collected into a small "best of" list the model uses as style
+  reference (without copying them verbatim).
+- A belt-ranking system (white → black) tracks how many jokes you've rated.
+- Bilingual UI (Japanese / English).
+- A couple of easter eggs (try mentioning a certain 80s pop song as your topic).
+
+## Stack
+
+- **Backend:** Flask + Gunicorn
+- **Model:** Gemma (via the Gemini API), with an optional unlock code to switch to Gemini
+- **Frontend:** a single templated HTML page, no framework
+- **Deploy:** Dockerfile included, designed to run on Cloud Run (reads `PORT` from env)
+
+## Running locally
+
+```bash
+pip install -r requirements.txt
+export GEMINI_API_KEY=your-key-here
+python app.py
+```
+
+Without `GEMINI_API_KEY` set, the app falls back to a couple of canned jokes so the
+UI still works.
+
+### Environment variables
+
+| Variable         | Purpose                                                        |
+|------------------|-----------------------------------------------------------------|
+| `GEMINI_API_KEY` | Gemini API key. Required for live joke generation.              |
+| `UNLOCK_CODE`     | Optional code that lets a user switch from Gemma to Gemini.     |
+| `PORT`           | Port to listen on (defaults to `8080`).                         |
+
+## Disclaimer
+
+This is a joke generator in the classic "Chuck Norris Facts" internet-meme genre —
+exaggerated, absurd, and not intended to mock or harm anyone. It doesn't take itself
+seriously, and neither should you.