diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f9e72cc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,14 @@
+# How Do You Convert? Repository
+
+This repository hosts the HowDoYouConvert conversion catalog and the SvelteKit front end that renders every calculator page. The work is split between a generated data layer (`calculators_list.md` + `migrate.py`) and the `hdyc-svelte` app that consumes that data.
+
+Key facts:
+- `/calculators_list.md` is the canonical registry of published conversions. Each row in the active table becomes a calculator page in the UI.
+- `migrate.py` reads the registry and regenerates `hdyc-svelte/src/lib/data/calculators.ts`, so updates to calculations (or metadata like descriptions) must flow through the registry + generator.
+- `hdyc-svelte` renders the homepage, category lists, and calculator routes (`/[slug]`) using the generated data, along with helpers in `src/lib/data/unitDefinitions.ts` for glossary blurbs.
+- The Node/Svelte front end lives entirely in `hdyc-svelte`; use `npm run dev`, `npm run check`, and `npm run build` from that directory for development and verification.
+
+Typical workflow:
+1. Update `calculators_list.md` to add/adjust entries.
+2. Run `python migrate.py` from the repository root to refresh `hdyc-svelte/src/lib/data/calculators.ts`.
+3. Inside `hdyc-svelte`, run `npm run check` (and optionally `npm run dev` or `npm run build`) to ensure everything compiles before committing.