diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 00000000..c840da08
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
diff --git a/README.md b/README.md
index 6294b108..b721fb29 100644
--- a/README.md
+++ b/README.md
@@ -35,9 +35,10 @@ https://controld.com/dashboard/profiles/741861frakbm/filters
 
 ### Configure the script
 
-1. **Clone & install**
+1. **Fork & clone**
+   > Fork this repo first (click **Fork** on GitHub), then clone your fork:
    ```bash
-   git clone https://github.com/your-username/ctrld-sync.git
+   git clone https://github.com/YOUR_USERNAME/ctrld-sync.git
    cd ctrld-sync
    uv sync
    ```
@@ -113,23 +114,20 @@ This project includes a comprehensive test suite to ensure code quality and corr
 
 **Basic test execution:**
 ```bash
-# Install dev dependencies first
-pip install pytest pytest-mock pytest-xdist
-
-# Run all tests
-pytest tests/
+# Dev dependencies are included when you run `uv sync` (see Quick start)
+uv run pytest tests/
 ```
 
 **Parallel test execution (recommended):**
 ```bash
 # Run tests in parallel using all available CPU cores
-pytest tests/ -n auto
+uv run pytest tests/ -n auto
 
 # Run with specific number of workers
-pytest tests/ -n 4
+uv run pytest tests/ -n 4
 ```
 
-**Note on parallel execution:** The test suite is currently small (~78 tests, <1s execution time), so parallel execution overhead may result in longer wall-clock time compared to sequential execution. However, pytest-xdist is included for:
+**Note on parallel execution:** The test suite is currently small (~95 tests, <1s execution time), so parallel execution overhead may result in longer wall-clock time compared to sequential execution. However, pytest-xdist is included for:
 - **Test isolation verification** - Ensures tests don't share state
 - **Future scalability** - As the test suite grows, parallel execution will provide significant speedups
 - **CI optimization** - May benefit from parallelization in CI environments with different characteristics
@@ -139,13 +137,13 @@ pytest tests/ -n 4
 For active development with frequent test runs:
 ```bash
 # Run tests sequentially (faster for small test suites)
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # Run specific test file
-pytest tests/test_security.py -v
+uv run pytest tests/test_security.py -v
 
 # Run tests matching pattern
-pytest tests/ -k "test_validation" -v
+uv run pytest tests/ -k "test_validation" -v
 ```
 
 ## Release Process
@@ -155,7 +153,7 @@ This project uses manual releases via GitHub Releases. To create a new release:
 1. **Ensure all changes are tested and merged to `main`**
    ```bash
    # Verify tests pass
-   pytest tests/
+   uv run pytest tests/
    
    # Verify security scans pass
    bandit -r main.py -ll