diff --git a/README.md b/README.md
index c9b2ff6..7a94a7f 100644
--- a/README.md
+++ b/README.md
@@ -1,35 +1,81 @@
 # nixie
 
-`nixie` is a simple command-line tool that validates Mermaid diagrams embedded in Markdown files.
+`nixie` validates Mermaid diagrams embedded in Markdown files.
 
-The CLI scans each provided file (or directory) for `mermaid` code blocks and
-invokes `mermaid-cli` to verify that the diagrams can be rendered without
-errors.
+## Features
 
-## Usage
+- Recursively searches directories for Markdown files
+- Parses `mermaid` code blocks and uses `@mermaid-js/mermaid-cli` to validate
+- Runs checks concurrently for faster feedback
+- Prints clear error messages for failing diagrams
+
+## Requirements
+
+- Python 3.11+
+- Node.js with `npx` and `@mermaid-js/mermaid-cli`
+
+## Installation
+
+### From PyPI
+
+End users can install the latest release directly from PyPI:
 
 ```bash
-nixie path/to/file.md
+pip install nixie
 ```
 
-Use `--concurrency` to control how many diagrams are processed in parallel. The tool relies on
-Node.js and `@mermaid-js/mermaid-cli` being available on your system.
+This provides the `nixie` command without any development extras.
 
-## Development
+### Development Setup
 
-Development dependencies are managed via `pyproject.toml`. After installing
-[uv](https://github.com/astral-sh/uv), run:
+To contribute to nixie, install the package in editable mode and set up
+development tools using [uv](https://docs.astral.sh/uv/), Astral's fast Python
+package manager:
 
 ```bash
+pip install -e .
 uv sync --include dev
 ```
 
-This installs linters and test tools such as Ruff, Pyright, pytest and
-pytest-asyncio.
+## Usage
+
+```bash
+nixie [--concurrency N] FILE [FILE...]
+```
+
+`--concurrency` controls how many diagrams are processed in parallel (defaults
+to the number of CPU cores or `4` if this cannot be determined). Paths can be
+files or directories.
 
-Before running the test suite, install the project in editable mode so the
-package can be imported:
+Example:
 
 ```bash
-pip install -e .
+$ nixie bad.md
+Parse error on line 1:
+invalid diagram
+^
+Unexpected token: syntax error
+```
+
+## Development
+
+Run formatting, linting, type checking and tests before committing:
+
+```bash
+ruff format
+ruff check
+pyright
+pytest
 ```
+
+The integration tests mock the CLI so Node.js is not needed during testing.
+
+## Project Structure
+
+- `nixie/cli.py` – command-line interface and validation logic
+- `nixie/unittests/` – unit tests for helper functions
+- `tests/integration/` – behavioural tests covering the CLI
+
+## License
+
+See `LICENSE` for license details.