diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2c60647
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# CodeHeat
+
+A Visual Studio Code extension that tracks how much time you actually spend in
+each project and each file, and paints that time back onto the file explorer as
+a heatmap.
+
+Everything stays on your machine. There is no account, no server, no sync and
+no telemetry — the extension writes a single JSON file into VS Code's own
+extension storage directory and nothing leaves it.
+
+## What it does
+
+- **Per-project and per-file time tracking.** A 30-second heartbeat credits time
+  to the file you are currently working in, but only while you are actually
+  active. Typing, moving the cursor and switching editors all count as activity.
+- **Idle detection.** After a configurable period with no editor activity
+  (3 minutes by default) the heartbeat stops crediting time, so a session left
+  open overnight does not turn into eight tracked hours.
+- **Explorer heatmap.** Every file that has tracked time gets a badge from 1 to
+  5 in the explorer, coloured blue → green → yellow → orange → red. The scale is
+  relative to the hottest file in that project, so it shows where the work went
+  rather than an absolute number. Hovering a file shows the exact time.
+- **Status bar clock.** The left of the status bar shows the total time tracked
+  in the current project. Click it to open a summary.
+- **Summary view.** A panel listing the 25 hottest files in the project as a bar
+  chart, plus the project total.
+- **Export and clear.** Export the whole dataset as JSON, or wipe the data for
+  the current project only.
+
+Time is attributed to a file only when that file belongs to an open workspace
+folder. Files opened outside a workspace folder are not tracked.
+
+## Requirements
+
+- Visual Studio Code 1.85.0 or newer.
+
+That is the whole list. The extension is plain JavaScript against the VS Code
+API with no runtime dependencies and no build step.
+
+## Installing
+
+The extension is not on the Marketplace. Two ways to install it:
+
+**Copy it into the extensions folder**
+
+```bash
+git clone https://github.com/dualfroz/codeheat.git ~/.vscode/extensions/codeheat
+```
+
+Then restart VS Code.
+
+**Or package it into a .vsix**
+
+```bash
+npx @vscode/vsce package
+code --install-extension codeheat-0.1.0.vsix
+```
+
+## Commands
+
+Open the command palette and search for "CodeHeat":
+
+| Command | What it does |
+| --- | --- |
+| CodeHeat: Show Time Summary | Opens the per-file bar chart for the current project |
+| CodeHeat: Toggle Tracking | Pauses or resumes tracking; the status bar shows the state |
+| CodeHeat: Export Data as JSON | Writes the full dataset to a file you choose |
+| CodeHeat: Clear Data for This Project | Deletes tracked data for the current project only |
+
+## Settings
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `codeheat.idleThresholdMinutes` | `3` | Minutes of no editor activity before tracking pauses |
+| `codeheat.heatmapEnabled` | `true` | Show the heat badges in the file explorer |
+
+## Where the data lives
+
+A single file, `codeheat-data.json`, inside VS Code's global storage directory
+for this extension. On Linux that is usually:
+
+```
+~/.config/Code/User/globalStorage/foksiu-local.codeheat/codeheat-data.json
+```
+
+The structure is straightforward — projects keyed by their absolute workspace
+path, each with a total and a map of workspace-relative file paths to seconds:
+
+```json
+{
+  "projects": {
+    "/home/you/work/api": {
+      "label": "api",
+      "totalSeconds": 7230,
+      "files": { "src/server.js": 4100, "README.md": 300 }
+    }
+  }
+}
+```
+
+Because projects are keyed by absolute path, moving a project directory starts
+a new entry rather than continuing the old one.
+
+## Tested on
+
+Linux Mint 22.2 with the Cinnamon desktop, VS Code 1.85+. Nothing in the
+extension is platform-specific, so it should work anywhere VS Code runs, but
+that is the only environment it has actually been used in.
+
+## Licence
+
+No licence has been chosen yet.