diff --git a/README.md b/README.md
index df27ff8..3a64885 100644
--- a/README.md
+++ b/README.md
@@ -4,51 +4,89 @@
 
 - [👉  Check it out](https://synchub.to/)
 
+Install the GitHub App, connect your tangled identity, and every commit,
+branch, and tag will be mirrored to tangled. No additional configuration required.
+
 ## Features
 
-- a GitHub App
-- OAuth connection to tangled
+- no workflow file required
+- one-time OAuth connection to tangled
 - per-push sync of branches and tags
+- a dashboard where you can resync, pause, or rotate keys
 
 > [!IMPORTANT]
 > Only public repositories are synced (tangled does not yet support private repositories).
 
-## Try it out locally
-
-You will need:
+## Run it locally
 
-1. A GitHub App with a webhook pointed at your local tunnel and `contents:read`, `metadata:read` permissions plus the `push`, `create`, `delete`, `repository` events.
-2. A [Neon](https://neon.tech) Postgres database.
-3. An AT Protocol confidential OAuth client (see `.well-known/atproto-client-metadata.json`).
+You will need [Node 24+](https://nodejs.org), [pnpm 10+](https://pnpm.io)
+(`corepack enable`), a [Neon](https://neon.tech) database (free tier is fine),
+and the [Smee CLI](https://smee.io) for webhook proxying
+(`pnpm add -g smee-client`).
 
-Set your environment variables in a `.env` file:
-
-```env
-NUXT_GITHUB_APP_ID=<github app id>
-NUXT_GITHUB_APP_PRIVATE_KEY=<github app private key, pem>
-NUXT_GITHUB_WEBHOOK_SECRET=<github app webhook secret>
-NUXT_DATABASE_URL=<neon postgres connection string>
-NUXT_ENCRYPTION_KEY=<32-byte base64 key for sealing ssh private keys>
-NUXT_CRON_SECRET=<shared secret for the worker cron route>
+```bash
+corepack enable
+pnpm install
+cp .env.example .env   # fill in the values, see below
+pnpm db:migrate
+pnpm dev
 ```
 
-### Setup
+`.env.example` documents every variable. Generate the secrets with the bundled
+helpers:
 
 ```bash
-# install dependencies
-corepack enable
-pnpm install
+pnpm gen:jwk              # NUXT_ATPROTO_PRIVATE_JWK
+pnpm gen:encryption-key   # NUXT_ENCRYPTION_KEY and NUXT_SESSION_PASSWORD
+pnpm gen:cron-secret      # NUXT_CRON_SECRET
+```
 
-# serve in dev mode, with hot reload at localhost:3000
-pnpm dev
+The rest (`NUXT_DATABASE_URL`, the `NUXT_GITHUB_APP_*` values) come from your
+Neon dashboard and a [new GitHub App](https://github.com/settings/apps/new).
+The App needs `contents:read` and `metadata:read` permissions plus the `push`,
+`create`, `delete`, and `repository` events, with its webhook pointed at your
+Smee URL.
 
-# build for production
-pnpm build
+In separate terminals, proxy webhooks and drain the job queue:
 
-# preview in production mode
-pnpm preview
+```bash
+smee --url <your-smee-url> --target http://127.0.0.1:3000/api/github/webhook
+pnpm jobs:tick   # run as needed; in production Vercel Cron does this
 ```
 
+## Deploy to Vercel
+
+synchub.to runs on Vercel with a Neon Postgres database.
+
+1. Apply migrations against your production database:
+   ```bash
+   NUXT_DATABASE_URL="<pooled neon connection string>" pnpm db:migrate
+   ```
+2. Import the repo into Vercel (the Nuxt preset is auto-detected) and set every
+   variable from `.env.example` under **Settings > Environment Variables**.
+   Mark the secrets (`NUXT_DATABASE_URL`, `NUXT_GITHUB_APP_PRIVATE_KEY`,
+   `NUXT_ATPROTO_PRIVATE_JWK`, `NUXT_ENCRYPTION_KEY`, `NUXT_SESSION_PASSWORD`,
+   `NUXT_GITHUB_WEBHOOK_SECRET`, `NUXT_CRON_SECRET`) as **Sensitive**.
+3. Set `NUXT_PUBLIC_URL` to your real origin and point the GitHub App webhook at
+   `https://<your-domain>/api/github/webhook`.
+4. Deploy.
+
+The worker runs on a Vercel Cron (declared in `nuxt.config.ts`, so no
+`vercel.json` is needed) and appears under **Settings > Cron Jobs** after the
+first deploy.
+
+> [!NOTE]
+> The GitHub App private key is multi-line, but Vercel env values are single
+> line. Collapse the newlines to literal `\n` before pasting:
+>
+> ```bash
+> awk 'NF {printf "%s\\n", $0}' your-app.private-key.pem
+> ```
+>
+> Locally, keep the real newlines as shown in `.env.example`. Migrations are
+> manual: re-run `pnpm db:migrate` against production whenever you ship a
+> schema change.
+
 ## License
 
 Made with ❤️