diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index de8d432..45e632f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,6 +62,36 @@ out of sync with the Rust code.
 `cargo insta accept`
 3. commit the `.snap` files alongside code changes
 
+## playground
+
+the browser playground lives in `playground/`. to run it locally:
+
+```bash
+cd playground
+bun install
+bun run dev
+```
+
+to deploy manually to Cloudflare Pages:
+
+```bash
+cd playground
+bun run build
+bunx wrangler pages deploy dist --project-name=tryke-playground
+```
+
+this creates a preview deployment at a unique URL (e.g.
+`<hash>.tryke-playground.pages.dev`). to deploy straight to production, add
+`--branch main` — this is just metadata passed to Cloudflare and works from
+any local branch:
+
+```bash
+bunx wrangler pages deploy dist --project-name=tryke-playground --branch main
+```
+
+pushes to `main` that touch the playground or WASM crates deploy automatically
+to production via the `playground` GitHub Actions workflow.
+
 ## manual release
 
 1. bump version in both `crates/tryke/Cargo.toml` and `pyproject.toml`
diff --git a/README.md b/README.md
index 1db4861..9100d91 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,15 @@
 
 ## Getting started
 
-For more information, see the [documentation](https://tryke.dev/).
+Run tryke with [uvx](https://docs.astral.sh/uv/guides/tools/) to get started quickly:
 
-Write a test.
+```bash
+uvx tryke
+```
+
+Or, check out the [tryke playground](https://playground.tryke.dev) to try it out in your browser.
+
+To learn more about using tryke, see the [documentation](https://tryke.dev/).
 
 ```python
 from typing import Annotated
diff --git a/docs/index.md b/docs/index.md
index b047ec4..5790c82 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -48,6 +48,14 @@ A Rust-based Python test runner with a Jest-style API.
 
 ## Getting started
 
+Run tryke with [uvx](https://docs.astral.sh/uv/guides/tools/) to get started quickly:
+
+```bash
+uvx tryke test
+```
+
+Or, check out the [tryke playground](https://playground.tryke.dev) to try it out in your browser.
+
 ```python
 from typing import Annotated
 
@@ -110,4 +118,4 @@ This repository is licensed under the [MIT License](https://github.com/thejchap/
 
 ## Installation
 
-See the [installation](guides/installation.md) documentation.
+See the [installation](./guides/installation.md) documentation.