diff --git a/README.md b/README.md
index 92a07ac..eb1d411 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,59 @@
-# stm32PinValidator
+# STM32 Pin Validator
 
+KiCad pcbnew action plugin that validates STM32 MCU pin assignments by comparing three sources:
+
+1. **PCB layout** - pad net names (via pcbnew API)
+2. **Schematic** - pin names and labels (parsed from `.kicad_sch`)
+3. **STM32CubeMX** - GPIO signals and labels (parsed from `.ioc`)
+
+Results are shown in a colour-coded table so mismatches are easy to spot.
+
+## Features
+
+- Colour-coded status: green (match), yellow (review), red (PCB/IOC only), grey (power)
+- Filter to show warnings only
+- Handles pin remapping and GPIO aliases (e.g. PA9/PA11)
+- Traces schematic wires to find connected labels (both local and global)
+- Normalises naming conventions (`+`/`P`, `-`/`M`, leading `/`)
+- Remembers previously used `.ioc` file paths
+
+## Installation
+
+### Manual
+
+Copy the contents of `plugins/` into your KiCad scripting plugins directory:
+
+- **Windows**: `%APPDATA%\kicad\<version>\scripting\plugins\stm32_pin_validator\`
+- **Linux**: `~/.local/share/kicad/<version>/scripting/plugins/stm32_pin_validator/`
+- **macOS**: `~/Library/Application Support/kicad/<version>/scripting/plugins/stm32_pin_validator/`
+
+### KiCad PCM
+
+Coming soon.
+
+## Usage
+
+1. Open your PCB in KiCad pcbnew
+2. Click the STM32 Pin Validator toolbar button (or find it under **Tools > External Plugins**)
+3. Select the MCU footprint and browse to the matching `.ioc` file
+4. Review the results table
+
+## Status column
+
+| Status | Meaning |
+|--------|---------|
+| Match | Schematic label or PCB net matches IOC label/signal |
+| Review | Both sides have signals but names differ |
+| PCB Only | Pin connected in PCB but not configured in IOC |
+| IOC Only | Pin configured in IOC but unconnected in PCB |
+| NC | Not connected on either side |
+| Power | Power pin (VDD, VSS, etc.) - skipped |
+
+## Requirements
+
+- KiCad 9.0 or later
+- An STM32CubeMX `.ioc` file for the target MCU
+
+## License
+
+GPL-3.0-or-later