diff --git a/README.md b/README.md
index 71cc8e0..a31b976 100644
--- a/README.md
+++ b/README.md
@@ -1,85 +1,111 @@
 # aturi.to
 
-Universal links for the ATmosphere. Share ATProto content with anyone, let them choose where to view it.
+Universal links for the Atmosphere. Share ATProto content with anyone, let them choose where to view it — and jump between clients yourself, in one click, with the companion browser extension.
 
 ## What is aturi.to?
 
-aturi.to is a simple service that makes it easy to share ATProto content across different clients. When someone visits an aturi.to link, they see all available platforms where they can view that content (Bluesky, Anisota, Blacksky, Leaflet, pdsls, atp.tools, etc.) and can choose their preferred one.
+aturi.to is a small ecosystem for navigating the Atmosphere (ATProto) web. It has two halves that share the same waypoint catalog and URI parsers:
 
-## Features
+- **The web app** at [aturi.to](https://aturi.to) turns any ATProto URI into a universal link. When someone opens an `aturi.to/...` URL, they see every supported app that can render that content (Bluesky, Anisota, Blacksky, Red Dwarf, Leaflet, Tangled, Margin, Grain, PDSls, atp.tools, and many more) and pick the one they prefer.
+- **The browser extension** ([`extension/`](extension/)) puts that same catalog in your toolbar. From any supported page, click the icon to open the same content in any other client, or flip on auto-redirect to silently rewrite links between apps before they load.
 
-- **Universal Sharing**: One link works everywhere
-- **Platform Agnostic**: Recipients choose their preferred ATProto client
-- **Rich Previews**: Dynamic OpenGraph images for beautiful social sharing
-- **Easy Integration**: Simple URL structure, no API keys required
+If aturi.to is "send a link, let them pick the client," the extension is the inverse: "I landed on a link, take me to *my* client."
 
 ## Browser extension
 
-A companion browser extension lives in [`extension/`](extension/). It lets you
-open the current page in any other Aturi waypoint with one click, and can
-auto-redirect links between apps based on your preferences. See
-[`extension/README.md`](extension/README.md) for dev and build instructions.
+The extension is a first-class part of Aturi — for many users it's the primary way they use the project day to day. It's available for Chrome, Firefox, and Safari (via WXT + Xcode's web-extension converter).
 
-## URL Structure
+### What it does
+
+- **One-click jump.** When you're on a supported site (bsky.app, blacksky.community, leaflet.pub, tangled.org, margin.at, pdsls.dev, atp.tools, and dozens more), click the toolbar icon to see every other Atmosphere waypoint that can render the same post, profile, list, or record. Click one and it opens in a new tab.
+- **Auto-redirect.** Flip a switch and links get silently rewritten to your preferred client *before* they load. Pick a favorite per "data family" (Bluesky-style clients, Publications, Tangled, Margin, Grain, Pinkleap, Semble, Streamplace, Popfeed, Sifa, Blento). Powered by `chrome.declarativeNetRequest`, so it's fast and doesn't read your browsing history.
+- **Custom waypoints.** Wire up any site that uses a consistent URL structure via templates like `/profile/{handle}` or `/u/{handle}/p/{rkey}`. The extension forward-fills *and* reverse-matches the templates, so custom waypoints are first-class everywhere — popup, auto-redirect, and visibility controls.
+- **Visibility & ordering.** Hide waypoints you'll never use, drag-and-drop the rest into the order you want, and the popup surfaces your most-used destinations first.
+- **Shared catalog.** The extension imports `@aturi/*` directly from the web app's `src/utils/`, so the waypoint list, URI parsers, and reverse parsers stay in sync between the two.
+
+See [`extension/README.md`](extension/README.md) for development, build, and Safari packaging instructions.
+
+### Supported waypoints
+
+The catalog covers roughly 25+ Atmosphere apps and dev tools across categories like:
+
+- **Bluesky clients** — Bluesky, Anisota, Blacksky, Red Dwarf, Witchsky, Catsky, Deer, and other forks
+- **Publications** — Leaflet, Standard Site readers
+- **Apps** — Tangled, Margin, Grain, Pinkleap, Semble, Streamplace, Popfeed, Sifa, Blento, Offprint, pckt, Anisota Reader
+- **Dev tools** — PDSls, atp.tools, Anisota Explorer
+
+Want to add a new waypoint? Open a PR against [`src/utils/waypoints.data.ts`](src/utils/waypoints.data.ts) — both the web app and the extension pick it up automatically.
+
+## Web app features
+
+- **Universal sharing** — one link works everywhere
+- **Platform-agnostic landing page** — recipients choose their preferred client
+- **Rich previews** — dynamic OpenGraph images for beautiful social sharing
+- **Easy integration** — simple URL structure, no API keys required
+- **Handle and DID resolution** — handles, DIDs, and full `at://` URIs all work
+
+### URL structure
+
+Profiles:
 
-### For profiles:
 ```
 aturi.to/[handle or did]
 ```
+
 Example: `aturi.to/alice.bsky.social`
 
-### For records (posts, lists, etc.):
+Records (posts, lists, etc.):
+
 ```
 aturi.to/[handle or did]/[collection]/[rkey]
 ```
+
 Example: `aturi.to/alice.bsky.social/app.bsky.feed.post/3k7qw...`
 
-## Running Locally
+## Running locally
 
 ### Prerequisites
 
-- Node.js 20.9.0 or higher (use `.nvmrc` file with nvm: `nvm use`)
+- Node.js 20.9.0 or higher (use `.nvmrc` with nvm: `nvm use`)
 
-### Steps
+### Web app
 
-1. Clone the repository:
 ```bash
 git clone https://github.com/yourusername/aturi-to.git
 cd aturi-to
-```
-
-2. Use the correct Node version (if using nvm):
-```bash
 nvm use
-```
-
-3. Install dependencies:
-```bash
 npm install
+npm run dev
 ```
 
-4. Run the development server:
+Then open [http://localhost:3000](http://localhost:3000).
+
+### Browser extension
+
 ```bash
-npm run dev
+cd extension
+npm install
+npm run dev            # Chrome (loads the extension into a fresh Chromium profile)
+npm run dev:firefox    # Firefox
 ```
 
-5. Open [http://localhost:3000](http://localhost:3000) in your browser.
+WXT hot-reloads on changes. For release builds and Safari packaging, see [`extension/README.md`](extension/README.md).
 
 ## Deployment
 
-This project is designed to be deployed on Vercel for optimal OG image generation:
+The web app is designed for Vercel so the OpenGraph route can use the Edge Runtime:
 
 1. Push your code to GitHub
 2. Import the repository in Vercel
-3. Deploy!
+3. Deploy
 
-The site will automatically use Vercel's Edge Runtime for OG image generation.
+The extension ships as standalone bundles via `npm run zip` / `npm run zip:firefox` (and `xcrun safari-web-extension-converter` for Safari).
 
 ## Integration
 
 Want to add aturi.to links to your app? Check out the [Integration Guide](https://aturi.to/integrate) for code examples and best practices.
 
-### Quick Example (TypeScript)
+### Quick example (TypeScript)
 
 ```typescript
 function toAturiLink(atUri: string): string {
@@ -88,59 +114,64 @@ function toAturiLink(atUri: string): string {
 }
 ```
 
-## Tech Stack
+## Tech stack
 
-- **Next.js 16** - App Router with React Server Components
-- **TypeScript** - Type safety throughout
-- **@vercel/og** - Dynamic OpenGraph image generation
-- **@vercel/analytics** - Privacy-focused analytics
-- **Tailwind CSS** - Utility-first styling (v4)
+**Web app**
 
-## Contributing
+- **Next.js 16** — App Router with React Server Components
+- **TypeScript** — type safety throughout
+- **@vercel/og** — dynamic OpenGraph image generation
+- **@vercel/analytics** — privacy-focused analytics
+- **Tailwind CSS v4** — utility-first styling
+- **Framer Motion** — page and component animations
+
+**Extension**
 
-This is a community tool for the ATProto ecosystem. Contributions are welcome!
+- **WXT** — cross-browser MV3/MV2 build tooling (Chrome, Firefox, Safari)
+- **React 19** — popup and options UI
+- **`chrome.declarativeNetRequest`** — fast, privacy-preserving auto-redirect
+- **`@dnd-kit`** — drag-and-drop ordering of waypoints
+- **Vitest** — unit tests for templates, rules, and reverse parsers
+
+## Contributing
 
-## Forking & Custom Domains
+This is a community tool for the Atmosphere ecosystem. Contributions are welcome — bugs, new waypoints, popup polish, and extension features all land in the same repo. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Want to run your own instance with a custom domain? aturi.to is designed to be forkable!
+## Forking & custom domains
 
-### Quick Start
+Want to run your own instance with a custom domain? aturi.to is designed to be forkable.
 
 ```bash
-# Clone the repository
 git clone https://github.com/yourusername/aturi-to.git my-custom-instance
 cd my-custom-instance
-
-# Run the interactive setup
 npm run setup-fork
 
-# Start developing
 npm install
 npm run dev
 ```
 
-**See [QUICKSTART.md](QUICKSTART.md) for a complete 10-minute setup guide.**
-
 The setup script will help you configure:
+
 - Your custom domain
-- Site branding and metadata  
+- Site branding and metadata
 - Attribution information
 - Environment variables
 
-### More Resources
+### More resources
 
-- [Quick Start Guide](QUICKSTART.md) - Get running in 10 minutes
-- [Forking Guide](FORKING.md) - Detailed customization instructions
-- [Contributing Guide](CONTRIBUTING.md) - How to contribute back
+- [Quick Start Guide](QUICKSTART.md) — get running in 10 minutes
+- [Forking Guide](FORKING.md) — detailed customization instructions
+- [Contributing Guide](CONTRIBUTING.md) — how to contribute back
+- [Extension README](extension/README.md) — extension dev, build, and Safari notes
 
 When forking, please keep your source code open (GPL v3) and credit the original project.
 
 ## License
 
-This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the GNU General Public License v3.0 or later — see the [LICENSE](LICENSE) file for details.
 
-**GPL v3 ensures:** All forks and modifications must remain open source and credit the original work. When you fork aturi.to, you must share your source code and maintain the same GPL v3 license.
+**GPL v3 ensures:** all forks and modifications must remain open source and credit the original work. When you fork aturi.to, you must share your source code and maintain the same GPL v3 license.
 
 ## Acknowledgments
 
-Built for the ATProto ecosystem and inspired by the need for universal, platform-agnostic sharing.
+Built for the Atmosphere ecosystem and inspired by the need for universal, platform-agnostic sharing — and for a way to escape link silos in your own browser.