diff --git a/README.md b/README.md
index efffcd6..e4e70c7 100644
--- a/README.md
+++ b/README.md
@@ -1,44 +1,82 @@
-# kestrove-core
+# Kestrove core
 
-Rust workspace that holds **all** Kestrove crypto and vault logic. Apple,
-Android and desktop apps call it through UniFFI. The server uses only `kv-proto`.
+This is the heart of **Kestrove**, the self-hosted password manager. Everything that touches your secrets
+lives here, in one Rust codebase that every app shares:
 
-| Crate | Status | Purpose |
-|---|---|---|
-| `kv-proto` | ✅ M0 | Wire types (Envelope, KDF params, API bodies). No secrets. |
-| `kv-crypto` | ✅ M0 | 2SKD (Argon2id + Secret Key), XChaCha20-Poly1305 envelopes, HPKE vault-key sealing, keyset, Ed25519, Secret Key format |
-| `kv-model` | ✅ M0 | Items, URL matching (PSL), TOTP (RFC 6238), password generator |
-| `kv-ffi` | ✅ M1 | The exported API (`VaultCore` with SQLite storage, local unlock key, sync; `totp_code`, `match_url`, `generate_password`) |
-| `kv-store` | ✅ M1 | SQLite replica (ciphertext only), base copies for merges, 10-version history |
-| `kv-sync` | ✅ M1 | TLS 1.3 + SPKI pins, OPAQUE login, RFC 9421 signing, pull/push/merge, signed manifest |
+- the **encryption** (your master password and Secret Key turn into the keys that lock your vault),
+- the **vault** itself (logins, passkeys, one-time codes, notes, cards, tags, "Sign in with Google"…),
+- **sync** with your Kestrove server, and the merging of changes made on two devices at once,
+- **passkeys** (creating and signing them), **one-time codes**, the **password generator**,
+- **import** from 1Password and CSV, and encrypted export.
 
-Spec: `../kestrove-spec/docs/02-cryptography.md` and `03-sync-protocol.md`.
+Because all apps use this same code, a vault works the same on iPhone, Mac, Android, Windows, Linux and in
+the browser, and the security-critical parts are written and reviewed once.
 
-## Setup
+You only need this repository to **build the apps** or to work on Kestrove itself. To run a server, see
+[`kestrove-server`](https://gitea.samialabri.com/kestrove/kestrove-server).
+
+## How the apps use it
+
+| App | How it gets the core |
+|---|---|
+| iPhone, iPad, Mac (`kestrove-apple`) | `scripts/build-apple.sh` builds a Swift package |
+| Android (`kestrove-android`) | `scripts/build-android.sh` builds the native libraries and Kotlin bindings |
+| Windows and Linux (`kestrove-desktop`) | Uses the Rust code directly |
+| Web vault (`kestrove-web`) | `crates/kv-wasm/build.sh` builds a WebAssembly package (`kestrove-web` keeps a copy) |
+| Server (`kestrove-server`) | Uses only the shared message formats (`kv-proto`); it never handles secrets |
+
+Keep the repositories **side by side in one folder** (`kestrove-core`, `kestrove-apple`, …): the apps find
+the core by that relative path.
+
+## Build and test
+
+You need Rust (install it once from [rustup.rs](https://rustup.rs)):
 
 ```bash
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # once
-cargo test --workspace
+cargo test --workspace --all-features     # every test
+cargo clippy --workspace --all-targets --all-features
 ```
 
-## Bindings
+**Build for the apps:**
 
 ```bash
-./scripts/build-apple.sh     # → ../kestrove-apple/Packages/KestroveCore (XCFramework + Swift)
-./scripts/build-android.sh   # → ../kestrove-android/core-ffi (jniLibs + Kotlin); needs cargo-ndk
+./scripts/build-apple.sh       # → ../kestrove-apple/Packages/KestroveCore  (needs Xcode)
+ANDROID_NDK_HOME=~/Library/Android/sdk/ndk/27.3.13750724 ./scripts/build-android.sh
+                               # → ../kestrove-android/core-ffi            (needs the Android NDK and cargo-ndk)
+(cd ../kestrove-web && scripts/vendor-core.sh)
+                               # → builds kv-wasm and copies it into the web vault (needs wasm-pack)
 ```
 
-The desktop (Tauri) app depends on `kv-ffi` directly as a Rust crate.
+Run these again after changing the core, so the apps pick up the change.
 
-## Test vectors and the live-server test
+**Test against a real server** (start a fresh local `kestrove-server` first; the test file explains how):
 
 ```bash
-cargo run -p kv-crypto --example gen-vectors   # writes crates/kv-crypto/tests/vectors and ../kestrove-spec/vectors
-cargo test -p kv-ffi --test live_server -- --ignored   # against a fresh local kestrove-server; see the test's docs
+cargo test -p kv-ffi --test live_server -- --ignored
 ```
 
-## Rules
-* No `unsafe` outside generated FFI glue.
-* Secrets live in `Zeroizing<_>`. Never log, `Debug`-print or `format!` a secret.
-* Any change to formats needs a spec change first and new vectors in `kestrove-spec/vectors`.
-* `cargo deny check` must pass. There are no GPL dependencies (App Store).
+## What's inside
+
+| Crate | What it does |
+|---|---|
+| `kv-crypto` | Keys and encryption: turning the master password and Secret Key into keys (Argon2id), sealing every item (XChaCha20-Poly1305), sealing vault keys for devices (HPKE), signatures (Ed25519). |
+| `kv-model` | Vault items and what's in them, website matching (which login belongs to which site), one-time codes (TOTP), passkey signing (WebAuthn), the password generator. |
+| `kv-store` | The encrypted copy of the vault kept on each device (SQLite). It stores only ciphertext. |
+| `kv-sync` | Talking to the server: login without sending the password (OPAQUE), signed requests, pulling and pushing changes, merging edits from two devices, and a signed summary that catches a server hiding or rolling back data. |
+| `kv-proto` | The message formats shared with the server. No secrets. |
+| `kv-ffi` | The one API every app calls (`VaultCore`): create an account, unlock, read and save items, passkeys, sync, add devices. Also the browser bridge that the Mac and desktop apps use to answer the browser extension. |
+| `kv-wasm` | The same API for the web vault, as WebAssembly in a Web Worker. |
+| `kv-import` | Import from 1Password (`.1pux`) and CSV, and passphrase-encrypted export (`.kvex`). |
+| `kv-ipc`, `kv-nmh` | The small helper (`kestrove-nmh`) that browsers start to reach the Kestrove app, and its local connection to the app. |
+
+The design behind all this, with the reasons, is in
+[`kestrove-spec`](https://gitea.samialabri.com/kestrove/kestrove-spec): start with `docs/02-cryptography.md`
+and `docs/03-sync-protocol.md`.
+
+## Rules for changes
+
+- No `unsafe` code outside the generated bindings.
+- Secrets are kept in `Zeroizing<…>` so they're wiped from memory, and are never logged or printed.
+- Changing a stored or transmitted format? Change the spec first, then add test vectors to
+  `kestrove-spec/vectors` (`cargo run -p kv-crypto --example gen-vectors` writes them).
+- No GPL dependencies (the apps go to the App Store); `cargo deny check` must pass.