diff --git a/README.md b/README.md
index b1d0000..851e27b 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,29 @@ Useful when you need mouse movement that is statistically indistinguishable
 from a real user — for ML-based bot-detection research, behavioral biometrics
 prototyping, or replay-based test fixtures.
 
+- Source: <https://git.vercanti.com/yellowdog/human_mouse>
+- License: MIT
+
 ## Install
 
+The package is not on PyPI yet. Install directly from the git remote:
+
 ```bash
-uv add human_mouse              # or: pip install human_mouse
-uv add "human_mouse[demo]"      # also installs cloakbrowser for the example
+# core only
+uv add "human_mouse @ git+https://git.vercanti.com/yellowdog/human_mouse.git"
+
+# with the bundled CloakBrowser example
+uv add "human_mouse[demo] @ git+https://git.vercanti.com/yellowdog/human_mouse.git"
 ```
 
+Or pin to a specific commit / tag:
+
+```bash
+uv add "human_mouse @ git+https://git.vercanti.com/yellowdog/human_mouse.git@v0.1.0"
+```
+
+`pip install` works with the same `git+https://...` URL.
+
 ## One-time dataset download
 
 ```python
@@ -85,10 +101,13 @@ hm.replay(page, points, speed=1.0)
 ## Running the bundled example
 
 The `examples/` folder ships a Playwright canvas page (`demo.html`) plus a
-runner script that uses [CloakBrowser](https://github.com/CloakHQ/CloakBrowser):
+runner script that uses [CloakBrowser](https://github.com/CloakHQ/CloakBrowser).
+You need a local checkout for this since `examples/` ships only in the sdist:
 
 ```bash
-uv add "human_mouse[demo]"
+git clone https://git.vercanti.com/yellowdog/human_mouse.git
+cd human_mouse
+uv sync --extra demo
 python -m human_mouse download ./sapimouse_data            # one-time, ~8 MB
 uv run python examples/cloakbrowser_demo.py sapi           # one trajectory
 uv run python examples/cloakbrowser_demo.py multi --n 10   # 10 overlaid
@@ -99,6 +118,19 @@ Outputs land in `./outputs/`:
 - `sapi.png` + `sapi.json` — single trajectory screenshot and per-event coords
 - `multi/overlay.png` + per-run JSONs + `summary.json`
 
+## Development
+
+```bash
+git clone https://git.vercanti.com/yellowdog/human_mouse.git
+cd human_mouse
+uv sync --all-extras           # core + [demo] + [dev]
+uv run pytest                  # 23 tests, ~40s with SapiMouse present
+uv build                       # produces wheel + sdist in dist/
+```
+
+Integration tests auto-skip when `sapimouse_data/sapimouse/` is missing, so
+the core 10 unit tests run on a fresh clone without the dataset.
+
 ## What `replay` is and isn't
 
 **Is**: a deterministic replay of one real human's mouse path, warped to your
diff --git a/pyproject.toml b/pyproject.toml
index bcd0aa1..28833f5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,7 +31,8 @@ demo = ["cloakbrowser>=0.3.27"]
 dev = ["pytest>=7.0"]
 
 [project.urls]
-Homepage = "https://github.com/your-org/human_mouse"
+Homepage = "https://git.vercanti.com/yellowdog/human_mouse"
+Source = "https://git.vercanti.com/yellowdog/human_mouse"
 "SapiMouse dataset" = "https://www.ms.sapientia.ro/~manyi/sapimouse/sapimouse.html"
 
 [tool.hatch.build.targets.wheel]