diff --git a/README.md b/README.md
index 7e59edb..df6649c 100644
--- a/README.md
+++ b/README.md
@@ -16,9 +16,12 @@ A modern, dark-mode-first MongoDB GUI. Built as a daily-driver alternative to Mo
 
 - **Multiple connections, side-by-side.** Connect to as many clusters as you want; each runs an independent pool. Drag-reorder them in the sidebar, manage them with right-click context menus.
 - **Built-in SSH tunnelling.** Point a connection at a cluster that is only reachable from a jump host — key, password or agent auth, no external port forwards. Because the tunnel is a dynamic SOCKS5 proxy rather than a single forwarded port, the driver reaches **every replica-set member** it discovers, resolved on the SSH server's side.
-- **Three query modes per tab.** Switch a single tab between **Simple** (filter / projection / sort), **Aggregation** pipeline, and **Shell** (`db.coll.find().limit()` syntax) without losing state.
+- **Cloudflare Access tunnels.** For a MongoDB published through Cloudflare Access, MongoBench runs `cloudflared access tcp` itself on a free loopback port and connects through it — sign in with your browser or a service token, no local port to pick or forward.
+- **Several tabs per collection, with drafts.** Open the same collection as often as you like. Each tab switches between **Simple** (filter / projection / sort), **Aggregation** pipeline and **Shell** (mongosh syntax for reads like `db.coll.find().limit()` and writes like `updateMany`); edits stay drafts until you run them, and every mode keeps its own last result.
+- **Schema-aware completion.** Suggestions come from a sample of the collection: field paths with their types and common values, operators that fit the field, pipeline stages that know which fields the previous stages produce, and shell methods.
 - **Mongo shell syntax everywhere.** Type `ObjectId("…")`, `ISODate("…")`, `UUID("…")`, `NumberLong("…")` etc. directly in filters and editors — MongoBench parses it into canonical EJSON before sending.
-- **Optimistic concurrency on writes.** Every edit and delete includes a sha-256 hash precondition of the document; concurrent edits surface as conflicts instead of silently overwriting.
+- **Numeric types stay exact.** Int32, Int64, Double and Decimal128 values keep their BSON type through view, edit and save — `5.0` stays a double, `NumberLong("5")` stays a long, `NaN` and `-0.0` survive.
+- **Optimistic concurrency on document edits.** Every edit and delete of a single document includes a sha-256 hash precondition of the document; concurrent edits surface as conflicts instead of silently overwriting.
 - **Built-in observability.** Per-connection dashboard with op rate, read/write/command latency, connection pool state, cache fill, network throughput, and a per-database storage breakdown.
 - **Updates you decide on.** MongoBench tells you when a newer release exists and shows the download progress, but nothing is fetched or installed until you click. Builds are unsigned — the app never replaces its own binary behind your back.
 
@@ -32,7 +35,7 @@ Saved connections at a glance with quick-connect buttons and inline tips.
 
 ### Connection form
 
-Full driver-option surface — auth, SSH tunnel, topology, pool, timeouts, UUID encoding, display timezone.
+Full driver-option surface — auth, SSH or Cloudflare Access tunnel, topology, pool, timeouts, UUID encoding, display timezone.
 
 ![New connection dialog](https://i.masel.io/ZIXO8/huKuWAvE28.png/raw)
 
@@ -62,20 +65,20 @@ Monaco editor with mongo shell helpers (`ObjectId(…)`, `ISODate(…)`, `Number
 
 ### Query autocomplete
 
-Operator autocomplete (`$eq`, `$in`, `$elemMatch`, `$geoWithin`, …) and field-name autocomplete from the most recent results.
+Operator autocomplete (`$eq`, `$in`, `$elemMatch`, `$geoWithin`, …) ranked by the field's type, and field-name autocomplete from a sample of the collection.
 
 ![Operator autocomplete](https://i.masel.io/ZIXO8/mIhavoWU58.png/raw)
 ![Field-name autocomplete](https://i.masel.io/ZIXO8/KiTUxUkA81.png/raw)
 
 ### Indexes
 
-Per-collection index manager — list with key spec, properties, size; create with full option surface (TTL, partial filter, collation, weights, 2dsphere, wildcard).
+Per-collection index manager — list with key spec, properties, size and usage; create with full option surface (TTL, partial filter, collation, weights, 2dsphere, wildcard).
 
 ![Indexes dialog](https://i.masel.io/ZIXO8/ZuzImILI62.png/raw)
 
 ### Users
 
-Per-database user management. Common-role shortcuts plus arbitrary custom roles.
+Per-database user management. A role editor for any role on any database, with one-click toggles for the common roles.
 
 ![Manage users](https://i.masel.io/ZIXO8/royEDozi90.png/raw)
 ![New user dialog](https://i.masel.io/ZIXO8/codOjUZU83.png/raw)
@@ -98,9 +101,16 @@ Per-database user management. Common-role shortcuts plus arbitrary custom roles.
   - Auth via **private key** (+ passphrase), **password**, or the running **SSH agent**
   - Key files are referenced by path — the key is read at connect time and never stored or copied
   - Passwords and passphrases go into the same OS keystore as the MongoDB password
-  - Host keys are checked against your `~/.ssh/known_hosts`; an unknown host is pinned on first use and its `SHA256:` fingerprint surfaced for you to verify. A key that later changes is a hard failure
+  - Host keys are checked against your `~/.ssh/known_hosts`; an unknown host is pinned on first use and its `SHA256:` fingerprint surfaced for you to verify. A key that later changes is a hard failure, and so is a key your `known_hosts` marks `@revoked`
   - Implemented as a loopback SOCKS5 proxy over the SSH session (with per-tunnel random credentials), handed to the driver as `proxyHost` / `proxyPort` — so **topology discovery works**: list every replica-set member in the URI under the names the SSH server resolves. `mongodb+srv://` is the exception, as its DNS lookup still happens locally
   - A tunnel that dies takes its connection down and says so, instead of leaving a connection that only looks alive
+- **Cloudflare Access tunnel** per connection, for a MongoDB behind a Cloudflare Access TCP application (**Tunnel → Cloudflare Access** in the form):
+  - MongoBench starts `cloudflared access tcp` on a free loopback port when you connect and stops it when you disconnect — there is no host or port to enter, only the Access hostname
+  - Auth via **browser sign-in** or a **service token**. For browser sign-in, cloudflared opens the browser only when it has no valid Access session and reuses the session until it expires; a toast explains the browser window and can reopen the sign-in page. A service token's secret goes into the OS keystore and reaches cloudflared through its environment, never its command line. A saved secret is only used for the hostname and client ID it was saved with; change either and the form asks for the secret again
+  - Uses `cloudflared` from `PATH` or an executable you pick; the form shows the detected version. A picked executable must be a file on this computer named like a cloudflared release (`cloudflared`, `cloudflared.exe`, `cloudflared-linux-amd64`, …); network and UNC paths are refused
+  - The tunnel reaches exactly one server, so `directConnection` is always on and `mongodb+srv://` is not supported. The connection string still carries credentials, database and options, but its host is never dialled — with TLS on, it names the certificate to expect. Choosing the tunnel fills an empty connection string with `mongodb://localhost`
+  - cloudflared's own error (e.g. a rejected service token) is reported instead of a driver timeout, and a cloudflared that exits takes its connection down
+  - While connected, the loopback port is reachable by other local processes; MongoDB authentication still applies
 - **Drag-to-reorder** saved connections in the sidebar
 - **Right-click context menu** per connection: connect / disconnect, edit, delete, new database, refresh, copy URI
 - Full driver option surface, persisted per connection:
@@ -117,33 +127,71 @@ Per-database user management. Common-role shortcuts plus arbitrary custom roles.
 - Three-level tree: **connection → database → collection**
 - Live status dot per connection (connected / disconnected / busy)
 - Right-click on a **database**: new collection, manage users, drop, copy name
-- Right-click on a **collection**: open, info, copy namespace, insert document, manage indexes, rename, drop
+- Right-click on a **collection**: open, open in new tab, info, copy namespace, insert document, manage indexes, rename, drop
 - Distinct icons for **collections vs. views**
 - Hover-quick-create buttons on database rows
 - Active tab is highlighted in the sidebar; opening a tab from the palette auto-expands and scrolls to the row
 
-### Query modes
+### Tabs
+
+- Clicking a collection focuses its most recently used tab, or opens one; **`Ctrl`/`Cmd`-click**, **middle-click** or **Open in new tab** opens another tab of the same collection
+- Tabs of one collection are numbered `#1`, `#2`, …; right-click a tab to **duplicate** or **close** it, middle-click closes it
+- Every tab keeps its own editors — text, cursor, scroll position and undo history survive tab and mode switches
+- Edits are drafts: nothing runs until you press **Run**, and a dot on the tab marks a draft that differs from its last run
+- **Duplicate** copies the drafts and the Simple result; Aggregation and Shell start idle in the copy, so an expensive pipeline doesn't run twice
+- ObjectId lookups open the referenced document in a new tab, or re-run an earlier lookup tab you haven't edited
+- Tabs follow a collection rename (an Aggregation result is cleared and waits for **Run** under the new name) and close when their collection or database is dropped or their connection disconnects; cached results of that namespace are discarded, so nothing stale comes back
 
-| Mode            | Surface                                   | Highlights                                                                                                             |
-| --------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Simple**      | filter · projection · sort · skip · limit | EJSON or shell syntax, field-name autocomplete from last results                                                       |
-| **Aggregation** | pipeline as `[{ $match: … }, …]`          | Monaco, full operator autocomplete                                                                                     |
-| **Shell**       | `db.coll.find({…}).sort({…}).limit(n)`    | Curated subset of mongosh syntax — `find`, `findOne`, `aggregate`, `count`, `countDocuments`, `estimatedDocumentCount` |
+### Query modes
 
-- **Run:** click button or `Ctrl+Enter` / `Cmd+Enter`
-- **Format:** `Shift+Alt+F` — custom formatter that preserves shell helpers
-- **Operator autocomplete** for every standard query operator (`$eq`, `$in`, `$elemMatch`, `$geoWithin`, `$jsonSchema`, …)
+| Mode            | Surface                                | Highlights                                                                                                                                                                                             |
+| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Simple**      | filter · projection · sort · limit     | EJSON or shell syntax; paged, with the total document count (estimated for an empty filter, _count unavailable_ with the reason when the server can't count the filter, e.g. `$where`)                 |
+| **Aggregation** | pipeline as `[{ $match: … }, …]`       | Read-only pipelines — `$out` / `$merge` are rejected (they run in Shell), and so is `$changeStream`, which never ends; at most 1,000 rows                                                              |
+| **Shell**       | `db.coll.find({…}).sort({…}).limit(n)` | Reads and writes on any collection of the database — `find`, `findOne`, `aggregate`, `countDocuments`, `count`, `estimatedDocumentCount`, `distinct` (at most 1,000 rows), and the write methods below |
+
+- **Run:** click button or `Ctrl+Enter` / `Cmd+Enter`. When the input can't run (invalid filter, empty pipeline), the Run tooltip says why
+- **Cancel:** while a query runs, Run turns into Cancel — it aborts the operation on the server and the result area shows _Run cancelled_; a cancelled run starts again only when you press Run. In Simple mode a total count that is still loading never blocks Run. Closing a tab aborts its running queries as well, unless a duplicate of the tab still shows them. A Shell write can't be cancelled — the driver has no way to abort a write — so while one runs, the button shows _Writing…_
+- **Switching modes never runs anything:** each mode shows its own last result; Aggregation and Shell show an example until their first run in that tab
+- **Result cap:** Aggregation and Shell reads show at most 1,000 rows; the status bar flags a truncated result and how to reach the rest (`$skip` / `$limit` stages, `.skip()` / `.limit()`, or a narrower `distinct` filter). Simple mode keeps its own limit and pager — an empty or 0 limit fetches every match
+- **Shell:** address any collection as `db.name`, `db.a.b`, `db["name"]` or `db.getCollection("name")`; chain `sort`, `skip`, `limit`, `projection`, `toArray`, `pretty` after `find`, where `.limit(0)` means no limit. Comments and a trailing `;` are fine. Counts show as one large number — `count()` on an empty filter is estimated from collection metadata, like in mongosh; `countDocuments()` is always exact
+- **Shell writes:** `insertOne`, `insertMany`, `updateOne`, `updateMany` (update operators or an update pipeline), `replaceOne`, `deleteOne`, `deleteMany`, `findOneAndUpdate`, `findOneAndReplace`, `findOneAndDelete`, `bulkWrite`, and `aggregate` ending in `$out` / `$merge` (into any collection, also of another database), each with mongosh's options (`upsert`, `arrayFilters`, `hint`, `collation`, `returnDocument` / `returnNewDocument`, …). When the command writes, Run turns amber and its tooltip names the collection it writes to
+  - A write runs exactly once, when you press Run — holding `Ctrl+Enter`, a double-click on Run, switching tabs or modes, or a refresh after another write never repeats it
+  - `updateMany` / `deleteMany` with an empty filter (also inside `bulkWrite`) and a `$out` ask for confirmation first
+  - The result shows the counts that apply (inserted, matched, modified, upserted, deleted), the inserted or upserted `_id`s, where `$out` / `$merge` wrote, and the document a `findOneAnd*` returned — Edit, Duplicate and Delete load the stored document first; a deleted one is read-only
+  - Afterwards the written collection's results, its stats and the collection list refresh — after a failed write too, since an ordered `insertMany` or `bulkWrite` may have written part
+  - The legacy `insert`, `update`, `remove`, `save` and `findAndModify` name their modern replacement; `drop`, index and rename commands point to the explorer
+- **Format:** `Shift+Alt+F` — re-prints filters, pipelines and shell commands, keeping shell helpers (comments are dropped)
+
+### Completion
+
+- Field suggestions come from a random sample of up to 200 documents, taken when an editor gets focus and reused for 10 minutes; **Refresh Field Suggestions** in the editor's context menu samples again. Unprojected documents of the current result are folded in
+- Keys suggest field paths ranked by how often they occur, with their types; values suggest the matching constructor (`ObjectId("…")`, `ISODate("…")` in the connection's timezone, `NumberLong("…")`, …) and the field's most common values
+- Operators are ranked by the field's type — `$regex` for strings, `$size` / `$elemMatch` for arrays, geo operators for coordinates
+- Pipelines: stage names and templates, the fields each stage produces (`$group`, `$project`, `$unwind`, `$lookup`, …), expression operators with their named arguments, fields ranked by the type an argument expects, and `$$` variables with the subfields they hold. `$lookup` and `$unionWith` suggest collection names and know the target collection's fields
+- Shell: collections of the database (as `getCollection("…")` when `db.name` can't reach them), collection methods and cursor methods, and the arguments of write methods — update operators, update pipeline stages, option names and `bulkWrite` operations
+- Document editor: keys and values from the same sample; suggestions open only on trigger characters or `Ctrl+Space`, so `Enter` still starts a new line. The index form suggests key fields from the same sample
+- Word-based suggestions are off, so text from other tabs never shows up
 
 ### Documents
 
 - Auto-sized table columns, drag-to-resize, per-collection persistence
 - Multi-select with `Shift+Click` range select
-- Right-click row: **view, edit, duplicate, delete, copy `_id`, jump to referenced ObjectId** (cross-collection lookup submenu)
+- Right-click row: **view, edit, duplicate, delete, copy as canonical EJSON, jump to referenced ObjectId** (cross-collection lookup submenu)
+- **Row actions follow the result:**
+  - Whole documents — Simple or shell `find` / `findOne` without projection, pipelines of only `$match` / `$sort` / `$skip` / `$limit` — are edited and deleted directly
+  - Projected rows are partial, so Edit, Duplicate and Delete first load the stored document by `_id`
+  - Rows of other pipelines, `distinct` values and rows without `_id` are read-only: View, Copy and ObjectId lookups
 - **View / edit modes:**
-  - Canonical EJSON (`{ "$oid": "…" }`, `{ "$date": "…" }`, …) or relaxed display
+  - Documents open in mongo shell syntax built from canonical EJSON (`ObjectId("…")`, `ISODate("…")`, `NumberLong("…")`, …)
   - Shell-syntax accepted on input, parsed before send
   - sha-256 hash precondition on `replaceOne` / `deleteOne` to catch concurrent edits
+  - **Exact numeric types:** documents are read without promoting BSON numbers, so a save writes back what was stored — Int32 as `NumberInt(…)`, Int64 as `NumberLong("…")`, Double as `5.0` / `2.5` / `-0.0` / `NumberDouble("NaN")`, Decimal128 as `NumberDecimal("…")`
+  - Regular expressions keep their exact pattern and flags, including `s`, `x` and `u`
+  - On input, a plain integer becomes Int32 (Int64 when larger) and a literal with a `.` or an exponent (`5.0`, `1e3`) a Double; `Double(…)` / `NumberDouble(…)` also take `"NaN"`, `"Infinity"` and `"-Infinity"`. `ObjectId()` without arguments creates a fresh id
 - **Bulk delete** via multi-select + confirm
+- After any write — from the table, the editor or the Shell — the visible result refreshes if it may read that collection — Simple, Aggregation, or a Shell command on that database. A hidden Simple result refreshes when you show it again; a hidden Aggregation or Shell result keeps its last data until you press **Run**
+- A multi-document insert that fails part-way reports how many documents were already inserted
 - **Export** the current result set as JSON, CSV or TSV
 - **Type-aware rendering** in the table:
   - `ObjectId` as hex string with kind badge
@@ -155,15 +203,23 @@ Per-database user management. Common-role shortcuts plus arbitrary custom roles.
 ### Indexes
 
 - List with name, key spec, type (1/-1/text/2dsphere/2d/hashed), TTL, uniqueness, sparseness, hidden flag, partial filter, collation, weights
-- Create with full option surface: `unique`, `sparse`, `hidden`, `expireAfterSeconds`, `partialFilterExpression`, `collation`, `weights`, `default_language`, `language_override`, `textIndexVersion`, `2dsphereIndexVersion`, `bits`, `min`, `max`, `wildcardProjection`
+- Create with full option surface: `unique`, `sparse`, `hidden`, `expireAfterSeconds`, `partialFilterExpression`, `collation`, `weights`, `default_language`, `language_override`, `textIndexVersion`, `2dsphereIndexVersion`, `bits`, `min`, `max`, `wildcardProjection`; key fields are suggested from a sample of the collection
 - Drop with confirmation (`_id` index protected)
-- Per-index size from `collStats`
+- **Size** and **Usage** columns, both sortable:
+  - Size per index from `$collStats`, summed across shards
+  - Usage from `$indexStats`: operations since the counters started, with a per-day rate; hover for the start date and the count per host
+  - An index with no recorded use for at least a day is flagged **unused** (never `_id_`, hidden, TTL or still-building indexes); indexes still being built carry a **building** badge
+  - Counters reset when a mongod restarts; a note under the table names the hosts and shards they were counted on
+- Statistics load when the dialog opens and are never polled; **Refresh** reloads them. When a source needs a privilege you don't have (`indexStats`, `collStats`), a notice says so and the rest still shows
 
 ### Users
 
 - List per-database users with their roles
-- Create with username, password, role assignments per database
-- Common-role shortcuts: `read`, `readWrite`, `dbAdmin`, `dbOwner`, `userAdmin` — plus arbitrary custom roles
+- Create with username, password (with a generator) and roles
+- **Role editor:** any role on any database
+  - Suggestions from the server's roles (built-in and custom), the roles of listed users and the known databases
+  - One-click toggles for `read`, `readWrite`, `dbAdmin`, `dbOwner`, `userAdmin` on the current database
+  - Roles grouped per database and filterable; while editing, added and removed roles stay marked until you save, and a removed role can be restored
 - Update password and / or roles independently (preserve unchanged fields)
 - Drop with confirmation
 
@@ -171,7 +227,7 @@ Per-database user management. Common-role shortcuts plus arbitrary custom roles.
 
 - Create / drop database (with confirmation, closes affected tabs)
 - Create / rename / drop collection
-- **Collection info dialog**: namespace, document count, average doc size, storage size (compressed + uncompressed), index count, free space, capped status
+- **Collection info dialog**: namespace, document count, average doc size, storage size (compressed + uncompressed), index count, free space, capped status — summed across shards on sharded clusters
 
 ### Connection dashboard
 
@@ -198,6 +254,7 @@ Per-connection live view, sampled every 5 s, sliding 5-min history:
 - Custom **Monaco theme** matching the app palette
 - **Custom scrollbars** (Chromium): 10 px, transparent track, primary-tinted on grab
 - **Status indicators** everywhere: spinners on pending operations, success / error toasts, hash-protected badges in the status bar
+- **Escape** inside a dialog first closes the innermost popup — suggestion list, editor find widget, dropdown — and only then the dialog
 
 ## Install
 
@@ -271,7 +328,13 @@ src/
 
 - Builds are **unsigned** — Windows shows SmartScreen on first launch
 - No **change-streams / live tail** UI yet
-- Shell mode parses a curated subset of `db.coll.<op>(...)` syntax, not the full mongosh grammar
+- Shell mode runs one command per run — the reads and writes listed above, not the full mongosh grammar: no variables or JavaScript, no legacy write methods, no collection or index administration (the explorer does that)
+- Shell writes can't be cancelled once they run, and they carry no hash precondition: they act on whatever matches when they run
+- Aggregation and Shell reads stop at 1,000 rows; page with `$skip` / `$limit` or `.skip()` / `.limit()`. A write result lists at most 1,000 inserted or upserted `_id`s
+- **Cancel** stops waiting for `distinct` and `estimatedDocumentCount`, but cannot abort them on the server
+- `distinct` shows Int32 and Double values as plain numbers, so it doesn't tell them apart (Int64 values stay exact); queried documents always keep their exact types
+- The document a `findOneAnd*` returns may show an integral Double as an Int32 (Int64 values and regular expressions stay exact); editing it starts from the stored document, so no type changes on save. View and Copy show it as returned, so a copied `findOneAndDelete` result is not a type-exact backup of the deleted document
+- A Cloudflare Access tunnel reaches a single server: no replica-set discovery, no `mongodb+srv://`
 - macOS builds aren't published (the codebase runs on macOS in dev; binaries just aren't in the release matrix yet)
 
 ## License
diff --git a/package-lock.json b/package-lock.json
index 048a699..b6b1fbf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mongobench",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mongobench",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "license": "MIT",
       "dependencies": {
         "@fontsource-variable/geist": "^5.2.8",
@@ -64,7 +64,7 @@
         "tailwindcss-animate": "^1.0.7",
         "typescript": "^5.6.2",
         "vite": "^7.0.0",
-        "vitest": "^4.0.0"
+        "vitest": "^4.1.12"
       },
       "engines": {
         "node": ">=20"
@@ -437,9 +437,9 @@
       "license": "MIT"
     },
     "node_modules/@electron/asar/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -579,9 +579,9 @@
       }
     },
     "node_modules/@electron/rebuild": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/@electron/rebuild/-/rebuild-4.2.0.tgz",
-      "integrity": "sha512-RKL/O+jGoXJMxrx/5771y1n0xTKmFuOYGO3gMmwypBM6rsH0kou0mswwdXA2JrhIkE4xyC7v9vGk0n6NPzgOxQ==",
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/@electron/rebuild/-/rebuild-4.2.1.tgz",
+      "integrity": "sha512-IS4pG3BysRrCLJ8xTAfvg+IQDbiUoAzdJy2SfjcYKnLDy5DpCdjnPdhS5Zf5UMfrkB24xu0KC+TqcOxg+eG+6w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -626,9 +626,9 @@
       "license": "MIT"
     },
     "node_modules/@electron/universal/node_modules/brace-expansion": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
-      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
+      "version": "2.1.7",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.7.tgz",
+      "integrity": "sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -636,9 +636,9 @@
       }
     },
     "node_modules/@electron/universal/node_modules/fs-extra": {
-      "version": "11.4.0",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.0.tgz",
-      "integrity": "sha512-EQsFzMUJkCKGr1ePqlYADkIUmHW1s3ZXr5Yqy6wbGrfUCphpl2maM/kyOIRA2HpP3AaFQTZXD4ldjek+nccddA==",
+      "version": "11.4.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.1.tgz",
+      "integrity": "sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -689,9 +689,9 @@
       }
     },
     "node_modules/@electron/windows-sign/node_modules/fs-extra": {
-      "version": "11.4.0",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.0.tgz",
-      "integrity": "sha512-EQsFzMUJkCKGr1ePqlYADkIUmHW1s3ZXr5Yqy6wbGrfUCphpl2maM/kyOIRA2HpP3AaFQTZXD4ldjek+nccddA==",
+      "version": "11.4.1",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.4.1.tgz",
+      "integrity": "sha512-KYAb4c9BJQI6QqGKthV68OHe0badztdXJWKo0WtBA9IuCFPTKvE5ZdUBglP833aMjhaSPNO4A5j/EkzZtGlKjA==",
       "dev": true,
       "license": "MIT",
       "optional": true,
@@ -1225,9 +1225,9 @@
       "license": "MIT"
     },
     "node_modules/@eslint/eslintrc/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1346,9 +1346,9 @@
       "license": "MIT"
     },
     "node_modules/@humanwhocodes/config-array/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1562,13 +1562,13 @@
       }
     },
     "node_modules/@noble/hashes": {
-      "version": "2.3.0",
-      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-2.3.0.tgz",
-      "integrity": "sha512-oN+QwyX7VSHotibwubG3kpzbwKrfnyR6OOO+3Nk/53ADL7FmgHHz4TgrbaYKvvOw09u6QTx0oiH1cNCIOuN0CQ==",
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
       "dev": true,
       "license": "MIT",
       "engines": {
-        "node": ">= 20.19.0"
+        "node": "^14.21.3 || >=16"
       },
       "funding": {
         "url": "https://paulmillr.com/funding/"
@@ -1613,15 +1613,18 @@
       }
     },
     "node_modules/@peculiar/asn1-schema": {
-      "version": "2.8.0",
-      "resolved": "https://registry.npmjs.org/@peculiar/asn1-schema/-/asn1-schema-2.8.0.tgz",
-      "integrity": "sha512-7YT0U/ze0tF2QOBbE15gKZwy5tvgGyLRiRHLzhlbOpf7BT032oBSd0haZqXn5W6l26WLlu3dyxzjM+2638/z2Q==",
+      "version": "2.11.0",
+      "resolved": "https://registry.npmjs.org/@peculiar/asn1-schema/-/asn1-schema-2.11.0.tgz",
+      "integrity": "sha512-8xh4avo53/vXO6UEv9yaoJ83hY581geaLTygf61NPIXP5AeIZCPjJhpTaYU23IZkG+NpLN/C9FYzWp7hphIT9A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@peculiar/utils": "^2.0.2",
         "asn1js": "^3.0.10",
         "tslib": "^2.8.1"
+      },
+      "engines": {
+        "node": ">=14"
       }
     },
     "node_modules/@peculiar/json-schema": {
@@ -3375,16 +3378,16 @@
       }
     },
     "node_modules/@vitest/expect": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.10.tgz",
-      "integrity": "sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.12.tgz",
+      "integrity": "sha512-vFlTt+YEu9WBpNjdGayNmlMVzrWPi1+sv853/7t2FU7hpO5gAFBKHzQmkCq5Xjpr+evegF2994LQT3hF3mRlqQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@standard-schema/spec": "^1.1.0",
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/spy": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "chai": "^6.2.2",
         "tinyrainbow": "^3.1.0"
       },
@@ -3393,13 +3396,13 @@
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.10.tgz",
-      "integrity": "sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.12.tgz",
+      "integrity": "sha512-fKShNpKZzupWZuY0z7egydvL0sqW4INEZBEExMBMAa6izlENEVHwoXgdaTCaBZ5fwlr4xf2o1wXC83n9RpO+NA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "4.1.10",
+        "@vitest/spy": "4.1.12",
         "estree-walker": "^3.0.3",
         "magic-string": "^0.30.21"
       },
@@ -3420,9 +3423,9 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.10.tgz",
-      "integrity": "sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.12.tgz",
+      "integrity": "sha512-XW9O8+Mxx4VpCtkYdMJLZQQwsVryP9wk7cPKDxtXFfwSak6yRh5+2fep/Y0XF/ElBvJHq8bcYdi6aeuai0opZA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3433,13 +3436,13 @@
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.10.tgz",
-      "integrity": "sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.12.tgz",
+      "integrity": "sha512-NKlVKCr5QnCe8jijdMnmkpHHU+WTqiLFR6G0pHji9uRjXK9xJl1k1nTw6F3pOOj2PDcsDt2GKQMI7wIsaT491w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "4.1.10",
+        "@vitest/utils": "4.1.12",
         "pathe": "^2.0.3"
       },
       "funding": {
@@ -3447,14 +3450,14 @@
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.10.tgz",
-      "integrity": "sha512-xRkfOT1qpTAi/Ti4Y1LtfRc3kEuqxGw59eN2jN9pRWMtS/XDevekhcFSqvQqjUNGksfjMJu3Y+oJ+4Ypn2OaJw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.12.tgz",
+      "integrity": "sha512-ko1y1Qgb/slzQ9mr+b89Cuqud8WG1TKtsPD8r7ZUBdvVOGt85Af2HwCqHujrhwJq95hs/9RM7fcAPg57o1vlzw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/pretty-format": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "magic-string": "^0.30.21",
         "pathe": "^2.0.3"
       },
@@ -3463,9 +3466,9 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.10.tgz",
-      "integrity": "sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.12.tgz",
+      "integrity": "sha512-RGq9x4JNGNTZHEJxvN0oSiJjeSCExm0n2gZKKJZHY9cX5AVA6M7VJILBT3ZJ/tJ/0J9uWT7fETV9/btoi//vSg==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -3473,13 +3476,13 @@
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.10.tgz",
-      "integrity": "sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.12.tgz",
+      "integrity": "sha512-Q3awXrwOfEV+qc3WmO5ONyE0yO7Q1gQ9/oyHxGLZ/pl7N3NO/ZztqQwKLuwMkV+CA1JYSIeO3gkHnRDIo4AVaA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.10",
+        "@vitest/pretty-format": "4.1.12",
         "convert-source-map": "^2.0.0",
         "tinyrainbow": "^3.1.0"
       },
@@ -3488,9 +3491,9 @@
       }
     },
     "node_modules/@xmldom/xmldom": {
-      "version": "0.8.13",
-      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.13.tgz",
-      "integrity": "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw==",
+      "version": "0.8.15",
+      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.15.tgz",
+      "integrity": "sha512-/5NV/vDALVFDXgLmfsy9TRCBlKwO2LNBFzpzvb9iIj+jR+eSc6DLYYvVOdivT/jm7MtU6TebYuRmzEOI7w40UA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -3621,9 +3624,9 @@
       }
     },
     "node_modules/app-builder-lib": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/app-builder-lib/-/app-builder-lib-26.15.3.tgz",
-      "integrity": "sha512-2VnyWkqsP5v5XbBhL3tD5Syx8iNPBYsoU7kY4S2fz7wg8Rj/nztWKCUzGKaFRTv0Xwf3/H058CR1Kvtd/3lRow==",
+      "version": "26.17.0",
+      "resolved": "https://registry.npmjs.org/app-builder-lib/-/app-builder-lib-26.17.0.tgz",
+      "integrity": "sha512-wfL7EhujuODDW3uMSD8RPcr/MLzmT0dmpVfWV0wFUWXI0rIdaukzAJ7EFUSyHXOpxuBZqaIGlQt6VeQhtHhetw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3635,13 +3638,13 @@
         "@electron/rebuild": "^4.0.4",
         "@electron/universal": "2.0.3",
         "@malept/flatpak-bundler": "^0.4.0",
-        "@noble/hashes": "^2.2.0",
+        "@noble/hashes": "^1.8.0",
         "@peculiar/webcrypto": "^1.7.1",
         "@types/fs-extra": "9.0.13",
         "ajv": "^8.18.0",
         "asn1js": "^3.0.10",
         "async-exit-hook": "^2.0.1",
-        "builder-util": "26.15.3",
+        "builder-util": "26.16.0",
         "builder-util-runtime": "9.7.0",
         "chromium-pickle-js": "^0.2.0",
         "ci-info": "4.3.1",
@@ -3649,7 +3652,7 @@
         "dotenv": "^16.4.5",
         "dotenv-expand": "^11.0.6",
         "ejs": "^3.1.8",
-        "electron-publish": "26.15.3",
+        "electron-publish": "26.16.0",
         "fs-extra": "^10.1.0",
         "hosted-git-info": "^4.1.0",
         "isbinaryfile": "^5.0.0",
@@ -3673,8 +3676,8 @@
         "node": ">=14.0.0"
       },
       "peerDependencies": {
-        "dmg-builder": "26.15.3",
-        "electron-builder-squirrel-windows": "26.15.3"
+        "dmg-builder": "26.17.0",
+        "electron-builder-squirrel-windows": "26.17.0"
       }
     },
     "node_modules/app-builder-lib/node_modules/@electron/get": {
@@ -3956,14 +3959,14 @@
       }
     },
     "node_modules/asn1js": {
-      "version": "3.0.10",
-      "resolved": "https://registry.npmjs.org/asn1js/-/asn1js-3.0.10.tgz",
-      "integrity": "sha512-S2s3aOytiKdFRdulw2qPE51MzjzVOisppcVv7jVFR+Kw0kxwvFrDcYA0h7Ndqbmj0HkMIXYWaoj7fli8kgx1eg==",
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/asn1js/-/asn1js-3.1.0.tgz",
+      "integrity": "sha512-HWYi1THkOqguCiO+vwj09ZkQFD2kKEsejYHAYCtX0D80WVdoDnvRc9IukXX/jeb0T9NRWJnRtqwdbHltnFjwXA==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "pvtsutils": "^1.3.6",
-        "pvutils": "^1.1.5",
+        "pvutils": "^1.2.0",
         "tslib": "^2.8.1"
       },
       "engines": {
@@ -4277,9 +4280,9 @@
       "optional": true
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.9",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
-      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
+      "version": "5.0.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
+      "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4362,9 +4365,9 @@
       }
     },
     "node_modules/builder-util": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/builder-util/-/builder-util-26.15.3.tgz",
-      "integrity": "sha512-q2hn7Mbo2nFNkVekPiHFx6Nfo3hURmES3tfBn+k5Pqxl2RkmP3QGqZUhH/q9Pch/4G05NRhPjDlVj1O8q4Txvw==",
+      "version": "26.16.0",
+      "resolved": "https://registry.npmjs.org/builder-util/-/builder-util-26.16.0.tgz",
+      "integrity": "sha512-RLyJhB7Si3YkzKR9ubQslWuXW3Vhs3CGe1i+SeixBZ0qTd1mk3XBmssvY22TlB6CS5blyko8Gu1JzpYk8UkYAg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4570,9 +4573,9 @@
       "license": "CC-BY-4.0"
     },
     "node_modules/chai": {
-      "version": "6.2.2",
-      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
-      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.3.0.tgz",
+      "integrity": "sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -5187,9 +5190,9 @@
       "license": "MIT"
     },
     "node_modules/dir-compare/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -5218,14 +5221,14 @@
       "license": "MIT"
     },
     "node_modules/dmg-builder": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/dmg-builder/-/dmg-builder-26.15.3.tgz",
-      "integrity": "sha512-O3zJUFUYHJKgzPqioHxfxzBzlSC1eXCSr79gMSBKBP5AgjjpmrydMsMLotEg9fAJF36vdUncb+4ndRNxoPdlSQ==",
+      "version": "26.17.0",
+      "resolved": "https://registry.npmjs.org/dmg-builder/-/dmg-builder-26.17.0.tgz",
+      "integrity": "sha512-EAw1f2iGkICmUvAVBOjm7v5mxJdB7/+OZSycHFhKBimiTkCXtvkCC6wBKzHo7ZQYi58C2MmwIleRbgRnROlK2Q==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "app-builder-lib": "26.15.3",
-        "builder-util": "26.15.3",
+        "app-builder-lib": "26.17.0",
+        "builder-util": "26.16.0",
         "fs-extra": "^10.1.0",
         "js-yaml": "^4.1.0"
       }
@@ -5244,9 +5247,9 @@
       }
     },
     "node_modules/dompurify": {
-      "version": "3.4.13",
-      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.13.tgz",
-      "integrity": "sha512-2vmYIoqjze2d+kakP8S/nS5shfsl587kzwEjcGlTdiksUVgFHnFCsLYDVj/JNqJVOQZGSYBTmuycv0PodwmnMQ==",
+      "version": "3.4.17",
+      "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.17.tgz",
+      "integrity": "sha512-B/pSlYVHQ58kqISD/yDjuJ1yfzI34m1gF4lAod2bwSRhiN4K5Cl3H8Af7hqB2PmTL911tdEudnnXn5FnhRoz0w==",
       "license": "(MPL-2.0 OR Apache-2.0)",
       "optionalDependencies": {
         "@types/trusted-types": "^2.0.7"
@@ -5323,9 +5326,9 @@
       }
     },
     "node_modules/electron": {
-      "version": "42.9.0",
-      "resolved": "https://registry.npmjs.org/electron/-/electron-42.9.0.tgz",
-      "integrity": "sha512-xyKfPbHP43Jx22Z1hItLR4KB5h3/avb5BIX4xaQZ6uPPRY4cQxuHnRVrKCGbSsMa/9zd0bBT4TAVNVuVjYcYtw==",
+      "version": "42.11.15",
+      "resolved": "https://registry.npmjs.org/electron/-/electron-42.11.15.tgz",
+      "integrity": "sha512-pZOe/Qga4o3t6q9WdL6hV0hYjjlcagJsSCFp3Zc4rxyqTYsIQr6macePGoQefXkdKFnsA4VvwqHjYxTUSiE3qA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -5342,18 +5345,18 @@
       }
     },
     "node_modules/electron-builder": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/electron-builder/-/electron-builder-26.15.3.tgz",
-      "integrity": "sha512-a1KM5heqS3gQCZzizXEI8RjJy3QVogULPdeSknt76uLDpBIW/HDGsMg/XgP0riP6PI9COsRvFITKKGDqA8fJxA==",
+      "version": "26.17.0",
+      "resolved": "https://registry.npmjs.org/electron-builder/-/electron-builder-26.17.0.tgz",
+      "integrity": "sha512-iYHBRiagS9sDIbZx1ZD113f5rEGQvtpvTvHf70ovHKJ8mRvxwIkWX7JCwfmVQmVS4eX735p7TZmoxHnBPwF3vA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "app-builder-lib": "26.15.3",
-        "builder-util": "26.15.3",
+        "app-builder-lib": "26.17.0",
+        "builder-util": "26.16.0",
         "builder-util-runtime": "9.7.0",
         "chalk": "^4.1.2",
         "ci-info": "^4.2.0",
-        "dmg-builder": "26.15.3",
+        "dmg-builder": "26.17.0",
         "fs-extra": "^10.1.0",
         "lazy-val": "^1.0.5",
         "simple-update-notifier": "2.0.0",
@@ -5368,15 +5371,15 @@
       }
     },
     "node_modules/electron-builder-squirrel-windows": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/electron-builder-squirrel-windows/-/electron-builder-squirrel-windows-26.15.3.tgz",
-      "integrity": "sha512-Jc19XPV9y9+2bAdZPkXuVNGNIEFBq9poHC61l8Kv6FdK7DRG3+Ic0rerC0DXOaeHNz8yW0fg/JnF8GQROOF5MA==",
+      "version": "26.17.0",
+      "resolved": "https://registry.npmjs.org/electron-builder-squirrel-windows/-/electron-builder-squirrel-windows-26.17.0.tgz",
+      "integrity": "sha512-uyh+D+B0m12qCRp9c/7dwBirHTh7JcvAzj5eTEbb4dXPPGAhYPx1nozzbu1fC6AdULfat6ZNqgWhipTFpb82lQ==",
       "dev": true,
       "license": "MIT",
       "peer": true,
       "dependencies": {
-        "app-builder-lib": "26.15.3",
-        "builder-util": "26.15.3",
+        "app-builder-lib": "26.17.0",
+        "builder-util": "26.16.0",
         "electron-winstaller": "5.4.0"
       }
     },
@@ -5390,15 +5393,15 @@
       }
     },
     "node_modules/electron-publish": {
-      "version": "26.15.3",
-      "resolved": "https://registry.npmjs.org/electron-publish/-/electron-publish-26.15.3.tgz",
-      "integrity": "sha512-g/2bn8YTavY4cuS5F+jOS7zmZbXXBV8KZ8yHKfJjFPoKtzBqrpCdNPxBd3tqdBwP7BVd0lGzf7Bk2s0KesWZ4Q==",
+      "version": "26.16.0",
+      "resolved": "https://registry.npmjs.org/electron-publish/-/electron-publish-26.16.0.tgz",
+      "integrity": "sha512-Vt3KzQIiw9BImvNOYtndg9Mjki+tl4+1sQiC/+G5j8khWaENOJFWodiB+sUl6yyHwtd37avehskdtPw7f8y/+Q==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@types/fs-extra": "^9.0.11",
         "aws4": "^1.13.2",
-        "builder-util": "26.15.3",
+        "builder-util": "26.16.0",
         "builder-util-runtime": "9.7.0",
         "chalk": "^4.1.2",
         "form-data": "^4.0.5",
@@ -5989,9 +5992,9 @@
       "license": "MIT"
     },
     "node_modules/eslint-plugin-react/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -6090,9 +6093,9 @@
       "license": "MIT"
     },
     "node_modules/eslint/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -6321,9 +6324,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
-      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "version": "3.1.8",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz",
+      "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==",
       "dev": true,
       "funding": [
         {
@@ -6378,9 +6381,9 @@
       "license": "MIT"
     },
     "node_modules/filelist/node_modules/brace-expansion": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.4.tgz",
-      "integrity": "sha512-hGfVzPxthbf3+2yjg/RBs60cB0FhqBS/zvdV/4wn4/BmN0bNMMHPc4V/BbFieqf1TKAGGAHnY4eSjajCl0f2Xg==",
+      "version": "2.1.7",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.7.tgz",
+      "integrity": "sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -6783,9 +6786,9 @@
       "license": "MIT"
     },
     "node_modules/glob/node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -7038,9 +7041,9 @@
       "license": "ISC"
     },
     "node_modules/http-cache-semantics": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
-      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.3.0.tgz",
+      "integrity": "sha512-M5t5LlJpS1UHMjvwRQVdFHvPISGeLAxNcrWuJkeGh0KxsqCHZ1O3NXZU/8x7cD0BDcGW8kapxMKTvwlqrNkHkA==",
       "dev": true,
       "license": "BSD-2-Clause"
     },
@@ -7184,9 +7187,9 @@
       }
     },
     "node_modules/ip-address": {
-      "version": "10.5.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.5.0.tgz",
-      "integrity": "sha512-R5SnVLJmgYYvf2F2ZgwSBnelz5G4q5AxIC277GDfUaNbrZKNANcBC7RHqYYePlszf4kBolVkJauG0ZjHHFh55g==",
+      "version": "10.7.4",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.4.tgz",
+      "integrity": "sha512-DWBMKyeM25D70nrIiTkgQth59/G+naKOTep6huF9j+GmeK3DMD60Zvxg5d5qQnz+38AHgou6ean2LECX+lrKDg==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -7732,9 +7735,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
       "funding": [
         {
           "type": "github",
@@ -8551,9 +8554,9 @@
       }
     },
     "node_modules/node-abi": {
-      "version": "4.33.0",
-      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-4.33.0.tgz",
-      "integrity": "sha512-vLBWCKb+7LWsX+TbfzWOkw0W81m377tyx3hOweBTjO43CXZnRGS1/JPWs20fr0PgZyDXk6ROYrylsEycK8raDA==",
+      "version": "4.38.0",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-4.38.0.tgz",
+      "integrity": "sha512-suSdznUPfabdaeLiNERA0LHod14RhcEn8wMPUZEQ6bKvajUCZ+aizY4pIvlLU+gImeLKp2bFDHhOc9yonISsXw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -8648,9 +8651,9 @@
       }
     },
     "node_modules/node-gyp/node_modules/undici": {
-      "version": "6.28.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-6.28.0.tgz",
-      "integrity": "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA==",
+      "version": "6.29.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.29.1.tgz",
+      "integrity": "sha512-EvRlUt/QqAEvXdQeRMYUfwOQsfzpDztykrG2owGEE/rBOBoYv9uF39ZzsNDh4lTFHhTr2XOZjKkYgueD12ZmGA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -9207,13 +9210,16 @@
       }
     },
     "node_modules/pkijs": {
-      "version": "3.4.0",
-      "resolved": "https://registry.npmjs.org/pkijs/-/pkijs-3.4.0.tgz",
-      "integrity": "sha512-emEcLuomt2j03vxD54giVB4SxTjnsqkU692xZOZXHDVoYyypEm+b3jpiTcc+Cf+myooc+/Ly0z01jqeNHVgJGw==",
+      "version": "3.4.1",
+      "resolved": "https://registry.npmjs.org/pkijs/-/pkijs-3.4.1.tgz",
+      "integrity": "sha512-Oo/NZcSWccq8KyoG7gLE9fnltgHns+pNCjCAp/WmjsUySi+sX7y4z4Xqu4fVb42CDHzRPl33fjzT15V1wvcyhA==",
       "dev": true,
       "license": "BSD-3-Clause",
+      "workspaces": [
+        "website"
+      ],
       "dependencies": {
-        "@noble/hashes": "1.4.0",
+        "@noble/hashes": "1.8.0",
         "asn1js": "^3.0.6",
         "bytestreamjs": "^2.0.1",
         "pvtsutils": "^1.3.6",
@@ -9224,19 +9230,6 @@
         "node": ">=16.0.0"
       }
     },
-    "node_modules/pkijs/node_modules/@noble/hashes": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.4.0.tgz",
-      "integrity": "sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">= 16"
-      },
-      "funding": {
-        "url": "https://paulmillr.com/funding/"
-      }
-    },
     "node_modules/plist": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/plist/-/plist-3.1.0.tgz",
@@ -10532,9 +10525,9 @@
       }
     },
     "node_modules/source-map-js": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
-      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
+      "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
@@ -11262,9 +11255,9 @@
       }
     },
     "node_modules/tinyrainbow": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.1.tgz",
-      "integrity": "sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==",
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.2.0.tgz",
+      "integrity": "sha512-LgO3D9yZJjApUiuUfl9iFAwrtaX4+lok3wJIqttGoKCHlWUqHqbQpnxCf82L8FjgKsh4iGo78hqJwgL8F6To2A==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -11496,9 +11489,9 @@
       }
     },
     "node_modules/undici": {
-      "version": "7.29.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.0.tgz",
-      "integrity": "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw==",
+      "version": "7.30.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz",
+      "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==",
       "dev": true,
       "license": "MIT",
       "optional": true,
@@ -12253,19 +12246,19 @@
       }
     },
     "node_modules/vitest": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.10.tgz",
-      "integrity": "sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw==",
+      "version": "4.1.12",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.12.tgz",
+      "integrity": "sha512-5eWdz2yb3ajxWF3C8C4TjkXl7FGm3n2E/VlazALrQHzK7nYMSGFnCZto0bbPNl77AwkOZVLk0YnBAejUu0NiWA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/expect": "4.1.10",
-        "@vitest/mocker": "4.1.10",
-        "@vitest/pretty-format": "4.1.10",
-        "@vitest/runner": "4.1.10",
-        "@vitest/snapshot": "4.1.10",
-        "@vitest/spy": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/expect": "4.1.12",
+        "@vitest/mocker": "4.1.12",
+        "@vitest/pretty-format": "4.1.12",
+        "@vitest/runner": "4.1.12",
+        "@vitest/snapshot": "4.1.12",
+        "@vitest/spy": "4.1.12",
+        "@vitest/utils": "4.1.12",
         "es-module-lexer": "^2.0.0",
         "expect-type": "^1.3.0",
         "magic-string": "^0.30.21",
@@ -12293,12 +12286,12 @@
         "@edge-runtime/vm": "*",
         "@opentelemetry/api": "^1.9.0",
         "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.10",
-        "@vitest/browser-preview": "4.1.10",
-        "@vitest/browser-webdriverio": "4.1.10",
-        "@vitest/coverage-istanbul": "4.1.10",
-        "@vitest/coverage-v8": "4.1.10",
-        "@vitest/ui": "4.1.10",
+        "@vitest/browser-playwright": "4.1.12",
+        "@vitest/browser-preview": "4.1.12",
+        "@vitest/browser-webdriverio": "^4.1.11",
+        "@vitest/coverage-istanbul": "4.1.12",
+        "@vitest/coverage-v8": "4.1.12",
+        "@vitest/ui": "4.1.12",
         "happy-dom": "*",
         "jsdom": "*",
         "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
diff --git a/package.json b/package.json
index 462ccdb..bd9b98e 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mongobench",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "private": true,
   "description": "A modern, dark-mode-first MongoDB GUI.",
   "author": "ByteExceptionM",
@@ -85,7 +85,7 @@
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.6.2",
     "vite": "^7.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.12"
   },
   "overrides": {
     "dompurify": "^3.4.13"
diff --git a/src/main/index.ts b/src/main/index.ts
index eaef1cc..562db5c 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -8,6 +8,8 @@ const APP_ICON = app.isPackaged
 import log from 'electron-log/main'
 import { EventChannels } from './ipc/channels'
 import { registerIpcHandlers } from './ipc/router'
+import { opensInBrowser } from './lib/externalUrl'
+import { CloudflaredTunnelService } from './services/CloudflaredTunnelService'
 import { ConnectionService } from './services/ConnectionService'
 import { DatabaseService } from './services/DatabaseService'
 import { IndexService } from './services/IndexService'
@@ -71,14 +73,14 @@ function createWindow(): void {
   })
 
   window.webContents.setWindowOpenHandler(({ url }) => {
-    void shell.openExternal(url)
+    if (opensInBrowser(url)) void shell.openExternal(url)
     return { action: 'deny' }
   })
 
   window.webContents.on('will-navigate', (event, url) => {
     if (url !== window.webContents.getURL()) {
       event.preventDefault()
-      void shell.openExternal(url)
+      if (opensInBrowser(url)) void shell.openExternal(url)
     }
   })
 
@@ -113,8 +115,11 @@ function createWindow(): void {
 app.whenReady().then(() => {
   const secrets = new SecretsStore()
   const repo = new ConnectionsRepository(secrets)
-  const tunnels = new SshTunnelService(new HostKeysStore())
-  const connections = new ConnectionService(repo, tunnels, (connectionId, reason) =>
+  const sshTunnels = new SshTunnelService(new HostKeysStore())
+  const cloudflared = new CloudflaredTunnelService((prompt) =>
+    pushToRenderer(EventChannels.CloudflaredLogin, prompt)
+  )
+  const connections = new ConnectionService(repo, sshTunnels, cloudflared, (connectionId, reason) =>
     pushToRenderer(EventChannels.ConnectionDropped, { connectionId, reason })
   )
   const databases = new DatabaseService(connections)
@@ -127,7 +132,16 @@ app.whenReady().then(() => {
   services.repo = repo
   services.connections = connections
 
-  registerIpcHandlers({ repo, connections, databases, queries, users, indexes, updater })
+  registerIpcHandlers({
+    repo,
+    connections,
+    databases,
+    queries,
+    users,
+    indexes,
+    updater,
+    cloudflared
+  })
 
   createWindow()
 
diff --git a/src/main/ipc/channels.ts b/src/main/ipc/channels.ts
index 5e0f0db..d6003ec 100644
--- a/src/main/ipc/channels.ts
+++ b/src/main/ipc/channels.ts
@@ -22,15 +22,18 @@ export const Channels = {
   CollectionsCreate: 'collections:create',
   CollectionsDrop: 'collections:drop',
   CollectionsRename: 'collections:rename',
+  CollectionsSchema: 'collections:schema',
 
   IndexesList: 'indexes:list',
   IndexesCreate: 'indexes:create',
   IndexesDrop: 'indexes:drop',
+  IndexesStats: 'indexes:stats',
 
   UsersList: 'users:list',
   UsersCreate: 'users:create',
   UsersUpdate: 'users:update',
   UsersDrop: 'users:drop',
+  RolesList: 'roles:list',
 
   QueryFind: 'query:find',
   QueryAggregate: 'query:aggregate',
@@ -40,12 +43,18 @@ export const Channels = {
   QueryInsertMany: 'query:insertMany',
   QueryDeleteOne: 'query:deleteOne',
   QueryDeleteMany: 'query:deleteMany',
+  QueryDistinct: 'query:distinct',
+  QueryCancel: 'query:cancel',
+  QueryWrite: 'query:write',
 
   UpdaterCheck: 'updater:check',
   UpdaterDownload: 'updater:download',
   UpdaterInstall: 'updater:install',
 
-  DialogPickPrivateKey: 'dialog:pickPrivateKey'
+  CloudflaredVersion: 'cloudflared:version',
+
+  DialogPickPrivateKey: 'dialog:pickPrivateKey',
+  DialogPickCloudflared: 'dialog:pickCloudflared'
 } as const
 
 export type ChannelName = (typeof Channels)[keyof typeof Channels]
@@ -53,5 +62,6 @@ export type ChannelName = (typeof Channels)[keyof typeof Channels]
 /** main → renderer pushes. Subscribed to in the preload, never `handle`d. */
 export const EventChannels = {
   UpdaterProgress: 'updater:progress',
-  ConnectionDropped: 'connections:dropped'
+  ConnectionDropped: 'connections:dropped',
+  CloudflaredLogin: 'cloudflared:login'
 } as const
diff --git a/src/main/ipc/router.test.ts b/src/main/ipc/router.test.ts
new file mode 100644
index 0000000..3eb2d61
--- /dev/null
+++ b/src/main/ipc/router.test.ts
@@ -0,0 +1,78 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Result } from '@shared/result'
+
+type Handler = (event: unknown, payload?: unknown) => Promise<Result<unknown>>
+
+const ipc = vi.hoisted(() => ({ handlers: new Map<string, Handler>(), warn: vi.fn() }))
+
+vi.mock('electron', () => ({
+  BrowserWindow: { getFocusedWindow: () => null },
+  dialog: { showOpenDialog: vi.fn() },
+  ipcMain: { handle: (channel: string, handler: Handler) => ipc.handlers.set(channel, handler) }
+}))
+vi.mock('electron-log/main', () => ({
+  default: { info: vi.fn(), warn: ipc.warn, debug: vi.fn(), error: vi.fn() }
+}))
+
+const { registerIpcHandlers } = await import('./router')
+const { Channels } = await import('./channels')
+type Services = Parameters<typeof registerIpcHandlers>[0]
+
+const FIND = {
+  connectionId: '7f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f',
+  db: 'app',
+  coll: 'players',
+  skip: 0
+}
+
+const queries = { find: vi.fn() }
+const repo = { list: vi.fn() }
+registerIpcHandlers({ queries, repo } as unknown as Services)
+
+function invoke(channel: string, payload?: unknown): Promise<Result<unknown>> {
+  const handler = ipc.handlers.get(channel)
+  if (!handler) throw new Error(`no handler for ${channel}`)
+  return handler({}, payload)
+}
+
+function named(name: string, message: string): Error {
+  return Object.assign(new Error(message), { name })
+}
+
+beforeEach(() => {
+  ipc.warn.mockClear()
+})
+
+describe('IPC handler failures', () => {
+  it('returns a cancelled run as an error without logging a warning', async () => {
+    queries.find.mockRejectedValueOnce(named('CancelledError', 'Query cancelled'))
+
+    await expect(invoke(Channels.QueryFind, FIND)).resolves.toEqual({
+      ok: false,
+      error: { code: 'cancelled', message: 'Query cancelled' }
+    })
+    expect(ipc.warn).not.toHaveBeenCalled()
+  })
+
+  it('logs every other failure as a warning', async () => {
+    queries.find.mockRejectedValueOnce(named('DocumentNotFoundError', 'gone'))
+
+    await expect(invoke(Channels.QueryFind, FIND)).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'not_found' }
+    })
+    expect(ipc.warn).toHaveBeenCalledWith('IPC handler failed', {
+      code: 'not_found',
+      message: 'gone'
+    })
+  })
+
+  it('treats a cancel the same way in handlers without input', async () => {
+    repo.list.mockRejectedValueOnce(named('CancelledError', 'Query cancelled'))
+
+    await expect(invoke(Channels.ConnectionsList)).resolves.toMatchObject({
+      error: { code: 'cancelled' }
+    })
+    expect(ipc.warn).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/ipc/router.ts b/src/main/ipc/router.ts
index 0c2ef04..b28bad6 100644
--- a/src/main/ipc/router.ts
+++ b/src/main/ipc/router.ts
@@ -5,6 +5,8 @@ import log from 'electron-log/main'
 import type { ZodType } from 'zod'
 import {
   AggregateRequestSchema,
+  CancelQuerySchema,
+  CloudflaredVersionSchema,
   CollectionRefSchema,
   ConnectionIdSchema,
   ConnectionInputSchema,
@@ -19,6 +21,7 @@ import {
   DatabaseRefSchema,
   DeleteManyRequestSchema,
   DeleteOneRequestSchema,
+  DistinctRequestSchema,
   DropIndexSchema,
   DropUserSchema,
   FindRequestSchema,
@@ -28,12 +31,14 @@ import {
   RenameCollectionSchema,
   ReorderConnectionsSchema,
   ReplaceOneRequestSchema,
-  UpdateUserSchema
+  UpdateUserSchema,
+  WriteRequestSchema
 } from '@shared/schemas'
 import type { Result } from '@shared/result'
 import { err, ok } from '@shared/result'
 import { mapError } from '../lib/errorMap'
 import type { ConnectionsRepository } from '../stores/ConnectionsRepository'
+import type { CloudflaredTunnelService } from '../services/CloudflaredTunnelService'
 import type { ConnectionService } from '../services/ConnectionService'
 import type { DatabaseService } from '../services/DatabaseService'
 import type { IndexService } from '../services/IndexService'
@@ -50,6 +55,7 @@ export type Services = {
   users: UserService
   indexes: IndexService
   updater: UpdaterService
+  cloudflared: CloudflaredTunnelService
 }
 
 function withResult<P, R>(
@@ -66,9 +72,7 @@ function withResult<P, R>(
     try {
       return ok(await fn(parsed.data))
     } catch (error) {
-      const mapped = mapError(error)
-      log.warn(`IPC handler failed`, mapped)
-      return err(mapped.code, mapped.message, mapped.details)
+      return failure(error)
     }
   }
 }
@@ -78,15 +82,31 @@ function withoutInput<R>(fn: () => Promise<R>): (event: IpcMainInvokeEvent) => P
     try {
       return ok(await fn())
     } catch (error) {
-      const mapped = mapError(error)
-      log.warn(`IPC handler failed`, mapped)
-      return err(mapped.code, mapped.message, mapped.details)
+      return failure(error)
     }
   }
 }
 
+function failure(error: unknown): Result<never> {
+  const mapped = mapError(error)
+  // A cancel is the user's own action, not a failure.
+  if (mapped.code !== 'cancelled') log.warn(`IPC handler failed`, mapped)
+  return err(mapped.code, mapped.message, mapped.details)
+}
+
+/** Native file picker, parented to the focused window when there is one. */
+async function pickFile(options: Electron.OpenDialogOptions): Promise<string | null> {
+  const parent = BrowserWindow.getFocusedWindow()
+  const result =
+    parent === null
+      ? await dialog.showOpenDialog(options)
+      : await dialog.showOpenDialog(parent, options)
+  if (result.canceled) return null
+  return result.filePaths[0] ?? null
+}
+
 export function registerIpcHandlers(services: Services): void {
-  const { repo, connections, databases, queries, users, indexes, updater } = services
+  const { repo, connections, databases, queries, users, indexes, updater, cloudflared } = services
 
   ipcMain.handle(
     Channels.ConnectionsList,
@@ -166,6 +186,13 @@ export function registerIpcHandlers(services: Services): void {
     )
   )
 
+  ipcMain.handle(
+    Channels.CollectionsSchema,
+    withResult(CollectionRefSchema, ({ connectionId, db, coll }) =>
+      databases.collectionSchema(connectionId, db, coll)
+    )
+  )
+
   ipcMain.handle(
     Channels.CollectionsCreate,
     withResult(CreateCollectionSchema, ({ connectionId, db, name }) =>
@@ -232,6 +259,22 @@ export function registerIpcHandlers(services: Services): void {
     withResult(DeleteManyRequestSchema, (request) => queries.deleteMany(request))
   )
 
+  ipcMain.handle(
+    Channels.QueryDistinct,
+    withResult(DistinctRequestSchema, (request) => queries.distinct(request))
+  )
+
+  // Ids of runs that already settled are ignored.
+  ipcMain.handle(
+    Channels.QueryCancel,
+    withResult(CancelQuerySchema, async ({ requestId }) => queries.cancel(requestId))
+  )
+
+  ipcMain.handle(
+    Channels.QueryWrite,
+    withResult(WriteRequestSchema, (request) => queries.write(request))
+  )
+
   ipcMain.handle(
     Channels.IndexesList,
     withResult(IndexesListSchema, ({ connectionId, db, coll }) =>
@@ -239,6 +282,13 @@ export function registerIpcHandlers(services: Services): void {
     )
   )
 
+  ipcMain.handle(
+    Channels.IndexesStats,
+    withResult(CollectionRefSchema, ({ connectionId, db, coll }) =>
+      indexes.indexStats(connectionId, db, coll)
+    )
+  )
+
   ipcMain.handle(
     Channels.IndexesCreate,
     withResult(CreateIndexSchema, ({ connectionId, db, coll, keys, options }) =>
@@ -279,6 +329,16 @@ export function registerIpcHandlers(services: Services): void {
     )
   )
 
+  ipcMain.handle(
+    Channels.RolesList,
+    withResult(DatabaseRefSchema, ({ connectionId, db }) => users.listRoles(connectionId, db))
+  )
+
+  ipcMain.handle(
+    Channels.CloudflaredVersion,
+    withResult(CloudflaredVersionSchema, ({ binaryPath }) => cloudflared.version(binaryPath))
+  )
+
   ipcMain.handle(
     Channels.UpdaterCheck,
     withoutInput(() => updater.check())
@@ -302,20 +362,26 @@ export function registerIpcHandlers(services: Services): void {
   // main at connect time and never leaves it.
   ipcMain.handle(
     Channels.DialogPickPrivateKey,
-    withoutInput(async () => {
-      const options: Electron.OpenDialogOptions = {
+    withoutInput(() =>
+      pickFile({
         title: 'Select an SSH private key',
         defaultPath: join(homedir(), '.ssh'),
         // Key files carry no extension, and .ssh is a hidden directory.
         properties: ['openFile', 'showHiddenFiles', 'dontAddToRecent']
-      }
-      const parent = BrowserWindow.getFocusedWindow()
-      const result =
-        parent === null
-          ? await dialog.showOpenDialog(options)
-          : await dialog.showOpenDialog(parent, options)
-      if (result.canceled) return null
-      return result.filePaths[0] ?? null
-    })
+      })
+    )
+  )
+
+  ipcMain.handle(
+    Channels.DialogPickCloudflared,
+    withoutInput(() =>
+      pickFile({
+        title: 'Select the cloudflared executable',
+        properties: ['openFile', 'dontAddToRecent'],
+        ...(process.platform === 'win32'
+          ? { filters: [{ name: 'Executables', extensions: ['exe'] }] }
+          : {})
+      })
+    )
   )
 }
diff --git a/src/main/lib/cloudflaredLog.test.ts b/src/main/lib/cloudflaredLog.test.ts
new file mode 100644
index 0000000..8cfe333
--- /dev/null
+++ b/src/main/lib/cloudflaredLog.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest'
+import { findLoginUrl, OutputTail, parseLogLine, splitLines } from './cloudflaredLog'
+
+// Lines cloudflared 2025.8.1 printed in local runs against a hostname that cannot resolve.
+const INF_LINE = '2026-10-16T12:57:58Z INF Start Websocket listener host=127.0.0.1:62183'
+const ERR_LINE =
+  '2026-10-16T12:58:01Z ERR failed to connect to origin error="dial tcp: lookup mongo.example.invalid: no such host" originURL=https://mongo.example.invalid'
+const EMPTY_MESSAGE_ERR_LINE =
+  '2026-10-16T12:58:03Z ERR  error="failed to parse as URL: parse \\"https://-x\\": invalid character"'
+const LOGIN_URL =
+  'https://mongo.example.com/cdn-cgi/access/cli?aud=abc&redirect_url=https%3A%2F%2Fmongo.example.com&token=xyz'
+
+describe('parseLogLine', () => {
+  it('parses an INF line', () => {
+    expect(parseLogLine(INF_LINE)).toEqual({
+      level: 'INF',
+      message: 'Start Websocket listener host=127.0.0.1:62183'
+    })
+  })
+
+  it('parses an ERR line', () => {
+    expect(parseLogLine(ERR_LINE)?.level).toBe('ERR')
+    expect(parseLogLine(ERR_LINE)?.message).toMatch(/^failed to connect to origin error=/)
+  })
+
+  it('parses an ERR line whose message is empty down to its fields', () => {
+    expect(parseLogLine(EMPTY_MESSAGE_ERR_LINE)).toEqual({
+      level: 'ERR',
+      message: 'error="failed to parse as URL: parse \\"https://-x\\": invalid character"'
+    })
+  })
+
+  it('returns null for a line that is not a log line', () => {
+    expect(parseLogLine('failed to get app info: Head "https://x": no such host')).toBeNull()
+  })
+})
+
+describe('findLoginUrl', () => {
+  it('returns the sign-in URL for the configured hostname', () => {
+    expect(findLoginUrl(LOGIN_URL, 'mongo.example.com')).toBe(LOGIN_URL)
+  })
+
+  it('matches the hostname case-insensitively', () => {
+    expect(findLoginUrl(LOGIN_URL, 'Mongo.Example.com')).toBe(LOGIN_URL)
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(findLoginUrl(`  ${LOGIN_URL}\r`, 'mongo.example.com')).toBe(LOGIN_URL)
+  })
+
+  it('ignores a URL for another host', () => {
+    expect(
+      findLoginUrl('https://evil.example.net/cdn-cgi/access/cli?aud=abc', 'mongo.example.com')
+    ).toBeNull()
+  })
+
+  it('ignores plain http', () => {
+    expect(findLoginUrl(LOGIN_URL.replace('https:', 'http:'), 'mongo.example.com')).toBeNull()
+  })
+
+  it('ignores another path on the right host', () => {
+    expect(findLoginUrl('https://mongo.example.com/somewhere/else', 'mongo.example.com')).toBeNull()
+  })
+
+  it('ignores prose', () => {
+    expect(
+      findLoginUrl('A browser window should have opened at the following URL:', 'mongo.example.com')
+    ).toBeNull()
+  })
+})
+
+describe('splitLines', () => {
+  function collect(): { lines: string[]; splitter: ReturnType<typeof splitLines> } {
+    const lines: string[] = []
+    return { lines, splitter: splitLines((line) => lines.push(line)) }
+  }
+
+  it('joins a line split across chunks', () => {
+    const { lines, splitter } = collect()
+    splitter.write('first li')
+    splitter.write('ne\nsecond\n')
+    expect(lines).toEqual(['first line', 'second'])
+  })
+
+  it('splits CRLF line endings, also when \\r and \\n arrive in separate chunks', () => {
+    const { lines, splitter } = collect()
+    splitter.write('one\r\ntwo\r')
+    splitter.write('\nthree\r\n')
+    expect(lines).toEqual(['one', 'two', 'three'])
+  })
+
+  it('flushes an unterminated last line on end', () => {
+    const { lines, splitter } = collect()
+    splitter.write('done\npartial')
+    expect(lines).toEqual(['done'])
+    splitter.end()
+    expect(lines).toEqual(['done', 'partial'])
+  })
+})
+
+describe('OutputTail', () => {
+  it('keeps the newest ERR message even after many later lines', () => {
+    const tail = new OutputTail()
+    tail.add(ERR_LINE)
+    for (let i = 0; i < 30; i++)
+      tail.add(`2026-10-16T12:59:${String(i).padStart(2, '0')}Z INF tick ${i}`)
+    expect(tail.lastError()).toMatch(/^failed to connect to origin error=/)
+    expect(tail.describe()).toBe(tail.lastError())
+  })
+
+  it('reports no error before an ERR or FTL line', () => {
+    const tail = new OutputTail()
+    tail.add(INF_LINE)
+    expect(tail.lastError()).toBeNull()
+  })
+
+  it('describes a failure by the last plain line when nothing was logged as an error', () => {
+    const tail = new OutputTail()
+    tail.add(INF_LINE)
+    tail.add('failed to get app info: Head "https://mongo.example.invalid": no such host')
+    expect(tail.describe()).toBe(
+      'failed to get app info: Head "https://mongo.example.invalid": no such host'
+    )
+  })
+
+  it('describes a log line by its message', () => {
+    const tail = new OutputTail()
+    tail.add(INF_LINE)
+    expect(tail.describe()).toBe('Start Websocket listener host=127.0.0.1:62183')
+  })
+
+  it('says so when cloudflared printed nothing', () => {
+    const tail = new OutputTail()
+    tail.add('   ')
+    expect(tail.describe()).toBe('cloudflared printed nothing')
+    expect(tail.text()).toBe('')
+  })
+
+  it('keeps only the last 20 lines', () => {
+    const tail = new OutputTail()
+    for (let i = 0; i < 25; i++) tail.add(`line ${i}`)
+    const kept = tail.text().split('\n')
+    expect(kept).toHaveLength(20)
+    expect(kept[0]).toBe('line 5')
+    expect(kept[19]).toBe('line 24')
+  })
+
+  it('truncates a long line to 500 characters', () => {
+    const tail = new OutputTail()
+    tail.add('x'.repeat(2000))
+    expect(tail.text()).toHaveLength(500)
+  })
+})
diff --git a/src/main/lib/cloudflaredLog.ts b/src/main/lib/cloudflaredLog.ts
new file mode 100644
index 0000000..9df9440
--- /dev/null
+++ b/src/main/lib/cloudflaredLog.ts
@@ -0,0 +1,92 @@
+/**
+ * Reading side of cloudflared's console output: zerolog lines on stderr, with
+ * no colour when piped, plus the plain text `access login` prints. Pure — the
+ * service feeds it what the process wrote.
+ */
+
+const LOG_LINE = /^\d{4}-\d{2}-\d{2}T\S+\s+(DBG|INF|WRN|ERR|FTL)\s+(.*)$/
+const LOGIN_PATH = '/cdn-cgi/access/cli'
+const MAX_LINES = 20
+const MAX_LINE_LENGTH = 500
+
+/** A cloudflared console log line such as `2025-08-21T15:34:00Z ERR failed to connect to origin error="…"`. */
+export function parseLogLine(
+  line: string
+): { level: 'DBG' | 'INF' | 'WRN' | 'ERR' | 'FTL'; message: string } | null {
+  const match = LOG_LINE.exec(line.trim())
+  if (match === null) return null
+  return {
+    level: match[1] as 'DBG' | 'INF' | 'WRN' | 'ERR' | 'FTL',
+    message: (match[2] ?? '').trim()
+  }
+}
+
+/** The Access sign-in URL cloudflared printed for `hostname`, or null. */
+export function findLoginUrl(line: string, hostname: string): string | null {
+  let url: URL
+  try {
+    url = new URL(line.trim())
+  } catch {
+    return null
+  }
+  // The renderer opens this in the browser, so only Access's own sign-in page passes.
+  if (url.protocol !== 'https:') return null
+  if (url.hostname !== hostname.toLowerCase()) return null
+  if (url.pathname !== LOGIN_PATH) return null
+  return url.href
+}
+
+/** Splits a text stream into lines; `end` flushes a final unterminated line. */
+export function splitLines(onLine: (line: string) => void): {
+  write: (chunk: string) => void
+  end: () => void
+} {
+  let pending = ''
+  return {
+    write: (chunk) => {
+      const lines = (pending + chunk).split(/\r?\n/)
+      pending = lines.pop() ?? ''
+      for (const line of lines) onLine(line)
+    },
+    end: () => {
+      if (pending.length > 0) onLine(pending)
+      pending = ''
+    }
+  }
+}
+
+/** Keeps the end of a cloudflared process's output so errors can quote it. */
+export class OutputTail {
+  private readonly lines: string[] = []
+  // Held apart from `lines` so a burst of later INF lines cannot evict the reason.
+  private newestError: string | null = null
+
+  add(line: string): void {
+    const kept = line.trim().slice(0, MAX_LINE_LENGTH)
+    if (kept.length === 0) return
+    this.lines.push(kept)
+    if (this.lines.length > MAX_LINES) this.lines.shift()
+    const parsed = parseLogLine(kept)
+    if (parsed !== null && (parsed.level === 'ERR' || parsed.level === 'FTL')) {
+      this.newestError = parsed.message
+    }
+  }
+
+  /** The newest ERR or FTL message, or null when cloudflared logged none. */
+  lastError(): string | null {
+    return this.newestError
+  }
+
+  /** The best single line to explain a failure. */
+  describe(): string {
+    if (this.newestError !== null) return this.newestError
+    const last = this.lines.at(-1)
+    if (last === undefined) return 'cloudflared printed nothing'
+    return parseLogLine(last)?.message ?? last
+  }
+
+  /** Every kept line, newline-joined. */
+  text(): string {
+    return this.lines.join('\n')
+  }
+}
diff --git a/src/main/lib/connectionUri.test.ts b/src/main/lib/connectionUri.test.ts
index 575d032..ec9f5a1 100644
--- a/src/main/lib/connectionUri.test.ts
+++ b/src/main/lib/connectionUri.test.ts
@@ -1,10 +1,12 @@
 import { describe, expect, it } from 'vitest'
 import {
   canonicalize,
+  firstHostName,
   hasPasswordPlaceholder,
   injectStoredPassword,
   InvalidUriError,
-  parseUri
+  parseUri,
+  replaceHosts
 } from './connectionUri'
 
 describe('parseUri', () => {
@@ -126,3 +128,67 @@ describe('injectStoredPassword', () => {
     expect(restored).toBe(original)
   })
 })
+
+describe('replaceHosts', () => {
+  it('swaps every host and keeps credentials, database and options byte for byte', () => {
+    expect(
+      replaceHosts('mongodb://alice:p%40ss@h1:27017,h2:27018/db?authSource=admin', '127.0.0.1:5000')
+    ).toBe('mongodb://alice:p%40ss@127.0.0.1:5000/db?authSource=admin')
+  })
+
+  it('handles a URI with no path', () => {
+    expect(replaceHosts('mongodb://host', '127.0.0.1:5000')).toBe('mongodb://127.0.0.1:5000')
+  })
+
+  it('handles options without a slash before them', () => {
+    expect(replaceHosts('mongodb://host?tls=true', '127.0.0.1:5000')).toBe(
+      'mongodb://127.0.0.1:5000?tls=true'
+    )
+  })
+
+  it('keeps the stored password placeholder', () => {
+    expect(replaceHosts('mongodb://alice:%3CMONGOBENCH_PWD%3E@host/db', '127.0.0.1:5000')).toBe(
+      'mongodb://alice:%3CMONGOBENCH_PWD%3E@127.0.0.1:5000/db'
+    )
+  })
+
+  it('replaces an IPv6 literal', () => {
+    expect(replaceHosts('mongodb://[::1]:27017/db', '127.0.0.1:5000')).toBe(
+      'mongodb://127.0.0.1:5000/db'
+    )
+  })
+
+  it('rejects mongodb+srv://, whose hosts come from DNS', () => {
+    expect(() => replaceHosts('mongodb+srv://cluster.example.com/db', '127.0.0.1:5000')).toThrow(
+      InvalidUriError
+    )
+  })
+})
+
+describe('firstHostName', () => {
+  it('returns a DNS name in lower case, without the port', () => {
+    expect(firstHostName('mongodb://Mongo.Internal:27017/db')).toBe('mongo.internal')
+  })
+
+  it('returns null for an IPv4 literal', () => {
+    expect(firstHostName('mongodb://10.0.0.1:27017')).toBeNull()
+  })
+
+  it('returns null for an IPv6 literal', () => {
+    expect(firstHostName('mongodb://[::1]:27017')).toBeNull()
+  })
+
+  it('returns null for a percent-encoded socket path', () => {
+    expect(firstHostName('mongodb://%2Ftmp%2Fm.sock')).toBeNull()
+  })
+
+  it('returns the first host of a multi-host URI', () => {
+    expect(
+      firstHostName('mongodb://a.example.com:27017,b.example.com:27018/db?replicaSet=rs')
+    ).toBe('a.example.com')
+  })
+
+  it('ignores credentials', () => {
+    expect(firstHostName('mongodb://alice:p%40ss@db.example.com/admin')).toBe('db.example.com')
+  })
+})
diff --git a/src/main/lib/connectionUri.ts b/src/main/lib/connectionUri.ts
index e2f2ec6..d102fab 100644
--- a/src/main/lib/connectionUri.ts
+++ b/src/main/lib/connectionUri.ts
@@ -9,6 +9,8 @@
  * and is invariant under accidental decode/encode round-trips by other code.
  */
 
+import { isIP } from 'node:net'
+
 const SCHEME_RE = /^(mongodb(?:\+srv)?):\/\//
 const PASSWORD_PLACEHOLDER = '%3CMONGOBENCH_PWD%3E'
 
@@ -142,3 +144,35 @@ export function injectExternalCredentials(uri: string, username: string, passwor
   const parts = parseUri(uri)
   return `${parts.schemeWithSep}${encodeURIComponent(username)}:${encodeURIComponent(password)}@${parts.hostAndRest}`
 }
+
+/**
+ * Swaps the host list of a `mongodb://` URI for one address, keeping credentials, database and options byte for byte.
+ * @param address `host:port` the driver should dial instead.
+ * @throws InvalidUriError for `mongodb+srv://`, whose hosts come from DNS.
+ */
+export function replaceHosts(uri: string, address: string): string {
+  const parts = parseUri(uri)
+  if (parts.scheme === 'mongodb+srv') {
+    throw new InvalidUriError('mongodb+srv:// cannot run through a single forwarded port')
+  }
+  // Raw slice, so an injected password or the placeholder survives unchanged.
+  const prefix = uri.slice(0, uri.length - parts.hostAndRest.length)
+  const stop = parts.hostAndRest.search(/[/?]/)
+  return prefix + address + (stop === -1 ? '' : parts.hostAndRest.slice(stop))
+}
+
+/**
+ * The first host of a URI when it is a DNS name, lower-cased, for TLS certificate checks.
+ * @returns null for IP literals (incl. `[…]`) and percent-encoded socket paths.
+ */
+export function firstHostName(uri: string): string | null {
+  const { hostAndRest } = parseUri(uri)
+  const stop = hostAndRest.search(/[/?]/)
+  const hosts = stop === -1 ? hostAndRest : hostAndRest.slice(0, stop)
+  const first = hosts.split(',')[0] ?? ''
+  if (first.startsWith('[')) return null
+  const colon = first.lastIndexOf(':')
+  const host = decodeURIComponent(colon === -1 ? first : first.slice(0, colon))
+  if (host.length === 0 || host.includes('/') || isIP(host) !== 0) return null
+  return host.toLowerCase()
+}
diff --git a/src/main/lib/ejson.test.ts b/src/main/lib/ejson.test.ts
index 9cc1f85..7ab178f 100644
--- a/src/main/lib/ejson.test.ts
+++ b/src/main/lib/ejson.test.ts
@@ -1,6 +1,15 @@
 import { describe, expect, it } from 'vitest'
-import { Binary, Decimal128, Long, ObjectId } from 'bson'
-import { canonicalHash, parseFilter, toCanonicalString, toRelaxed } from './ejson'
+import { BSON, BSONRegExp, Binary, Decimal128, Double, EJSON, Int32, Long, ObjectId } from 'bson'
+import {
+  canonicalHash,
+  decodeDocument,
+  hashCanonicalString,
+  parseFilter,
+  parseRelaxed,
+  toCanonical,
+  toCanonicalString,
+  toRelaxed
+} from './ejson'
 
 describe('toRelaxed', () => {
   it('wraps ObjectId as { $oid }', () => {
@@ -21,9 +30,63 @@ describe('toRelaxed', () => {
     expect(out.price).toEqual({ $numberDecimal: '12345.6789' })
   })
 
-  it('keeps small Longs as plain numbers', () => {
-    const out = toRelaxed({ n: Long.fromNumber(42) }) as { n: number }
-    expect(out.n).toBe(42)
+  it('wraps small Longs as { $numberLong }', () => {
+    const out = toRelaxed({ n: Long.fromNumber(42) }) as { n: unknown }
+    expect(out.n).toEqual({ $numberLong: '42' })
+  })
+
+  it('keeps Longs beyond 2^53 exact', () => {
+    const out = toRelaxed({
+      big: Long.fromString('9007199254740993'),
+      neg: Long.fromString('-1234567890123456789')
+    })
+    expect(out).toEqual({
+      big: { $numberLong: '9007199254740993' },
+      neg: { $numberLong: '-1234567890123456789' }
+    })
+  })
+
+  it('wraps Longs nested in arrays and subdocuments', () => {
+    const big = Long.fromString('9007199254740993')
+    const out = toRelaxed({ list: [big, { inner: [big] }], sub: { deeper: { n: big } } })
+    expect(out).toEqual({
+      list: [{ $numberLong: '9007199254740993' }, { inner: [{ $numberLong: '9007199254740993' }] }],
+      sub: { deeper: { n: { $numberLong: '9007199254740993' } } }
+    })
+  })
+
+  it('leaves other BSON values next to a Long unchanged', () => {
+    const out = toRelaxed({
+      _id: new ObjectId('507f1f77bcf86cd799439011'),
+      at: new Date('2026-01-15T10:30:00.123Z'),
+      price: Decimal128.fromString('1.5'),
+      n: Long.fromNumber(7)
+    })
+    expect(out).toEqual({
+      _id: { $oid: '507f1f77bcf86cd799439011' },
+      at: { $date: '2026-01-15T10:30:00.123Z' },
+      price: { $numberDecimal: '1.5' },
+      n: { $numberLong: '7' }
+    })
+  })
+
+  it('keeps a __proto__ field as an own field', () => {
+    const doc = Object.defineProperty({}, '__proto__', {
+      value: { n: Long.fromNumber(1) },
+      enumerable: true,
+      writable: true,
+      configurable: true
+    })
+    const out = toRelaxed(doc)
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype)
+    expect(Object.getOwnPropertyDescriptor(out, '__proto__')?.value).toEqual({
+      n: { $numberLong: '1' }
+    })
+  })
+
+  it('shows Int32 and finite Double read without promotion as plain numbers', () => {
+    const out = toRelaxed({ i: new Int32(7), d: new Double(2.5) })
+    expect(out).toEqual({ i: 7, d: 2.5 })
   })
 
   it('wraps Binary as { $binary }', () => {
@@ -51,6 +114,100 @@ describe('toCanonicalString', () => {
   })
 })
 
+describe('decodeDocument', () => {
+  const stored = {
+    l: Long.fromNumber(5),
+    d: new Double(5),
+    z: new Double(-0),
+    i: new Int32(7),
+    n: new Double(NaN)
+  }
+
+  function readBack(): Record<string, unknown> {
+    return decodeDocument(BSON.serialize(stored))
+  }
+
+  it('keeps the stored numeric type of every field in canonical EJSON', () => {
+    expect(JSON.parse(toCanonicalString(readBack()))).toEqual({
+      l: { $numberLong: '5' },
+      d: { $numberDouble: '5.0' },
+      z: { $numberDouble: '-0.0' },
+      i: { $numberInt: '7' },
+      n: { $numberDouble: 'NaN' }
+    })
+  })
+
+  it('writes back the same BSON types after a canonical round trip', () => {
+    const reparsed = EJSON.parse(toCanonicalString(readBack()), { relaxed: false }) as object
+    const written = decodeDocument(BSON.serialize(reparsed))
+    const types = Object.fromEntries(
+      Object.entries(written).map(([k, v]) => [k, (v as { _bsontype: string })._bsontype])
+    )
+    expect(types).toEqual({ l: 'Long', d: 'Double', z: 'Double', i: 'Int32', n: 'Double' })
+  })
+
+  it('differs from the driver default, which collapses them to the smallest integer type', () => {
+    const promoted = BSON.deserialize(BSON.serialize(stored))
+    expect(JSON.parse(toCanonicalString(promoted))).toMatchObject({
+      l: { $numberInt: '5' },
+      d: { $numberInt: '5' }
+    })
+  })
+
+  // A JS RegExp would map 's' to 'g', drop x/u, and rewrite '/', line terminators and ''.
+  const REGEXES: Array<[string, string]> = [
+    ['dot.all', 's'],
+    ['(?i)abc', ''],
+    ['a/b', ''],
+    ['^https://x', ''],
+    ['a\nb', ''],
+    ['', ''],
+    ['a b', 'x'],
+    ['x', 'u'],
+    ['^abc$', 'imsux']
+  ]
+
+  it.each(REGEXES)('keeps the stored regex /%s/%s exactly', (pattern, options) => {
+    const doc = decodeDocument(BSON.serialize({ re: new BSONRegExp(pattern, options) }))
+    expect(JSON.parse(toCanonicalString(doc))).toEqual({
+      re: { $regularExpression: { pattern, options } }
+    })
+  })
+
+  it.each(REGEXES)('writes the regex /%s/%s back unchanged', (pattern, options) => {
+    const read = decodeDocument(BSON.serialize({ re: new BSONRegExp(pattern, options) }))
+    const reparsed = EJSON.parse(toCanonicalString(read), { relaxed: false }) as object
+    const written = decodeDocument(BSON.serialize(reparsed))['re'] as BSONRegExp
+    expect([written.pattern, written.options]).toEqual([pattern, options])
+  })
+})
+
+describe('toCanonical', () => {
+  it('wraps every BSON type, plain numbers included', () => {
+    const out = toCanonical({
+      _id: new ObjectId('507f1f77bcf86cd799439011'),
+      n: 1,
+      l: Long.fromNumber(2),
+      d: new Double(3),
+      at: new Date(0),
+      tags: ['a']
+    })
+    expect(out).toEqual({
+      _id: { $oid: '507f1f77bcf86cd799439011' },
+      n: { $numberInt: '1' },
+      l: { $numberLong: '2' },
+      d: { $numberDouble: '3.0' },
+      at: { $date: { $numberLong: '0' } },
+      tags: ['a']
+    })
+  })
+
+  it('returns a plain object that JSON-stringifies to the canonical string', () => {
+    const doc = { a: Long.fromString('9007199254740993'), b: [new Int32(1)] }
+    expect(JSON.stringify(toCanonical(doc))).toBe(toCanonicalString(doc))
+  })
+})
+
 describe('parseFilter', () => {
   it('returns {} for empty / whitespace input', () => {
     expect(parseFilter(undefined)).toEqual({})
@@ -62,6 +219,18 @@ describe('parseFilter', () => {
     expect(parseFilter('{ "a": 1 }')).toEqual({ a: 1 })
   })
 
+  it('keeps Int64 values beyond 2^53 exact in the BSON sent to the server', () => {
+    const parsed = parseFilter(
+      '{ "uid": { "$numberLong": "9007199254740993" }, "max": { "$numberLong": "9223372036854775807" } }'
+    )
+    const sent = BSON.deserialize(BSON.serialize(parsed), { promoteLongs: false })
+    expect([String(sent['uid']), String(sent['max'])]).toEqual([
+      '9007199254740993',
+      '9223372036854775807'
+    ])
+    expect([sent['uid']._bsontype, sent['max']._bsontype]).toEqual(['Long', 'Long'])
+  })
+
   it('parses EJSON shorthand for ObjectId', () => {
     const parsed = parseFilter('{ "_id": { "$oid": "507f1f77bcf86cd799439011" } }')
     expect(parsed['_id']).toBeInstanceOf(ObjectId)
@@ -73,6 +242,15 @@ describe('parseFilter', () => {
   })
 })
 
+describe('parseRelaxed', () => {
+  it('reads $numberLong as an exact bigint and plain numbers as numbers', () => {
+    expect(parseRelaxed('{ "big": { "$numberLong": "9007199254740993" }, "n": 1 }')).toEqual({
+      big: 9007199254740993n,
+      n: 1
+    })
+  })
+})
+
 describe('canonicalHash', () => {
   it('produces a 64-char hex digest', () => {
     const hash = canonicalHash({ a: 1 })
@@ -86,4 +264,9 @@ describe('canonicalHash', () => {
   it('changes with different content', () => {
     expect(canonicalHash({ a: 1 })).not.toBe(canonicalHash({ a: 2 }))
   })
+
+  it('equals the hash of the canonical string', () => {
+    const doc = { _id: new ObjectId('507f1f77bcf86cd799439011'), n: Long.fromNumber(5) }
+    expect(hashCanonicalString(toCanonicalString(doc))).toBe(canonicalHash(doc))
+  })
 })
diff --git a/src/main/lib/ejson.ts b/src/main/lib/ejson.ts
index 28d2408..b71da04 100644
--- a/src/main/lib/ejson.ts
+++ b/src/main/lib/ejson.ts
@@ -1,5 +1,6 @@
-import { EJSON } from 'bson'
+import { BSON, EJSON, type Document } from 'bson'
 import { createHash } from 'node:crypto'
+import { isDocument } from '@shared/writeOps'
 
 /**
  * EJSON helpers — the only place in the main process that touches
@@ -12,9 +13,23 @@ import { createHash } from 'node:crypto'
 
 export type RelaxedDocument = Record<string, unknown>
 
-/** Convert a BSON document to its relaxed-EJSON object form (display). */
+// Not driver options: per operation they would also turn server error codes into Int32 and stop retries.
+const DOCUMENT_DECODE_OPTIONS = { promoteValues: false, bsonRegExp: true } as const
+
+/** Driver options for replies read decoded: Int64 and regexes stay exact; error codes stay numbers. */
+export const REPLY_DECODE_OPTIONS = { promoteLongs: false, bsonRegExp: true } as const
+
+/**
+ * Decodes a document read with `raw: true`, keeping every stored BSON type for canonical EJSON.
+ * @param bytes one raw document as the driver returns it
+ */
+export function decodeDocument(bytes: Uint8Array): Document {
+  return BSON.deserialize(bytes, DOCUMENT_DECODE_OPTIONS)
+}
+
+/** Convert a BSON document to its relaxed-EJSON object form (display); Int64 stays `{ $numberLong }`. */
 export function toRelaxed(doc: unknown): RelaxedDocument {
-  return EJSON.serialize(doc as object, { relaxed: true }) as RelaxedDocument
+  return EJSON.serialize(wrapInt64(doc) as object, { relaxed: true }) as RelaxedDocument
 }
 
 /** Convert a BSON value to its canonical-EJSON string (stable identity). */
@@ -22,6 +37,37 @@ export function toCanonicalString(value: unknown): string {
   return EJSON.stringify(value, { relaxed: false })
 }
 
+/** Convert a BSON value to its canonical-EJSON object form (every BSON type wrapped). */
+export function toCanonical(value: unknown): unknown {
+  return EJSON.serialize(value as object, { relaxed: false })
+}
+
+// Relaxed EJSON turns every Long into a JS number, which rounds beyond 2^53.
+function wrapInt64(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(wrapInt64)
+  if (typeof value !== 'object' || value === null) return value
+  if ('_bsontype' in value) {
+    // Longs inside a DBRef's fields or a Code scope stay relaxed; EJSON serializes those itself.
+    return value._bsontype === 'Long' ? { $numberLong: String(value) } : value
+  }
+  const proto: unknown = Object.getPrototypeOf(value)
+  if (proto !== Object.prototype && proto !== null) return value
+  const out: Record<string, unknown> = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === '__proto__') {
+      Object.defineProperty(out, key, {
+        value: wrapInt64(entry),
+        writable: true,
+        enumerable: true,
+        configurable: true
+      })
+    } else {
+      out[key] = wrapInt64(entry)
+    }
+  }
+  return out
+}
+
 /**
  * Parse a user-supplied EJSON/JSON string into a BSON document. Empty or
  * whitespace-only input becomes `{}`. Relaxed mode is allowed so users
@@ -31,14 +77,24 @@ export function parseFilter(input: string | undefined): Record<string, unknown>
   if (input === undefined) return {}
   const trimmed = input.trim()
   if (trimmed.length === 0) return {}
-  const parsed = EJSON.parse(trimmed, { relaxed: true })
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+  const parsed = parseRelaxed(trimmed)
+  if (!isDocument(parsed)) {
     throw new Error('Filter must be a JSON object')
   }
-  return parsed as Record<string, unknown>
+  return parsed
+}
+
+/** Parses relaxed EJSON from the user; `$numberLong` becomes a bigint, which stays exact beyond 2^53. */
+export function parseRelaxed(input: string): unknown {
+  return EJSON.parse(input, { relaxed: true, useBigInt64: true })
 }
 
 /** sha-256 of a value's canonical-EJSON form. Used for optimistic concurrency in M3. */
 export function canonicalHash(value: unknown): string {
-  return createHash('sha256').update(toCanonicalString(value)).digest('hex')
+  return hashCanonicalString(toCanonicalString(value))
+}
+
+/** `canonicalHash` for a value whose canonical-EJSON string is already at hand. */
+export function hashCanonicalString(canonical: string): string {
+  return createHash('sha256').update(canonical).digest('hex')
 }
diff --git a/src/main/lib/errorMap.test.ts b/src/main/lib/errorMap.test.ts
new file mode 100644
index 0000000..0993cb7
--- /dev/null
+++ b/src/main/lib/errorMap.test.ts
@@ -0,0 +1,217 @@
+import { describe, expect, it } from 'vitest'
+import { MongoBulkWriteError, type BulkWriteResult } from 'mongodb'
+import { cancelledError, mapError, validationError } from './errorMap'
+
+function named(name: string, message = 'boom', fields: Record<string, unknown> = {}): Error {
+  return Object.assign(new Error(message), { name }, fields)
+}
+
+/** The driver's real class: `insertedCount` is a prototype getter over `result`, not an own field. */
+function bulkWriteError(insertedCount: number): MongoBulkWriteError {
+  return new MongoBulkWriteError(
+    { message: 'E11000 duplicate key error collection: app.users index: _id_', code: 11000 },
+    { insertedCount } as unknown as BulkWriteResult
+  )
+}
+
+describe('mapError — tunnels', () => {
+  it.each([
+    ['SshHostKeyMismatchError', 'ssh_host_key_mismatch'],
+    ['SshAuthError', 'ssh_auth_failed'],
+    ['SshConnectError', 'ssh_connect_failed'],
+    ['CloudflaredNotFoundError', 'cloudflared_not_found'],
+    ['CloudflaredAuthError', 'cloudflared_auth_failed'],
+    ['CloudflaredTunnelError', 'cloudflared_failed']
+  ])('maps %s to %s and keeps the message', (name, code) => {
+    expect(mapError(named(name, 'tunnel says no'))).toEqual({ code, message: 'tunnel says no' })
+  })
+
+  it('reports a tunnel failure even when its message mentions authentication', () => {
+    expect(mapError(named('CloudflaredAuthError', 'Access authentication failed')).code).toBe(
+      'cloudflared_auth_failed'
+    )
+    expect(mapError(named('SshAuthError', 'SSH authentication failed for tunneluser')).code).toBe(
+      'ssh_auth_failed'
+    )
+  })
+})
+
+describe('mapError — app errors', () => {
+  it('maps an error made by cancelledError to cancelled', () => {
+    expect(mapError(cancelledError('Query cancelled'))).toEqual({
+      code: 'cancelled',
+      message: 'Query cancelled'
+    })
+  })
+
+  it('maps NotConnectedError to not_connected', () => {
+    expect(mapError(named('NotConnectedError', 'Connection c1 is not connected'))).toEqual({
+      code: 'not_connected',
+      message: 'Connection c1 is not connected'
+    })
+  })
+
+  it.each([
+    ['InvalidUriError', 'validation_error'],
+    ['ValidationError', 'validation_error'],
+    ['ConnectionNotFoundError', 'not_found'],
+    ['DocumentNotFoundError', 'not_found'],
+    ['DocumentConflictError', 'conflict'],
+    ['DocumentImmutableIdError', 'conflict']
+  ])('maps %s to %s', (name, code) => {
+    expect(mapError(named(name, 'nope'))).toEqual({ code, message: 'nope' })
+  })
+
+  it('maps an error made by validationError to validation_error', () => {
+    expect(mapError(validationError('bad input'))).toEqual({
+      code: 'validation_error',
+      message: 'bad input'
+    })
+  })
+
+  it('treats an untagged "URI must start" message as a validation error', () => {
+    expect(mapError(new Error('URI must start with mongodb:// or mongodb+srv://')).code).toBe(
+      'validation_error'
+    )
+  })
+})
+
+describe('mapError — driver errors', () => {
+  it('maps MongoServerSelectionError to server_selection_timeout', () => {
+    expect(mapError(named('MongoServerSelectionError', 'timed out'))).toEqual({
+      code: 'server_selection_timeout',
+      message: 'timed out'
+    })
+  })
+
+  it.each(['MongoNetworkError', 'MongoNetworkTimeoutError'])('maps %s to network_error', (name) => {
+    expect(mapError(named(name, 'socket hang up'))).toEqual({
+      code: 'network_error',
+      message: 'socket hang up'
+    })
+  })
+
+  it('recognises authentication failures by name, code 18, code 13 and message', () => {
+    expect(mapError(named('MongoAuthenticationError')).code).toBe('auth_failed')
+    expect(mapError(named('MongoServerError', 'x', { code: 18 })).code).toBe('auth_failed')
+    expect(mapError(named('MongoServerError', 'x', { code: 13 })).code).toBe('auth_failed')
+    expect(mapError(new Error('Authentication failed.')).code).toBe('auth_failed')
+  })
+
+  it('maps MongoServerError to driver_error with its numeric code', () => {
+    expect(mapError(named('MongoServerError', 'ns not found', { code: 26 }))).toEqual({
+      code: 'driver_error',
+      message: 'ns not found',
+      details: { mongoCode: 26 }
+    })
+  })
+
+  it('maps MongoWriteConcernError to driver_error with its numeric code', () => {
+    expect(
+      mapError(named('MongoWriteConcernError', 'waiting for replication timed out', { code: 64 }))
+    ).toEqual({
+      code: 'driver_error',
+      message: 'waiting for replication timed out',
+      details: { mongoCode: 64 }
+    })
+  })
+
+  it('omits details for a MongoServerError without a numeric code', () => {
+    expect(mapError(named('MongoServerError', 'odd', { code: 'Location1' }))).toEqual({
+      code: 'driver_error',
+      message: 'odd',
+      details: undefined
+    })
+  })
+})
+
+describe('mapError — MongoBulkWriteError', () => {
+  it('says how many documents an ordered insertMany kept before failing', () => {
+    const mapped = mapError(bulkWriteError(49))
+    expect(mapped.code).toBe('driver_error')
+    expect(mapped.message).toContain('E11000 duplicate key error')
+    expect(mapped.message).toContain('49 documents were inserted')
+    expect(mapped.details).toEqual({ mongoCode: 11000, insertedCount: 49 })
+  })
+
+  it('uses the singular for one inserted document', () => {
+    expect(mapError(bulkWriteError(1)).message).toContain('1 document was inserted')
+  })
+
+  it('keeps the driver message unchanged when nothing was inserted', () => {
+    expect(mapError(bulkWriteError(0))).toEqual({
+      code: 'driver_error',
+      message: 'E11000 duplicate key error collection: app.users index: _id_',
+      details: { mongoCode: 11000, insertedCount: 0 }
+    })
+  })
+
+  it('reports every non-zero counter of a partial bulkWrite', () => {
+    const error = new MongoBulkWriteError({ message: 'E11000 duplicate key error', code: 11000 }, {
+      insertedCount: 1,
+      matchedCount: 4,
+      modifiedCount: 3,
+      deletedCount: 2,
+      upsertedCount: 1
+    } as unknown as BulkWriteResult)
+    expect(mapError(error).message).toBe(
+      'E11000 duplicate key error — 1 document was inserted, 4 matched, 3 modified, 2 deleted and 1 upserted before this error'
+    )
+  })
+
+  it('leaves zero counters out and names the documents with the first one left', () => {
+    const error = new MongoBulkWriteError({ message: 'E11000 duplicate key error', code: 11000 }, {
+      insertedCount: 0,
+      matchedCount: 0,
+      modifiedCount: 1,
+      deletedCount: 2,
+      upsertedCount: 0
+    } as unknown as BulkWriteResult)
+    expect(mapError(error).message).toBe(
+      'E11000 duplicate key error — 1 document was modified and 2 deleted before this error'
+    )
+  })
+
+  it('reports documents that only matched', () => {
+    const error = new MongoBulkWriteError({ message: 'E11000 duplicate key error', code: 11000 }, {
+      insertedCount: 0,
+      matchedCount: 5,
+      modifiedCount: 0
+    } as unknown as BulkWriteResult)
+    expect(mapError(error).message).toBe(
+      'E11000 duplicate key error — 5 documents were matched before this error'
+    )
+  })
+
+  it('keeps the driver message unchanged when every counter is zero', () => {
+    const error = new MongoBulkWriteError({ message: 'E11000 duplicate key error', code: 11000 }, {
+      insertedCount: 0,
+      matchedCount: 0,
+      modifiedCount: 0,
+      deletedCount: 0,
+      upsertedCount: 0
+    } as unknown as BulkWriteResult)
+    expect(mapError(error)).toEqual({
+      code: 'driver_error',
+      message: 'E11000 duplicate key error',
+      details: { mongoCode: 11000, insertedCount: 0 }
+    })
+  })
+})
+
+describe('mapError — fallbacks', () => {
+  it('maps an unknown Error to internal with its message', () => {
+    expect(mapError(named('Socks5ProtocolError', 'bad reply'))).toEqual({
+      code: 'internal',
+      message: 'bad reply'
+    })
+  })
+
+  it('maps a non-Error value to internal and carries it as details', () => {
+    expect(mapError('kaputt')).toEqual({
+      code: 'internal',
+      message: 'Unknown error',
+      details: 'kaputt'
+    })
+  })
+})
diff --git a/src/main/lib/errorMap.ts b/src/main/lib/errorMap.ts
index 9266c58..1929270 100644
--- a/src/main/lib/errorMap.ts
+++ b/src/main/lib/errorMap.ts
@@ -1,5 +1,19 @@
 import type { ErrorCode } from '@shared/result'
 
+/** An error `mapError` reports as `validation_error`: the request itself is invalid. */
+export function validationError(message: string): Error {
+  const e = new Error(message)
+  e.name = 'ValidationError'
+  return e
+}
+
+/** An error `mapError` reports as `cancelled`: the user stopped the operation, nothing failed. */
+export function cancelledError(message: string): Error {
+  const e = new Error(message)
+  e.name = 'CancelledError'
+  return e
+}
+
 /**
  * Map a thrown error (driver, filesystem, validation) to one of our
  * internal `ErrorCode`s. This is the only place that should pattern-match
@@ -9,29 +23,15 @@ export function mapError(error: unknown): { code: ErrorCode; message: string; de
   if (error instanceof Error) {
     const name = error.name
     const message = error.message
-    const code = readCodeField(error)
+    const code = readNumberField(error, 'code')
 
-    // SSH failures come before the driver checks: when a tunnel cannot be
+    // Tunnel failures come before the driver checks: when a tunnel cannot be
     // opened the driver never runs, and reporting "server selection timed out"
-    // for a rejected SSH key would point at the wrong end of the problem.
-    if (name === 'SshHostKeyMismatchError') {
-      return { code: 'ssh_host_key_mismatch', message }
-    }
-
-    if (name === 'SshAuthError') {
-      return { code: 'ssh_auth_failed', message }
-    }
-
-    if (name === 'SshConnectError') {
-      return { code: 'ssh_connect_failed', message }
-    }
-
-    if (name === 'MongoServerSelectionError') {
-      return { code: 'server_selection_timeout', message }
-    }
-
-    if (name === 'MongoNetworkError' || name === 'MongoNetworkTimeoutError') {
-      return { code: 'network_error', message }
+    // for a rejected SSH key or a cloudflared that never started would point
+    // at the wrong end of the problem.
+    const named = CODE_BY_NAME.get(name)
+    if (named !== undefined) {
+      return { code: named, message }
     }
 
     if (
@@ -43,7 +43,21 @@ export function mapError(error: unknown): { code: ErrorCode; message: string; de
       return { code: 'auth_failed', message }
     }
 
-    if (name === 'MongoServerError' || name === 'MongoBulkWriteError') {
+    // A failed insertMany / bulkWrite keeps earlier writes; saying so prevents a duplicating retry.
+    if (name === 'MongoBulkWriteError') {
+      const insertedCount = readNumberField(error, 'insertedCount')
+      const progress = bulkProgress(error)
+      return {
+        code: 'driver_error',
+        message: progress === null ? message : `${message} — ${progress} before this error`,
+        details: {
+          ...(code !== null ? { mongoCode: code } : {}),
+          ...(insertedCount !== null ? { insertedCount } : {})
+        }
+      }
+    }
+
+    if (name === 'MongoServerError' || name === 'MongoWriteConcernError') {
       return {
         code: 'driver_error',
         message,
@@ -73,7 +87,45 @@ export function mapError(error: unknown): { code: ErrorCode; message: string; de
   return { code: 'internal', message: 'Unknown error', details: error }
 }
 
-function readCodeField(error: Error): number | null {
-  const code = (error as { code?: unknown }).code
-  return typeof code === 'number' ? code : null
+const CODE_BY_NAME: ReadonlyMap<string, ErrorCode> = new Map([
+  ['SshHostKeyMismatchError', 'ssh_host_key_mismatch'],
+  ['SshAuthError', 'ssh_auth_failed'],
+  ['SshConnectError', 'ssh_connect_failed'],
+  ['CloudflaredNotFoundError', 'cloudflared_not_found'],
+  ['CloudflaredAuthError', 'cloudflared_auth_failed'],
+  ['CloudflaredTunnelError', 'cloudflared_failed'],
+  ['CancelledError', 'cancelled'],
+  ['NotConnectedError', 'not_connected'],
+  ['MongoServerSelectionError', 'server_selection_timeout'],
+  ['MongoNetworkError', 'network_error'],
+  ['MongoNetworkTimeoutError', 'network_error']
+])
+
+const BULK_COUNTS = [
+  ['insertedCount', 'inserted'],
+  ['matchedCount', 'matched'],
+  ['modifiedCount', 'modified'],
+  ['deletedCount', 'deleted'],
+  ['upsertedCount', 'upserted']
+] as const
+
+type CountField = (typeof BULK_COUNTS)[number][0]
+
+// "1 document was inserted, 3 matched and 2 deleted", or null when every counter is zero.
+function bulkProgress(error: Error): string | null {
+  const parts = BULK_COUNTS.flatMap(([field, verb]) => {
+    const count = readNumberField(error, field)
+    return count !== null && count > 0 ? [{ count, verb }] : []
+  })
+  const [first, ...rest] = parts
+  if (first === undefined) return null
+  const head = `${first.count} document${first.count === 1 ? ' was' : 's were'} ${first.verb}`
+  const tail = rest.map(({ count, verb }) => `${count} ${verb}`)
+  const last = tail.pop()
+  return last === undefined ? head : `${[head, ...tail].join(', ')} and ${last}`
+}
+
+function readNumberField(error: Error, field: 'code' | CountField): number | null {
+  const value = (error as unknown as Record<string, unknown>)[field]
+  return typeof value === 'number' ? value : null
 }
diff --git a/src/main/lib/externalUrl.test.ts b/src/main/lib/externalUrl.test.ts
new file mode 100644
index 0000000..e9c1d8c
--- /dev/null
+++ b/src/main/lib/externalUrl.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { opensInBrowser } from './externalUrl'
+
+describe('opensInBrowser', () => {
+  it('lets an https URL go to the browser', () => {
+    expect(
+      opensInBrowser('https://mongo.example.com/cdn-cgi/access/cli?aud=abc&redirect_url=x')
+    ).toBe(true)
+  })
+
+  it.each([
+    ['plain http', 'http://example.com/'],
+    ['a file URL', 'file:///C:/Windows/System32/calc.exe'],
+    ['a UNC file URL', 'file://attacker.invalid/share/payload.exe'],
+    ['a protocol handler', 'ms-msdt:/id PCWDiagnostic'],
+    ['a search handler', 'search-ms:query=x&crumb=location:\\\\attacker.invalid\\share'],
+    ['script', 'javascript:alert(1)'],
+    ['a bare UNC path', '\\\\attacker.invalid\\share\\payload.exe'],
+    ['an unparseable string', 'not a url']
+  ])('keeps %s away from the operating system', (_case, url) => {
+    expect(opensInBrowser(url)).toBe(false)
+  })
+})
diff --git a/src/main/lib/externalUrl.ts b/src/main/lib/externalUrl.ts
new file mode 100644
index 0000000..466803f
--- /dev/null
+++ b/src/main/lib/externalUrl.ts
@@ -0,0 +1,4 @@
+/** True when main may hand `url` to `shell.openExternal`, which starts whatever handles its scheme: https only. */
+export function opensInBrowser(url: string): boolean {
+  return URL.parse(url)?.protocol === 'https:'
+}
diff --git a/src/main/lib/indexStats.test.ts b/src/main/lib/indexStats.test.ts
new file mode 100644
index 0000000..ae8b966
--- /dev/null
+++ b/src/main/lib/indexStats.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it } from 'vitest'
+import { Long } from 'bson'
+import { buildIndexStatsReport, classifyStatsError } from './indexStats'
+
+type RawDocs = Array<Record<string, unknown>>
+
+const SINCE = new Date('2026-10-01T08:00:00.000Z')
+
+function fulfilled(value: RawDocs): PromiseSettledResult<RawDocs> {
+  return { status: 'fulfilled', value }
+}
+
+function rejected(reason: unknown): PromiseSettledResult<RawDocs> {
+  return { status: 'rejected', reason }
+}
+
+function serverError(message: string, code: number): Error {
+  return Object.assign(new Error(message), { code })
+}
+
+function usageDoc(name: string, ops: unknown, extra: Record<string, unknown> = {}) {
+  return { name, key: { a: 1 }, host: 'db1:27017', accesses: { ops, since: SINCE }, ...extra }
+}
+
+function storageDoc(indexSizes: Record<string, unknown>, extra: Record<string, unknown> = {}) {
+  return { ns: 'app.players', storageStats: { indexSizes, ...extra } }
+}
+
+describe('buildIndexStatsReport', () => {
+  it('turns a single host into ISO samples and merges sizes', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([usageDoc('_id_', 12), usageDoc('name_1', 0)]),
+      fulfilled([storageDoc({ _id_: 4096, name_1: 2048 })])
+    )
+
+    expect(report).toEqual({
+      indexes: [
+        {
+          name: '_id_',
+          size: 4096,
+          building: false,
+          usage: [{ host: 'db1:27017', ops: 12, since: '2026-10-01T08:00:00.000Z' }]
+        },
+        {
+          name: 'name_1',
+          size: 2048,
+          building: false,
+          usage: [{ host: 'db1:27017', ops: 0, since: '2026-10-01T08:00:00.000Z' }]
+        }
+      ],
+      usageUnavailable: null,
+      storageUnavailable: null
+    })
+    expect(report.indexes[0]?.usage[0]).not.toHaveProperty('shard')
+  })
+
+  it('converts Long and bigint counters to numbers', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([
+        usageDoc('a_1', Long.fromNumber(3)),
+        usageDoc('b_1', Long.fromString('9007199254740993')),
+        usageDoc('c_1', 5n)
+      ]),
+      fulfilled([])
+    )
+
+    expect(report.indexes.map((i) => i.usage[0]?.ops)).toEqual([3, 9007199254740992, 5])
+  })
+
+  it('keeps one sample per shard in input order and sums sizes across shards', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([
+        usageDoc('name_1', 7, { host: 'a1:27018', shard: 'shard-a' }),
+        usageDoc('name_1', 9, { host: 'b1:27018', shard: 'shard-b' })
+      ]),
+      fulfilled([
+        storageDoc({ name_1: 1000 }, { shard: 'shard-a' }),
+        storageDoc({ name_1: 1500 }, { shard: 'shard-b' })
+      ])
+    )
+
+    expect(report.indexes).toEqual([
+      {
+        name: 'name_1',
+        size: 2500,
+        building: false,
+        usage: [
+          { host: 'a1:27018', shard: 'shard-a', ops: 7, since: '2026-10-01T08:00:00.000Z' },
+          { host: 'b1:27018', shard: 'shard-b', ops: 9, since: '2026-10-01T08:00:00.000Z' }
+        ]
+      }
+    ])
+  })
+
+  it('marks an index building from $indexStats', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([usageDoc('name_1', 0, { building: true })]),
+      fulfilled([])
+    )
+
+    expect(report.indexes[0]?.building).toBe(true)
+  })
+
+  it('marks an index building from indexBuilds even when usage was rejected', () => {
+    const report = buildIndexStatsReport(
+      rejected(serverError('not authorized', 13)),
+      fulfilled([storageDoc({ _id_: 4096, x_1: 0 }, { indexBuilds: ['x_1'] })])
+    )
+
+    expect(report.indexes).toEqual([
+      { name: '_id_', size: 4096, building: false, usage: [] },
+      { name: 'x_1', size: 0, building: true, usage: [] }
+    ])
+  })
+
+  it('skips a usage document without a name', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([{ key: { a: 1 }, host: 'db1:27017', accesses: { ops: 1, since: SINCE } }]),
+      fulfilled([])
+    )
+
+    expect(report.indexes).toEqual([])
+  })
+
+  it('keeps the entry but drops the sample of a malformed usage document', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([
+        {
+          name: 'string_since',
+          host: 'db1:27017',
+          accesses: { ops: 1, since: SINCE.toISOString() }
+        },
+        { name: 'no_accesses', host: 'db1:27017' },
+        usageDoc('bad_ops', 'x'),
+        usageDoc('no_host', 1, { host: 42 }),
+        usageDoc('invalid_date', 1, { accesses: { ops: 1, since: new Date(Number.NaN) } })
+      ]),
+      fulfilled([])
+    )
+
+    expect(report.indexes).toEqual([
+      { name: 'string_since', building: false, usage: [] },
+      { name: 'no_accesses', building: false, usage: [] },
+      { name: 'bad_ops', building: false, usage: [] },
+      { name: 'no_host', building: false, usage: [] },
+      { name: 'invalid_date', building: false, usage: [] }
+    ])
+  })
+
+  it('skips a non-numeric index size', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([]),
+      fulfilled([storageDoc({ _id_: 'large', name_1: 2048 })])
+    )
+
+    expect(report.indexes).toEqual([{ name: 'name_1', size: 2048, building: false, usage: [] }])
+  })
+
+  it('reports usage as unauthorized on code 13 and still returns sizes', () => {
+    const report = buildIndexStatsReport(
+      rejected(serverError('not authorized on app to execute command', 13)),
+      fulfilled([storageDoc({ _id_: 4096 })])
+    )
+
+    expect(report.usageUnavailable).toEqual({
+      reason: 'unauthorized',
+      message: 'not authorized on app to execute command'
+    })
+    expect(report.storageUnavailable).toBeNull()
+    expect(report.indexes).toEqual([{ name: '_id_', size: 4096, building: false, usage: [] }])
+  })
+
+  it('reports storage as unsupported on code 166 and still returns usage', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([usageDoc('_id_', 3)]),
+      rejected(serverError('Namespace app.v is a view, not a collection', 166))
+    )
+
+    expect(report.storageUnavailable).toEqual({
+      reason: 'unsupported',
+      message: 'Namespace app.v is a view, not a collection'
+    })
+    expect(report.usageUnavailable).toBeNull()
+    expect(report.indexes).toEqual([
+      {
+        name: '_id_',
+        building: false,
+        usage: [{ host: 'db1:27017', ops: 3, since: '2026-10-01T08:00:00.000Z' }]
+      }
+    ])
+  })
+
+  it('does not throw when both sources are rejected', () => {
+    const report = buildIndexStatsReport(rejected(new Error('boom')), rejected('down'))
+
+    expect(report).toEqual({
+      indexes: [],
+      usageUnavailable: { reason: 'failed', message: 'boom' },
+      storageUnavailable: { reason: 'failed', message: 'down' }
+    })
+  })
+
+  it('creates an entry for a name only $collStats reports', () => {
+    const report = buildIndexStatsReport(
+      fulfilled([usageDoc('_id_', 1)]),
+      fulfilled([storageDoc({ _id_: 4096, fresh_1: 1024 })])
+    )
+
+    expect(report.indexes[1]).toEqual({ name: 'fresh_1', size: 1024, building: false, usage: [] })
+  })
+
+  it('merges an index named __proto__ like any other', () => {
+    const indexSizes: Record<string, unknown> = {}
+    Object.defineProperty(indexSizes, '__proto__', {
+      value: 256,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    })
+
+    const report = buildIndexStatsReport(
+      fulfilled([usageDoc('__proto__', 2)]),
+      fulfilled([storageDoc(indexSizes)])
+    )
+
+    expect(report.indexes).toEqual([
+      {
+        name: '__proto__',
+        size: 256,
+        building: false,
+        usage: [{ host: 'db1:27017', ops: 2, since: '2026-10-01T08:00:00.000Z' }]
+      }
+    ])
+  })
+})
+
+describe('classifyStatsError', () => {
+  it.each([115, 166, 40324])('reports code %i as unsupported', (code) => {
+    expect(classifyStatsError(serverError('nope', code))).toEqual({
+      reason: 'unsupported',
+      message: 'nope'
+    })
+  })
+
+  it('reports code 13 as unauthorized', () => {
+    expect(classifyStatsError(serverError('not authorized', 13)).reason).toBe('unauthorized')
+  })
+
+  it.each([
+    ['another server code', serverError('boom', 2)],
+    ['an Error without a code', new Error('boom')],
+    ['a thrown string', 'boom']
+  ])('reports %s as failed and keeps the message', (_label, error) => {
+    expect(classifyStatsError(error)).toEqual({ reason: 'failed', message: 'boom' })
+  })
+})
diff --git a/src/main/lib/indexStats.ts b/src/main/lib/indexStats.ts
new file mode 100644
index 0000000..24e0ae5
--- /dev/null
+++ b/src/main/lib/indexStats.ts
@@ -0,0 +1,98 @@
+import { Long } from 'bson'
+import type {
+  IndexRuntimeStats,
+  IndexStatsReport,
+  IndexStatsUnavailable,
+  IndexUsageSample
+} from '@shared/types'
+import { isDocument } from '@shared/writeOps'
+import { storageParts, sumIndexSizes } from './storageStats'
+
+type RawDocs = ReadonlyArray<Record<string, unknown>>
+
+const UNSUPPORTED_CODES = new Set([
+  115, // CommandNotSupported
+  166, // CommandNotSupportedOnView
+  40324 // Unrecognized pipeline stage name: servers/emulators without $indexStats
+])
+
+/** Merges `$indexStats` and `$collStats` output into one entry per index name; never throws. */
+export function buildIndexStatsReport(
+  usage: PromiseSettledResult<RawDocs>,
+  storage: PromiseSettledResult<RawDocs>
+): IndexStatsReport {
+  // A Map, not an object: an index may be named "__proto__".
+  const entries = new Map<string, IndexRuntimeStats>()
+  const entry = (name: string): IndexRuntimeStats => {
+    let stats = entries.get(name)
+    if (!stats) {
+      stats = { name, building: false, usage: [] }
+      entries.set(name, stats)
+    }
+    return stats
+  }
+
+  if (usage.status === 'fulfilled') {
+    for (const doc of usage.value) {
+      const name = doc['name']
+      if (typeof name !== 'string') continue
+      const stats = entry(name)
+      if (doc['building'] === true) stats.building = true
+      const sample = usageSample(doc)
+      if (sample) stats.usage.push(sample)
+    }
+  }
+
+  if (storage.status === 'fulfilled') {
+    const parts = storageParts(storage.value)
+    for (const [name, size] of Object.entries(sumIndexSizes(parts))) entry(name).size = size
+    for (const part of parts) {
+      const builds = part['indexBuilds']
+      if (!Array.isArray(builds)) continue
+      for (const name of builds) {
+        if (typeof name === 'string') entry(name).building = true
+      }
+    }
+  }
+
+  return {
+    indexes: [...entries.values()],
+    usageUnavailable: usage.status === 'rejected' ? classifyStatsError(usage.reason) : null,
+    storageUnavailable: storage.status === 'rejected' ? classifyStatsError(storage.reason) : null
+  }
+}
+
+/** Maps a failed stats read to a reason the UI can explain; `message` keeps the server text. */
+export function classifyStatsError(error: unknown): IndexStatsUnavailable {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = isDocument(error) && typeof error['code'] === 'number' ? error['code'] : null
+  if (code === 13) return { reason: 'unauthorized', message }
+  if (code !== null && UNSUPPORTED_CODES.has(code)) return { reason: 'unsupported', message }
+  return { reason: 'failed', message }
+}
+
+function usageSample(doc: Record<string, unknown>): IndexUsageSample | undefined {
+  const host = doc['host']
+  const accesses = doc['accesses']
+  if (typeof host !== 'string' || !isDocument(accesses)) return undefined
+  const ops = toSafeNumber(accesses['ops'])
+  const since = accesses['since']
+  if (ops === undefined || !(since instanceof Date) || Number.isNaN(since.getTime())) {
+    return undefined
+  }
+  const shard = doc['shard']
+  return {
+    host,
+    ...(typeof shard === 'string' ? { shard } : {}),
+    ops,
+    since: since.toISOString()
+  }
+}
+
+function toSafeNumber(value: unknown): number | undefined {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : undefined
+  if (typeof value === 'bigint') return Number(value)
+  // The driver promotes Longs to numbers only while they fit in 53 bits.
+  if (Long.isLong(value)) return value.toNumber()
+  return undefined
+}
diff --git a/src/main/lib/knownHosts.test.ts b/src/main/lib/knownHosts.test.ts
index 46bc999..9858a94 100644
--- a/src/main/lib/knownHosts.test.ts
+++ b/src/main/lib/knownHosts.test.ts
@@ -1,5 +1,13 @@
 import { describe, expect, it } from 'vitest'
-import { fingerprint, findHostKeys, keyMatches, parseKnownHosts } from './knownHosts'
+import {
+  fingerprint,
+  findHostKeys,
+  isRevoked,
+  keyMatches,
+  keyTypeOf,
+  orderHostKeyAlgorithms,
+  parseKnownHosts
+} from './knownHosts'
 
 // Real ed25519 key plus the two hashed lines OpenSSH itself produced for it
 // via `ssh-keygen -H`, so the HMAC matching is checked against the reference
@@ -15,20 +23,51 @@ const OTHER_KEY = Buffer.from(
   'base64'
 )
 
+const RSA_KEY = Buffer.from(
+  'AAAAB3NzaC1yc2EAAAADAQABAAAAgQC/gX/7WgOQ6kBJXm40rYn/ObaTIBNCWsuJI/6S/wSImH72Nfe2K50W7fBtgBtvhfhY9b56Mfhzh/jXNBdjJtKXjfjRPS2004BGz2jsaLdKeviBryT/jbo4tEX4SA/+NDKlIUwXb5TgSzN+7yTNcCNTdC0zsU77JVcOEgxyu5jYiQ==',
+  'base64'
+)
+const ECDSA_KEY = Buffer.from(
+  'AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCXAVIxb/s+tZzJwt47GTXuciOdpToANn3jirNMDAYBn0pFQlw0DJ0dTMFgTO8GN36IeBxjU159s/yYS5CmVk7g=',
+  'base64'
+)
+
+/** ssh2's own default order on a runtime with ed25519 support. */
+const SSH2_DEFAULTS = [
+  'ssh-ed25519',
+  'ecdsa-sha2-nistp256',
+  'ecdsa-sha2-nistp384',
+  'ecdsa-sha2-nistp521',
+  'rsa-sha2-512',
+  'rsa-sha2-256',
+  'ssh-rsa'
+] as const
+
 describe('parseKnownHosts', () => {
-  it('skips comments, blank lines and marker lines', () => {
+  it('skips comments, blank lines and @cert-authority lines', () => {
     const entries = parseKnownHosts(
       [
         '# a comment',
         '',
         '   ',
         `@cert-authority *.example.com ssh-ed25519 ${KEY_BASE64}`,
-        `@revoked gate.example.com ssh-ed25519 ${KEY_BASE64}`,
         `gate.example.com ssh-ed25519 ${KEY_BASE64}`
       ].join('\n')
     )
     expect(entries).toHaveLength(1)
     expect(entries[0]?.keyType).toBe('ssh-ed25519')
+    expect(entries[0]?.revoked).toBe(false)
+  })
+
+  it('keeps an @revoked line as a revoked entry', () => {
+    const entries = parseKnownHosts(`@revoked * ssh-ed25519 ${KEY_BASE64}`)
+    expect(entries).toHaveLength(1)
+    expect(entries[0]?.revoked).toBe(true)
+    expect(entries[0]?.key).toEqual(KEY)
+  })
+
+  it('skips lines with an unknown marker', () => {
+    expect(parseKnownHosts(`@unknown gate.example.com ssh-ed25519 ${KEY_BASE64}`)).toEqual([])
   })
 
   it('reads several patterns off one line', () => {
@@ -106,6 +145,96 @@ describe('findHostKeys', () => {
     )
     expect(findHostKeys(entries, 'gate.example.com', 22)).toHaveLength(2)
   })
+
+  it('never returns a revoked key', () => {
+    const entries = parseKnownHosts(
+      [
+        `@revoked gate.example.com ssh-ed25519 ${KEY_BASE64}`,
+        `gate.example.com ssh-ed25519 ${OTHER_KEY.toString('base64')}`
+      ].join('\n')
+    )
+    expect(findHostKeys(entries, 'gate.example.com', 22)).toEqual([OTHER_KEY])
+  })
+})
+
+describe('isRevoked', () => {
+  it('applies a wildcard revocation to any host presenting that key', () => {
+    const entries = parseKnownHosts(`@revoked * ssh-ed25519 ${KEY_BASE64}`)
+    expect(isRevoked(entries, 'gate.example.com', 22, KEY)).toBe(true)
+    expect(isRevoked(entries, 'other.example.org', 2222, KEY)).toBe(true)
+  })
+
+  it('does not apply to a different key', () => {
+    const entries = parseKnownHosts(`@revoked * ssh-ed25519 ${KEY_BASE64}`)
+    expect(isRevoked(entries, 'gate.example.com', 22, OTHER_KEY)).toBe(false)
+  })
+
+  it('only applies to hosts its patterns match', () => {
+    const entries = parseKnownHosts(`@revoked gate.example.com ssh-ed25519 ${KEY_BASE64}`)
+    expect(isRevoked(entries, 'gate.example.com', 22, KEY)).toBe(true)
+    expect(isRevoked(entries, 'other.example.com', 22, KEY)).toBe(false)
+  })
+
+  it('ignores plain entries carrying the same key', () => {
+    const entries = parseKnownHosts(`gate.example.com ssh-ed25519 ${KEY_BASE64}`)
+    expect(isRevoked(entries, 'gate.example.com', 22, KEY)).toBe(false)
+  })
+})
+
+describe('keyTypeOf', () => {
+  it('reads the type name of an ed25519 blob', () => {
+    expect(keyTypeOf(KEY)).toBe('ssh-ed25519')
+  })
+
+  it('reads the type name of an RSA blob', () => {
+    expect(keyTypeOf(RSA_KEY)).toBe('ssh-rsa')
+  })
+
+  it('reads the type name of an ECDSA blob', () => {
+    expect(keyTypeOf(ECDSA_KEY)).toBe('ecdsa-sha2-nistp256')
+  })
+
+  it('returns null for a blob cut off inside the type name', () => {
+    expect(keyTypeOf(KEY.subarray(0, 8))).toBeNull()
+  })
+
+  it('returns null for a blob too short to hold a length', () => {
+    expect(keyTypeOf(Buffer.from([0, 0]))).toBeNull()
+  })
+})
+
+describe('orderHostKeyAlgorithms', () => {
+  it('puts every RSA signature algorithm first for a known ssh-rsa key', () => {
+    expect(orderHostKeyAlgorithms(['ssh-rsa'], SSH2_DEFAULTS)).toEqual([
+      'rsa-sha2-512',
+      'rsa-sha2-256',
+      'ssh-rsa',
+      'ssh-ed25519',
+      'ecdsa-sha2-nistp256',
+      'ecdsa-sha2-nistp384',
+      'ecdsa-sha2-nistp521'
+    ])
+  })
+
+  it('keeps the default order among several known types', () => {
+    expect(orderHostKeyAlgorithms(['ssh-rsa', 'ecdsa-sha2-nistp384'], SSH2_DEFAULTS)).toEqual([
+      'ecdsa-sha2-nistp384',
+      'rsa-sha2-512',
+      'rsa-sha2-256',
+      'ssh-rsa',
+      'ssh-ed25519',
+      'ecdsa-sha2-nistp256',
+      'ecdsa-sha2-nistp521'
+    ])
+  })
+
+  it('keeps the defaults when no type is known', () => {
+    expect(orderHostKeyAlgorithms([], SSH2_DEFAULTS)).toEqual([...SSH2_DEFAULTS])
+  })
+
+  it('ignores known types the defaults do not offer', () => {
+    expect(orderHostKeyAlgorithms(['ssh-dss'], SSH2_DEFAULTS)).toEqual([...SSH2_DEFAULTS])
+  })
 })
 
 describe('keyMatches', () => {
diff --git a/src/main/lib/knownHosts.ts b/src/main/lib/knownHosts.ts
index b84dcfd..f6ceda4 100644
--- a/src/main/lib/knownHosts.ts
+++ b/src/main/lib/knownHosts.ts
@@ -4,14 +4,17 @@
  * client is trusted here too. Pure — the caller supplies the contents.
  *
  * Supported: plain patterns (with `*` / `?` wildcards and `!` negation), the
- * `[host]:port` form, and `|1|salt|hash` hashed entries. `@cert-authority` and
- * `@revoked` lines are skipped; we do not implement CA validation, and
- * skipping is the safe direction since such a line then authorises nothing.
+ * `[host]:port` form, `|1|salt|hash` hashed entries, and `@revoked` lines,
+ * whose key is refused for every host they match. `@cert-authority` lines are
+ * skipped; we do not implement CA validation, and skipping is the safe
+ * direction since such a line then authorises nothing.
  */
 
 import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
 import { DEFAULT_SSH_PORT } from '@shared/types'
 
+const REVOKED_MARKER = '@revoked'
+
 export type HostMatcher =
   | { kind: 'plain'; pattern: string; negated: boolean }
   | { kind: 'hashed'; salt: Buffer; digest: Buffer }
@@ -21,16 +24,21 @@ export type KnownHostEntry = {
   /** e.g. `ssh-ed25519`. Diagnostics only; matching goes by key bytes. */
   keyType: string
   key: Buffer
+  /** From an `@revoked` line: the key is refused, never authorised. */
+  revoked: boolean
 }
 
 export function parseKnownHosts(content: string): KnownHostEntry[] {
   const entries: KnownHostEntry[] = []
   for (const rawLine of content.split(/\r?\n/)) {
     const line = rawLine.trim()
-    if (line.length === 0 || line.startsWith('#') || line.startsWith('@')) continue
+    if (line.length === 0 || line.startsWith('#')) continue
 
-    const [hostField, keyType, keyBase64] = line.split(/\s+/)
+    const fields = line.split(/\s+/)
+    const revoked = fields[0] === REVOKED_MARKER
+    const [hostField, keyType, keyBase64] = revoked ? fields.slice(1) : fields
     if (hostField === undefined || keyType === undefined || keyBase64 === undefined) continue
+    if (hostField.startsWith('@')) continue
 
     const key = Buffer.from(keyBase64, 'base64')
     if (key.length === 0) continue
@@ -38,7 +46,7 @@ export function parseKnownHosts(content: string): KnownHostEntry[] {
     const hosts = hostField.split(',').flatMap(parseMatcher)
     if (hosts.length === 0) continue
 
-    entries.push({ hosts, keyType, key })
+    entries.push({ hosts, keyType, key, revoked })
   }
   return entries
 }
@@ -75,11 +83,24 @@ export function findHostKeys(entries: KnownHostEntry[], host: string, port: numb
   const names = candidateNames(host, port)
   const keys: Buffer[] = []
   for (const entry of entries) {
-    if (entryMatches(entry, names)) keys.push(entry.key)
+    if (!entry.revoked && entryMatches(entry, names)) keys.push(entry.key)
   }
   return keys
 }
 
+/** Whether an `@revoked` line that matches this host lists `key`. */
+export function isRevoked(
+  entries: KnownHostEntry[],
+  host: string,
+  port: number,
+  key: Buffer
+): boolean {
+  const names = candidateNames(host, port)
+  return entries.some(
+    (entry) => entry.revoked && keyMatches(key, entry.key) && entryMatches(entry, names)
+  )
+}
+
 function entryMatches(entry: KnownHostEntry, names: string[]): boolean {
   let matched = false
   for (const matcher of entry.hosts) {
@@ -119,3 +140,29 @@ export function keyMatches(candidate: Buffer, known: Buffer): boolean {
 export function fingerprint(key: Buffer): string {
   return `SHA256:${createHash('sha256').update(key).digest('base64').replace(/=+$/, '')}`
 }
+
+/** The type name a public key blob starts with, e.g. `ssh-rsa`; null for a malformed blob. */
+export function keyTypeOf(blob: Buffer): string | null {
+  if (blob.length < 4) return null
+  const end = 4 + blob.readUInt32BE(0)
+  return end <= blob.length ? blob.toString('ascii', 4, end) : null
+}
+
+/**
+ * `defaults` with the algorithms of already trusted key types moved to the front, as OpenSSH does.
+ * @param knownTypes key types (as `keyTypeOf` reads them) the host is trusted with.
+ * @param defaults host key algorithms in preference order.
+ * @returns the same algorithms; both groups keep their order from `defaults`.
+ */
+export function orderHostKeyAlgorithms<T extends string>(
+  knownTypes: readonly string[],
+  defaults: readonly T[]
+): T[] {
+  const known = (algorithm: T): boolean => knownTypes.includes(algorithmKeyType(algorithm))
+  return [...defaults.filter(known), ...defaults.filter((algorithm) => !known(algorithm))]
+}
+
+// RSA keys also sign under the rsa-sha2-* names (RFC 8332), but their blob always says ssh-rsa.
+function algorithmKeyType(algorithm: string): string {
+  return algorithm.startsWith('rsa-sha2-') ? 'ssh-rsa' : algorithm
+}
diff --git a/src/main/lib/socks5.test.ts b/src/main/lib/socks5.test.ts
index 4988f60..82b2c30 100644
--- a/src/main/lib/socks5.test.ts
+++ b/src/main/lib/socks5.test.ts
@@ -1,6 +1,7 @@
-import type { Socket } from 'node:net'
+import { once } from 'node:events'
+import { createConnection, type Socket } from 'node:net'
 import { PassThrough } from 'node:stream'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { SocksClient } from 'socks'
 import { createSocks5Server, type Socks5Server } from './socks5'
 
@@ -22,7 +23,8 @@ type Requested = { host: string; port: number }
  */
 async function startProxy(
   requested: Requested[],
-  connect?: (host: string, port: number) => Promise<PassThrough>
+  connect?: (host: string, port: number) => Promise<PassThrough>,
+  onError?: (error: Error) => void
 ): Promise<Socks5Server> {
   server = await createSocks5Server({
     username: USERNAME,
@@ -30,11 +32,37 @@ async function startProxy(
     connect: (host, port) => {
       requested.push({ host, port })
       return connect ? connect(host, port) : Promise.resolve(new PassThrough())
-    }
+    },
+    onError
   })
   return server
 }
 
+/**
+ * Sends greeting, credentials and CONNECT in one write and never reads the
+ * replies, so the test holds the raw socket while the outbound leg is pending.
+ */
+async function sendConnectRequest(proxyPort: number, destination: Requested): Promise<Socket> {
+  const socket = createConnection({ host: '127.0.0.1', port: proxyPort })
+  await once(socket, 'connect')
+  const host = Buffer.from(destination.host, 'utf8')
+  const port = Buffer.alloc(2)
+  port.writeUInt16BE(destination.port)
+  socket.write(
+    Buffer.concat([
+      Buffer.from([0x05, 0x01, 0x02]),
+      Buffer.from([0x01, USERNAME.length]),
+      Buffer.from(USERNAME, 'utf8'),
+      Buffer.from([PASSWORD.length]),
+      Buffer.from(PASSWORD, 'utf8'),
+      Buffer.from([0x05, 0x01, 0x00, 0x03, host.length]),
+      host,
+      port
+    ])
+  )
+  return socket
+}
+
 function connectThrough(
   proxyPort: number,
   destination: Requested,
@@ -146,6 +174,43 @@ describe('createSocks5Server', () => {
     ).rejects.toThrow()
   })
 
+  it('reports why the outbound leg could not be opened', async () => {
+    const errors: Error[] = []
+    const proxy = await startProxy(
+      [],
+      () => Promise.reject(new Error('(SSH) Channel open failure: administratively prohibited')),
+      (error) => errors.push(error)
+    )
+    await expect(
+      connectThrough(proxy.port, { host: 'mongo1.internal', port: 27017 })
+    ).rejects.toThrow()
+    expect(errors[0]?.message).toBe(
+      'failed to forward to mongo1.internal:27017: (SSH) Channel open failure: administratively prohibited'
+    )
+  })
+
+  it('destroys an outbound leg that opens after the client is gone', async () => {
+    let openRemote: (remote: PassThrough) => void = () => undefined
+    const pending = new Promise<PassThrough>((resolve) => (openRemote = resolve))
+    const requested: Requested[] = []
+    const errors: Error[] = []
+    const proxy = await startProxy(
+      requested,
+      () => pending,
+      (error) => errors.push(error)
+    )
+
+    const client = await sendConnectRequest(proxy.port, { host: 'mongo1.internal', port: 27017 })
+    await vi.waitFor(() => expect(requested).toHaveLength(1))
+    // A reset, unlike a FIN, leaves no 'end' that piping could pass on to the outbound leg.
+    client.resetAndDestroy()
+    await vi.waitFor(() => expect(errors).not.toHaveLength(0))
+
+    const remote = new PassThrough()
+    openRemote(remote)
+    await vi.waitFor(() => expect(remote.destroyed).toBe(true))
+  })
+
   it('destroys live connections on close', async () => {
     const proxy = await startProxy([])
     const { socket } = await connectThrough(proxy.port, { host: 'mongo1.internal', port: 27017 })
diff --git a/src/main/lib/socks5.ts b/src/main/lib/socks5.ts
index d4a5c50..49de8d5 100644
--- a/src/main/lib/socks5.ts
+++ b/src/main/lib/socks5.ts
@@ -202,7 +202,13 @@ function handleClient(socket: Socket, options: Socks5Options): void {
         remote = await options.connect(host, port)
       } catch (cause) {
         socket.end(replyFrame(REPLY_CONNECTION_REFUSED))
-        throw new Error(`failed to forward to ${host}:${port}`, { cause })
+        const reason = cause instanceof Error ? cause.message : String(cause)
+        throw new Error(`failed to forward to ${host}:${port}: ${reason}`, { cause })
+      }
+      // The client left while the leg was opening, so the 'close' hook below would come too late.
+      if (socket.destroyed) {
+        remote.destroy()
+        return
       }
       // The driver drives its own idle timeouts from here on.
       socket.setTimeout(0)
diff --git a/src/main/lib/storageStats.test.ts b/src/main/lib/storageStats.test.ts
new file mode 100644
index 0000000..b16710b
--- /dev/null
+++ b/src/main/lib/storageStats.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+import { mergeStorageStats, storageParts, sumIndexSizes } from './storageStats'
+
+describe('mergeStorageStats', () => {
+  it('passes a single document through', () => {
+    const merged = mergeStorageStats([
+      {
+        ns: 'app.players',
+        storageStats: {
+          count: 4,
+          size: 400,
+          avgObjSize: 100,
+          storageSize: 8192,
+          freeStorageSize: 1024,
+          totalIndexSize: 4096,
+          totalSize: 12288,
+          indexSizes: { _id_: 2048, name_1: 2048 },
+          nindexes: 2,
+          capped: false,
+          wiredTiger: { uri: 'statistics:table:collection-0' }
+        }
+      }
+    ])
+
+    expect(merged).toEqual({
+      ns: 'app.players',
+      storage: {
+        count: 4,
+        size: 400,
+        storageSize: 8192,
+        freeStorageSize: 1024,
+        totalIndexSize: 4096,
+        totalSize: 12288,
+        indexSizes: { _id_: 2048, name_1: 2048 },
+        nindexes: 2,
+        capped: false
+      }
+    })
+  })
+
+  it('sums every shard and merges indexSizes by name', () => {
+    const merged = mergeStorageStats([
+      {
+        ns: 'app.players',
+        shard: 'shard-a',
+        storageStats: {
+          count: 3,
+          size: 300,
+          avgObjSize: 100,
+          storageSize: 4096,
+          freeStorageSize: 0,
+          totalIndexSize: 3000,
+          totalSize: 7096,
+          indexSizes: { _id_: 1000, name_1: 2000 },
+          nindexes: 2,
+          capped: false,
+          numOrphanDocs: 1
+        }
+      },
+      {
+        ns: 'app.players',
+        shard: 'shard-b',
+        storageStats: {
+          count: 1,
+          size: 500,
+          avgObjSize: 500,
+          storageSize: 8192,
+          freeStorageSize: 512,
+          totalIndexSize: 700,
+          totalSize: 8892,
+          indexSizes: { _id_: 300, region_1: 400 },
+          nindexes: 3,
+          capped: true,
+          numOrphanDocs: 2
+        }
+      }
+    ])
+
+    expect(merged).toEqual({
+      ns: 'app.players',
+      storage: {
+        count: 4,
+        size: 800,
+        storageSize: 12288,
+        freeStorageSize: 512,
+        totalIndexSize: 3700,
+        totalSize: 15988,
+        numOrphanDocs: 3,
+        indexSizes: { _id_: 1300, name_1: 2000, region_1: 400 },
+        nindexes: 2,
+        capped: false
+      }
+    })
+  })
+
+  it('leaves numOrphanDocs out when no shard reports it', () => {
+    const { storage } = mergeStorageStats([
+      { ns: 'app.players', storageStats: { count: 1, size: 10 } },
+      { ns: 'app.players', storageStats: { count: 1, size: 10 } }
+    ])
+
+    expect(storage).not.toHaveProperty('numOrphanDocs')
+  })
+
+  it('counts non-number values as 0', () => {
+    const { storage } = mergeStorageStats([
+      { ns: 'app.players', storageStats: { count: 2, size: 'big', storageSize: null } },
+      { ns: 'app.players', storageStats: { count: Number.NaN, size: 60, indexSizes: { a_1: 'x' } } }
+    ])
+
+    expect(storage).toMatchObject({
+      count: 2,
+      size: 60,
+      storageSize: 0,
+      indexSizes: {}
+    })
+  })
+
+  it('leaves count out when no shard reports one, as for a time-series collection', () => {
+    const { storage } = mergeStorageStats([
+      {
+        ns: 'app.system.buckets.readings',
+        storageStats: { size: 959, timeseries: { bucketCount: 3 } }
+      }
+    ])
+
+    expect(storage).not.toHaveProperty('count')
+    expect(storage['size']).toBe(959)
+  })
+
+  it('keeps an index named __proto__ as an own entry', () => {
+    const indexSizes: Record<string, unknown> = {}
+    Object.defineProperty(indexSizes, '__proto__', {
+      value: 512,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    })
+
+    const { storage } = mergeStorageStats([
+      { ns: 'app.players', storageStats: { indexSizes } },
+      { ns: 'app.players', storageStats: { indexSizes } }
+    ])
+
+    expect(Object.entries(storage['indexSizes'] as object)).toEqual([['__proto__', 1024]])
+  })
+
+  it('gives an empty storage object and no ns for no documents', () => {
+    expect(mergeStorageStats([])).toEqual({ ns: null, storage: {} })
+  })
+})
+
+describe('storageParts', () => {
+  it('takes the storageStats of each document and gives {} where there is none', () => {
+    expect(
+      storageParts([{ storageStats: { size: 1 } }, { storageStats: null }, { ns: 'app.players' }])
+    ).toEqual([{ size: 1 }, {}, {}])
+  })
+})
+
+describe('sumIndexSizes', () => {
+  it('sums each index over the parts and skips parts without indexSizes', () => {
+    expect(
+      sumIndexSizes([{ indexSizes: { _id_: 10, a_1: 5 } }, {}, { indexSizes: { _id_: 30 } }])
+    ).toEqual({ _id_: 40, a_1: 5 })
+  })
+})
diff --git a/src/main/lib/storageStats.ts b/src/main/lib/storageStats.ts
new file mode 100644
index 0000000..ad7beca
--- /dev/null
+++ b/src/main/lib/storageStats.ts
@@ -0,0 +1,66 @@
+import { isDocument } from '@shared/writeOps'
+
+type StorageDoc = Record<string, unknown>
+
+/**
+ * Sums per-shard `$collStats` storage stats; `nindexes` and `capped` come from the first shard.
+ * @param docs one `$collStats` document per shard
+ * @returns the namespace and summed stats; `count` only when a shard reports one
+ */
+export function mergeStorageStats(docs: ReadonlyArray<StorageDoc>): {
+  ns: string | null
+  storage: Record<string, unknown>
+} {
+  const first = docs[0]
+  if (!first) return { ns: null, storage: {} }
+  const parts = storageParts(docs)
+  const firstPart = parts[0] ?? {}
+  return {
+    ns: typeof first['ns'] === 'string' ? first['ns'] : null,
+    storage: {
+      ...(parts.some((p) => p['count'] !== undefined) ? { count: sum(parts, 'count') } : {}),
+      size: sum(parts, 'size'),
+      storageSize: sum(parts, 'storageSize'),
+      freeStorageSize: sum(parts, 'freeStorageSize'),
+      totalIndexSize: sum(parts, 'totalIndexSize'),
+      totalSize: sum(parts, 'totalSize'),
+      ...(parts.some((p) => p['numOrphanDocs'] !== undefined)
+        ? { numOrphanDocs: sum(parts, 'numOrphanDocs') }
+        : {}),
+      indexSizes: sumIndexSizes(parts),
+      nindexes: firstPart['nindexes'],
+      capped: firstPart['capped']
+    }
+  }
+}
+
+function sum(parts: ReadonlyArray<StorageDoc>, key: string): number {
+  return parts.reduce((total, part) => total + (finiteNumber(part[key]) ?? 0), 0)
+}
+
+/** The `storageStats` of each `$collStats` document; `{}` where a document has none. */
+export function storageParts(docs: ReadonlyArray<StorageDoc>): StorageDoc[] {
+  return docs.map((doc) => {
+    const stats = doc['storageStats']
+    return isDocument(stats) ? stats : {}
+  })
+}
+
+/** Each index's size summed over `storageParts`; sizes that are not finite numbers are skipped. */
+export function sumIndexSizes(parts: ReadonlyArray<StorageDoc>): Record<string, number> {
+  // A Map, not an object: an index may be named "__proto__".
+  const sizes = new Map<string, number>()
+  for (const part of parts) {
+    const indexSizes = part['indexSizes']
+    if (!isDocument(indexSizes)) continue
+    for (const [name, value] of Object.entries(indexSizes)) {
+      const size = finiteNumber(value)
+      if (size !== undefined) sizes.set(name, (sizes.get(name) ?? 0) + size)
+    }
+  }
+  return Object.fromEntries(sizes)
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
diff --git a/src/main/lib/tunnel.test.ts b/src/main/lib/tunnel.test.ts
new file mode 100644
index 0000000..ad128f2
--- /dev/null
+++ b/src/main/lib/tunnel.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest'
+import { InvalidUriError } from './connectionUri'
+import { applyTunnelRoute, preferTunnelFailure, type Tunnel, type TunnelRoute } from './tunnel'
+
+const SOCKS: TunnelRoute = {
+  kind: 'socks5',
+  proxy: { proxyHost: '127.0.0.1', proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' }
+}
+const LOCAL_PORT: TunnelRoute = { kind: 'localPort', host: '127.0.0.1', port: 5001 }
+
+function driverError(name: string): Error {
+  return Object.assign(new Error('driver says no'), { name })
+}
+
+function tunnelWith(failure: Error | null): Tunnel {
+  return {
+    route: LOCAL_PORT,
+    pinnedHostKey: null,
+    failure: () => failure,
+    close: () => Promise.resolve()
+  }
+}
+
+describe('applyTunnelRoute', () => {
+  it('keeps the URI and adds the proxy options for a SOCKS5 route', () => {
+    const uri = 'mongodb://alice:pw@mongo1.internal:27017,mongo2.internal:27017/db'
+    expect(applyTunnelRoute(uri, { appName: 'MongoBench' }, SOCKS)).toEqual({
+      uri,
+      options: {
+        appName: 'MongoBench',
+        proxyHost: '127.0.0.1',
+        proxyPort: 1080,
+        proxyUsername: 'u',
+        proxyPassword: 'p'
+      }
+    })
+  })
+
+  it('points the URI at the local port and names the server for TLS', () => {
+    const target = applyTunnelRoute(
+      'mongodb://alice:pw@Mongo.Example.com:27017/db?authSource=admin',
+      { appName: 'MongoBench', tls: true },
+      LOCAL_PORT
+    )
+    expect(target.uri).toBe('mongodb://alice:pw@127.0.0.1:5001/db?authSource=admin')
+    expect(target.options).toEqual({
+      appName: 'MongoBench',
+      tls: true,
+      directConnection: true,
+      servername: 'mongo.example.com'
+    })
+  })
+
+  it('forces a direct connection even when the options asked for discovery', () => {
+    const target = applyTunnelRoute(
+      'mongodb://a.example.com,b.example.com/db',
+      { directConnection: false },
+      LOCAL_PORT
+    )
+    expect(target.uri).toBe('mongodb://127.0.0.1:5001/db')
+    expect(target.options.directConnection).toBe(true)
+  })
+
+  it('sets no servername for an IP host', () => {
+    const target = applyTunnelRoute('mongodb://10.0.0.5:27017/db', {}, LOCAL_PORT)
+    expect(target.options).toEqual({ directConnection: true })
+  })
+
+  it('rejects mongodb+srv:// on a local-port route', () => {
+    expect(() => applyTunnelRoute('mongodb+srv://cluster.example.com/db', {}, LOCAL_PORT)).toThrow(
+      InvalidUriError
+    )
+  })
+})
+
+describe('preferTunnelFailure', () => {
+  const reason = new Error(
+    'Cloudflare tunnel to mongo.example.com failed: websocket: bad handshake!'
+  )
+
+  it.each(['MongoServerSelectionError', 'MongoNetworkError', 'MongoNetworkTimeoutError'])(
+    'reports the tunnel reason instead of a %s',
+    (name) => {
+      expect(preferTunnelFailure(driverError(name), tunnelWith(reason))).toBe(reason)
+    }
+  )
+
+  it('never masks a MongoDB authentication error', () => {
+    const error = driverError('MongoAuthenticationError')
+    expect(preferTunnelFailure(error, tunnelWith(reason))).toBe(error)
+  })
+
+  it('keeps the driver error without a tunnel', () => {
+    const error = driverError('MongoServerSelectionError')
+    expect(preferTunnelFailure(error, null)).toBe(error)
+  })
+
+  it('keeps the driver error when the tunnel knows of no failure', () => {
+    const error = driverError('MongoServerSelectionError')
+    expect(preferTunnelFailure(error, tunnelWith(null))).toBe(error)
+  })
+})
diff --git a/src/main/lib/tunnel.ts b/src/main/lib/tunnel.ts
new file mode 100644
index 0000000..0b0f720
--- /dev/null
+++ b/src/main/lib/tunnel.ts
@@ -0,0 +1,60 @@
+import type { MongoClientOptions } from 'mongodb'
+import type { PinnedHostKeyNotice } from '@shared/types'
+import { firstHostName, replaceHosts } from './connectionUri'
+import { mapError } from './errorMap'
+
+/** What the driver needs to route through a SOCKS5 tunnel. */
+export type TunnelProxyOptions = {
+  proxyHost: string
+  proxyPort: number
+  proxyUsername: string
+  proxyPassword: string
+}
+
+/**
+ * How the driver reaches the server through an open tunnel: a SOCKS5 proxy that
+ * forwards any host by name, or one loopback port that leads to exactly one server.
+ */
+export type TunnelRoute =
+  { kind: 'socks5'; proxy: TunnelProxyOptions } | { kind: 'localPort'; host: string; port: number }
+
+/** An open tunnel. The caller owns it and is responsible for closing it. */
+export type Tunnel = {
+  route: TunnelRoute
+  /** Set only when this open pinned a host key it had never seen. */
+  pinnedHostKey: PinnedHostKeyNotice | null
+  /** The tunnel's own error for traffic it could not carry, when it has one. */
+  failure: () => Error | null
+  close: () => Promise<void>
+}
+
+/**
+ * The URI and options that send every driver socket through `route`.
+ * @throws InvalidUriError when a local-port route meets a `mongodb+srv://` URI.
+ */
+export function applyTunnelRoute(
+  uri: string,
+  options: MongoClientOptions,
+  route: TunnelRoute
+): { uri: string; options: MongoClientOptions } {
+  if (route.kind === 'socks5') return { uri, options: { ...options, ...route.proxy } }
+  const servername = firstHostName(uri)
+  return {
+    uri: replaceHosts(uri, `${route.host}:${route.port}`),
+    options: {
+      ...options,
+      // The port leads to one server; discovery would send the driver to member hosts the tunnel does not reach.
+      directConnection: true,
+      // The certificate names the server, not 127.0.0.1.
+      ...(servername !== null ? { servername } : {})
+    }
+  }
+}
+
+/** A driver timeout behind a tunnel that knows why it failed is reported as the tunnel's reason. */
+export function preferTunnelFailure(error: unknown, tunnel: Tunnel | null): unknown {
+  const failure = tunnel?.failure() ?? null
+  if (failure === null) return error
+  const { code } = mapError(error)
+  return code === 'server_selection_timeout' || code === 'network_error' ? failure : error
+}
diff --git a/src/main/services/CloudflaredTunnelService.test.ts b/src/main/services/CloudflaredTunnelService.test.ts
new file mode 100644
index 0000000..3b609a1
--- /dev/null
+++ b/src/main/services/CloudflaredTunnelService.test.ts
@@ -0,0 +1,555 @@
+import type { ChildProcess } from 'node:child_process'
+import { EventEmitter } from 'node:events'
+import { PassThrough } from 'node:stream'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { CloudflaredLoginPrompt } from '@shared/events'
+import type { CloudflaredRuntime } from './CloudflaredTunnelService'
+
+// The service logs through electron-log, which pulls in electron itself.
+vi.mock('electron-log/main', () => ({
+  default: { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+}))
+
+const {
+  CloudflaredAuthError,
+  CloudflaredNotFoundError,
+  CloudflaredTunnelError,
+  CloudflaredTunnelService
+} = await import('./CloudflaredTunnelService')
+const log = (await import('electron-log/main')).default
+
+const HOSTNAME = 'mongo.example.com'
+const TOKEN_ID = '0123456789abcdef0123456789abcdef.access'
+const TOKEN_SECRET = 'cfast_service-token-secret'
+const TOKEN_CONFIG = {
+  hostname: HOSTNAME,
+  authMethod: 'serviceToken' as const,
+  serviceTokenId: TOKEN_ID,
+  serviceTokenSecret: TOKEN_SECRET
+}
+const BROWSER_CONFIG = { hostname: HOSTNAME, authMethod: 'browser' as const }
+
+const LOGIN_URL = `https://${HOSTNAME}/cdn-cgi/access/cli?aud=abc&redirect_url=https%3A%2F%2F${HOSTNAME}`
+const LOGIN_PROMPT = `A browser window should have opened at the following URL:\n\n${LOGIN_URL}\n\n`
+const ORIGIN_ERROR =
+  '2026-10-16T12:58:01Z ERR failed to connect to origin error="websocket: bad handshake" originURL=https://mongo.example.com'
+const BIND_ERROR = (port: number): string =>
+  `2026-10-16T12:58:00Z ERR Error on Websocket listener error="failed to start forwarding server: listen tcp 127.0.0.1:${port}: bind: Only one usage of each socket address is normally permitted."`
+
+/** Stands in for a cloudflared child: stdio streams plus the exit events Node emits. */
+class FakeProcess extends EventEmitter {
+  readonly stdout = new PassThrough()
+  readonly stderr = new PassThrough()
+  exitCode: number | null = null
+  signalCode: NodeJS.Signals | null = null
+  readonly kill = vi.fn((): boolean => {
+    queueMicrotask(() => this.finish(null, 'SIGTERM'))
+    return true
+  })
+
+  /** cloudflared logs to stderr. */
+  log(text: string): void {
+    this.stderr.write(text)
+  }
+
+  /** 'exit' first, then 'close' once both streams have been read to the end. */
+  finish(code: number | null, signal: NodeJS.Signals | null = null): void {
+    if (this.exitCode !== null || this.signalCode !== null) return
+    this.exitCode = code
+    this.signalCode = signal
+    this.emit('exit', code, signal)
+    let open = 2
+    const drained = (): void => {
+      open -= 1
+      if (open === 0) this.emit('close', code, signal)
+    }
+    this.stdout.once('end', drained)
+    this.stderr.once('end', drained)
+    this.stdout.end()
+    this.stderr.end()
+  }
+
+  /** A spawn failure: 'error', then 'close', and never 'exit'. */
+  fail(code: string): void {
+    this.emit('error', Object.assign(new Error(`spawn cloudflared ${code}`), { code }))
+    this.emit('close', -4058, null)
+  }
+}
+
+type Spawned = { command: string; args: string[]; env: NodeJS.ProcessEnv; child: FakeProcess }
+
+/** `access login` succeeds at once; every other process keeps running. */
+function signInAtOnce({ args, child }: Spawned): void {
+  if (args[1] === 'login') child.finish(0)
+}
+
+function fakeRuntime(
+  options: { onSpawn?: (spawned: Spawned) => void; listening?: (port: number) => boolean } = {}
+): { runtime: CloudflaredRuntime; spawned: Spawned[] } {
+  const spawned: Spawned[] = []
+  const ports = [5001, 5002]
+  const runtime: CloudflaredRuntime = {
+    spawn: vi.fn((command: string, args: string[], env: NodeJS.ProcessEnv) => {
+      const child = new FakeProcess()
+      const call = { command, args, env, child }
+      spawned.push(call)
+      // After launch() attached its listeners, as with a real child.
+      queueMicrotask(() => (options.onSpawn ?? signInAtOnce)(call))
+      return child as unknown as ChildProcess
+    }),
+    freePort: vi.fn(() => Promise.resolve(ports.shift() ?? 6000)),
+    isListening: vi.fn((port: number) => Promise.resolve(options.listening?.(port) ?? true))
+  }
+  return { runtime, spawned }
+}
+
+function noPrompts(): void {}
+
+function spawnedAt(spawned: Spawned[], index: number): Spawned {
+  const call = spawned[index]
+  if (call === undefined) throw new Error(`nothing was spawned at ${index}`)
+  return call
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.clearAllMocks()
+  delete process.env['TUNNEL_SERVICE_HOSTNAME']
+})
+
+describe('open with a service token', () => {
+  it('runs access tcp with plain argv and the token only in the environment', async () => {
+    process.env['TUNNEL_SERVICE_HOSTNAME'] = 'inherited.example.net'
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const tunnel = await service.open(TOKEN_CONFIG)
+
+    expect(spawned).toHaveLength(1)
+    const { command, args, env } = spawnedAt(spawned, 0)
+    expect(command).toBe('cloudflared')
+    expect(args).toEqual(['access', 'tcp', '--hostname=mongo.example.com', '--url=127.0.0.1:5001'])
+    expect(env['TUNNEL_SERVICE_TOKEN_ID']).toBe(TOKEN_ID)
+    expect(env['TUNNEL_SERVICE_TOKEN_SECRET']).toBe(TOKEN_SECRET)
+    expect(env['TUNNEL_SERVICE_HOSTNAME']).toBeUndefined()
+    // cloudflared itself still has to be found and must reach the network.
+    expect(Object.keys(env).some((key) => key.toUpperCase() === 'PATH')).toBe(true)
+    expect(args.join(' ')).not.toContain(TOKEN_SECRET)
+    expect(tunnel.route).toEqual({ kind: 'localPort', host: '127.0.0.1', port: 5001 })
+    expect(service.openCount).toBe(1)
+  })
+
+  it('never writes the secret to the log', async () => {
+    const { runtime } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const tunnel = await service.open(TOKEN_CONFIG)
+    await tunnel.close()
+
+    const logged = JSON.stringify([
+      vi.mocked(log.info).mock.calls,
+      vi.mocked(log.warn).mock.calls,
+      vi.mocked(log.debug).mock.calls,
+      vi.mocked(log.error).mock.calls
+    ])
+    expect(logged).toContain(HOSTNAME)
+    expect(logged).not.toContain(TOKEN_SECRET)
+  })
+
+  it('rejects a missing client ID or secret before spawning anything', async () => {
+    const { runtime } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(service.open({ ...TOKEN_CONFIG, serviceTokenId: '' })).rejects.toThrow(
+      CloudflaredAuthError
+    )
+    const { serviceTokenSecret: _secret, ...withoutSecret } = TOKEN_CONFIG
+    await expect(service.open(withoutSecret)).rejects.toThrow(CloudflaredAuthError)
+    expect(runtime.spawn).not.toHaveBeenCalled()
+  })
+})
+
+describe('open with browser sign-in', () => {
+  it('signs in with access login first and starts the tunnel only after it exits', async () => {
+    const { runtime, spawned } = fakeRuntime({ onSpawn: () => undefined })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const opening = service.open(BROWSER_CONFIG)
+    await vi.waitFor(() => expect(spawned).toHaveLength(1))
+    expect(spawnedAt(spawned, 0).args).toEqual([
+      'access',
+      'login',
+      '--quiet',
+      '--auto-close',
+      'https://mongo.example.com'
+    ])
+    expect(spawnedAt(spawned, 0).env['TUNNEL_SERVICE_TOKEN_SECRET']).toBeUndefined()
+    // Still signing in: no tunnel yet.
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(spawned).toHaveLength(1)
+
+    spawnedAt(spawned, 0).child.finish(0)
+    const tunnel = await opening
+    expect(spawnedAt(spawned, 1).args.slice(0, 2)).toEqual(['access', 'tcp'])
+    expect(tunnel.route).toEqual({ kind: 'localPort', host: '127.0.0.1', port: 5001 })
+  })
+
+  it('reports a failed sign-in and never starts the tunnel', async () => {
+    const { runtime, spawned } = fakeRuntime({
+      onSpawn: ({ child }) => {
+        child.log('failed to get app info: Head "https://mongo.example.com": no such host\n')
+        child.finish(1)
+      }
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const error = await service.open(BROWSER_CONFIG).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(CloudflaredAuthError)
+    expect((error as Error).message).toContain('failed to get app info')
+    expect(spawned).toHaveLength(1)
+  })
+
+  it('stops a waiting sign-in when the open is aborted and never starts the tunnel', async () => {
+    const { runtime, spawned } = fakeRuntime({ onSpawn: () => undefined })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const aborting = new AbortController()
+
+    const opening = service.open(BROWSER_CONFIG, undefined, aborting.signal)
+    await vi.waitFor(() => expect(spawned).toHaveLength(1))
+    aborting.abort()
+
+    const error = await opening.catch((e: unknown) => e)
+    expect(error).toMatchObject({ name: 'CancelledError' })
+    expect((error as Error).message).toContain('cancelled')
+    expect(spawnedAt(spawned, 0).child.kill).toHaveBeenCalled()
+    expect(spawned).toHaveLength(1)
+  })
+
+  it('starts nothing for an open that was aborted before it began', async () => {
+    const { runtime } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(
+      service.open(BROWSER_CONFIG, undefined, AbortSignal.abort())
+    ).rejects.toMatchObject({ name: 'CancelledError' })
+    expect(runtime.spawn).not.toHaveBeenCalled()
+  })
+
+  it('does not start the tunnel when the open is aborted after the sign-in', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const aborting = new AbortController()
+    vi.mocked(runtime.freePort).mockImplementationOnce(() => {
+      aborting.abort()
+      return Promise.resolve(5001)
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(service.open(BROWSER_CONFIG, undefined, aborting.signal)).rejects.toMatchObject({
+      name: 'CancelledError'
+    })
+    expect(spawned.map(({ args }) => args[1])).toEqual(['login'])
+  })
+
+  it('announces the sign-in URL while waiting and once more when done', async () => {
+    const prompts: CloudflaredLoginPrompt[] = []
+    const { runtime } = fakeRuntime({
+      onSpawn: ({ args, child }) => {
+        if (args[1] !== 'login') return
+        child.log('https://evil.example.net/cdn-cgi/access/cli?aud=abc\n')
+        child.log(LOGIN_PROMPT)
+        child.finish(0)
+      }
+    })
+    const service = new CloudflaredTunnelService((prompt) => prompts.push(prompt), runtime)
+
+    await service.open(BROWSER_CONFIG)
+
+    expect(prompts).toEqual([
+      { hostname: HOSTNAME, state: 'waiting', url: LOGIN_URL },
+      { hostname: HOSTNAME, state: 'finished' }
+    ])
+  })
+})
+
+describe('choosing the executable', () => {
+  it('refuses a binary path that does not name cloudflared, without spawning it', async () => {
+    const { runtime } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(
+      service.open({ ...TOKEN_CONFIG, binaryPath: 'C:\\tools\\calc.exe' })
+    ).rejects.toThrow(CloudflaredNotFoundError)
+    expect(runtime.spawn).not.toHaveBeenCalled()
+  })
+
+  it('refuses a cloudflared on another machine, without spawning it', async () => {
+    const { runtime } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const remote = '\\\\attacker.invalid@SSL\\DavWWWRoot\\cloudflared.exe'
+
+    await expect(service.open({ ...TOKEN_CONFIG, binaryPath: remote })).rejects.toThrow(
+      CloudflaredNotFoundError
+    )
+    await expect(service.version(remote)).rejects.toThrow(CloudflaredNotFoundError)
+    expect(runtime.spawn).not.toHaveBeenCalled()
+  })
+
+  it('runs a chosen cloudflared executable', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await service.open({ ...TOKEN_CONFIG, binaryPath: 'C:\\tools\\cloudflared.exe' })
+    expect(spawnedAt(spawned, 0).command).toBe('C:\\tools\\cloudflared.exe')
+  })
+
+  it('explains a cloudflared missing from PATH', async () => {
+    const { runtime } = fakeRuntime({
+      onSpawn: ({ child }) => child.fail('ENOENT'),
+      listening: () => false
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const error = await service.open(TOKEN_CONFIG).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(CloudflaredNotFoundError)
+    expect((error as Error).message).toContain('not found on PATH')
+  })
+
+  it('reports a file Node refuses to run as not found', async () => {
+    const { runtime } = fakeRuntime()
+    vi.mocked(runtime.spawn).mockImplementation(() => {
+      throw Object.assign(new Error('spawn UNKNOWN'), { code: 'UNKNOWN' })
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(
+      service.open({ ...TOKEN_CONFIG, binaryPath: 'C:\\tools\\cloudflared.exe' })
+    ).rejects.toThrow(CloudflaredNotFoundError)
+  })
+
+  it('reports a spawn refused over its environment as a tunnel failure, without the token', async () => {
+    const { runtime } = fakeRuntime()
+    vi.mocked(runtime.spawn).mockImplementation(() => {
+      throw Object.assign(
+        new TypeError(
+          `The property 'options.env' must be a string without null bytes. Received '${TOKEN_SECRET}'`
+        ),
+        { code: 'ERR_INVALID_ARG_VALUE' }
+      )
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const error = await service.open(TOKEN_CONFIG).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(CloudflaredTunnelError)
+    expect((error as Error).name).toBe('CloudflaredTunnelError')
+    expect((error as Error).message).toContain('ERR_INVALID_ARG_VALUE')
+    expect((error as Error).message).not.toContain(TOKEN_SECRET)
+  })
+})
+
+describe('startup', () => {
+  it('reports why cloudflared quit before the port opened', async () => {
+    const { runtime } = fakeRuntime({
+      onSpawn: ({ child }) => {
+        child.log(
+          '2026-10-16T12:58:03Z ERR  error="failed to parse as URL: parse \\"https://x\\": invalid"\n'
+        )
+        child.stdout.write('NAME:\n   cloudflared access tcp - ...\n')
+        child.finish(0)
+      },
+      listening: () => false
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const error = await service.open(TOKEN_CONFIG).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(CloudflaredTunnelError)
+    expect((error as Error).message).toContain('failed to parse as URL')
+    expect(service.openCount).toBe(0)
+  })
+
+  it('retries once on another port when the picked one was taken', async () => {
+    const { runtime, spawned } = fakeRuntime({
+      onSpawn: ({ args, child }) => {
+        if (args[3] !== '--url=127.0.0.1:5001') return
+        child.log(`${BIND_ERROR(5001)}\n`)
+        child.finish(1)
+      },
+      listening: (port) => port !== 5001
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const tunnel = await service.open(TOKEN_CONFIG)
+    expect(tunnel.route).toEqual({ kind: 'localPort', host: '127.0.0.1', port: 5002 })
+    expect(spawned).toHaveLength(2)
+  })
+
+  it('gives up when the second port is taken too', async () => {
+    const { runtime, spawned } = fakeRuntime({
+      onSpawn: ({ args, child }) => {
+        child.log(`${BIND_ERROR(Number(args[3]?.split(':').pop()))}\n`)
+        child.finish(1)
+      },
+      listening: () => false
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const error = await service.open(TOKEN_CONFIG).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(CloudflaredTunnelError)
+    expect((error as Error).name).toBe('CloudflaredTunnelError')
+    expect((error as Error).message).toContain('failed to start forwarding server')
+    expect(spawned).toHaveLength(2)
+  })
+
+  it('stops cloudflared when the port never opens', async () => {
+    vi.useFakeTimers()
+    const { runtime, spawned } = fakeRuntime({ listening: () => false })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const failed = expect(service.open(TOKEN_CONFIG)).rejects.toThrow(
+      /did not open its local port for mongo\.example\.com within 15 s/
+    )
+    await vi.advanceTimersByTimeAsync(15_200)
+    await failed
+    expect(spawnedAt(spawned, 0).child.kill).toHaveBeenCalled()
+  })
+})
+
+describe('an open tunnel', () => {
+  it('stops cloudflared on close without reporting a drop, once', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const dropped: string[] = []
+    const tunnel = await service.open(TOKEN_CONFIG, (reason) => dropped.push(reason))
+
+    await tunnel.close()
+    await tunnel.close()
+
+    const { child } = spawnedAt(spawned, 0)
+    expect(child.kill).toHaveBeenCalledTimes(1)
+    expect(service.openCount).toBe(0)
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    expect(dropped).toEqual([])
+  })
+
+  it('reports a drop with the exit code and the last error when cloudflared dies', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const dropped: string[] = []
+    const tunnel = await service.open(TOKEN_CONFIG, (reason) => dropped.push(reason))
+    const { child } = spawnedAt(spawned, 0)
+
+    child.log(`${ORIGIN_ERROR}\n`)
+    child.finish(1)
+    await vi.waitFor(() => expect(dropped).toHaveLength(1))
+
+    expect(dropped[0]).toContain('code 1')
+    expect(dropped[0]).toContain('websocket: bad handshake')
+    expect(service.openCount).toBe(0)
+    expect(tunnel.failure()).toBeInstanceOf(CloudflaredTunnelError)
+    await tunnel.close()
+    expect(child.kill).not.toHaveBeenCalled()
+  })
+
+  it('knows no failure until cloudflared logs an error', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const tunnel = await service.open(TOKEN_CONFIG)
+    expect(tunnel.failure()).toBeNull()
+
+    spawnedAt(spawned, 0).child.log(`${ORIGIN_ERROR}\n`)
+    await vi.waitFor(() => expect(tunnel.failure()).not.toBeNull())
+    const failure = tunnel.failure()
+    expect(failure).toBeInstanceOf(CloudflaredTunnelError)
+    expect(failure?.message).toContain('websocket: bad handshake')
+  })
+
+  it('blames the service token when Access falls back to a browser sign-in', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+    const tunnel = await service.open(TOKEN_CONFIG)
+
+    spawnedAt(spawned, 0).child.log(LOGIN_PROMPT)
+    await vi.waitFor(() => expect(tunnel.failure()).toBeInstanceOf(CloudflaredAuthError))
+    expect(tunnel.failure()?.message).toContain('Service Auth policy')
+  })
+})
+
+describe('closeAll', () => {
+  it('stops open tunnels and sign-ins still waiting, reporting no drops', async () => {
+    const prompts: CloudflaredLoginPrompt[] = []
+    const { runtime, spawned } = fakeRuntime({
+      onSpawn: ({ args, child }) => {
+        if (args[1] === 'login') child.log(LOGIN_PROMPT)
+      }
+    })
+    const service = new CloudflaredTunnelService((prompt) => prompts.push(prompt), runtime)
+    const dropped: string[] = []
+
+    await service.open(TOKEN_CONFIG, (reason) => dropped.push(reason))
+    const signingIn = service.open(BROWSER_CONFIG, (reason) => dropped.push(reason))
+    const signInStopped = expect(signingIn).rejects.toThrow(CloudflaredAuthError)
+    await vi.waitFor(() => expect(prompts).toHaveLength(1))
+
+    await service.closeAll()
+    await signInStopped
+
+    expect(spawnedAt(spawned, 0).child.kill).toHaveBeenCalled()
+    expect(spawnedAt(spawned, 1).child.kill).toHaveBeenCalled()
+    expect(spawned).toHaveLength(2)
+    expect(prompts.map((prompt) => prompt.state)).toEqual(['waiting', 'finished'])
+    expect(service.openCount).toBe(0)
+    expect(dropped).toEqual([])
+  })
+
+  it('starts no tunnel for an open that was between sign-in and start', async () => {
+    const { runtime, spawned } = fakeRuntime()
+    let portPicked!: (port: number) => void
+    vi.mocked(runtime.freePort).mockImplementationOnce(
+      () => new Promise<number>((resolve) => (portPicked = resolve))
+    )
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    const opening = service.open(BROWSER_CONFIG)
+    await vi.waitFor(() => expect(runtime.freePort).toHaveBeenCalled())
+    await service.closeAll()
+    portPicked(5001)
+
+    await expect(opening).rejects.toThrow(CloudflaredTunnelError)
+    expect(spawned.map(({ args }) => args[1])).toEqual(['login'])
+    expect(service.openCount).toBe(0)
+  })
+})
+
+describe('version', () => {
+  it('reads the version cloudflared reports', async () => {
+    const { runtime, spawned } = fakeRuntime({
+      onSpawn: ({ child }) => {
+        child.stdout.write('cloudflared version 2025.8.1 (built 2025-08-21-1534 UTC)\n')
+        child.finish(0)
+      }
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(service.version()).resolves.toBe('2025.8.1')
+    expect(spawnedAt(spawned, 0).args).toEqual(['--version'])
+  })
+
+  it('reports a cloudflared missing from PATH as not found', async () => {
+    const { runtime } = fakeRuntime({ onSpawn: ({ child }) => child.fail('ENOENT') })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(service.version()).rejects.toThrow(/not found on PATH/)
+  })
+
+  it('reports a program that names no cloudflared version as not found', async () => {
+    const { runtime } = fakeRuntime({
+      onSpawn: ({ child }) => {
+        child.stdout.write('something else entirely\n')
+        child.finish(0)
+      }
+    })
+    const service = new CloudflaredTunnelService(noPrompts, runtime)
+
+    await expect(service.version('C:\\tools\\cloudflared.exe')).rejects.toThrow(
+      CloudflaredNotFoundError
+    )
+  })
+})
diff --git a/src/main/services/CloudflaredTunnelService.ts b/src/main/services/CloudflaredTunnelService.ts
new file mode 100644
index 0000000..e02eff7
--- /dev/null
+++ b/src/main/services/CloudflaredTunnelService.ts
@@ -0,0 +1,437 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import { connect, createServer, type AddressInfo } from 'node:net'
+import log from 'electron-log/main'
+import { isCloudflaredExecutable } from '@shared/cloudflared'
+import type { CloudflaredLoginPrompt } from '@shared/events'
+import type { CloudflaredAuthMethod } from '@shared/types'
+import { findLoginUrl, OutputTail, splitLines } from '../lib/cloudflaredLog'
+import { cancelledError } from '../lib/errorMap'
+import type { Tunnel } from '../lib/tunnel'
+
+const LOOPBACK = '127.0.0.1'
+const PATH_COMMAND = 'cloudflared'
+const STARTUP_TIMEOUT_MS = 15_000
+const PROBE_INTERVAL_MS = 100
+// Last resort only: cloudflared gives up by itself after 10 long polls of up to 60 s.
+const LOGIN_TIMEOUT_MS = 15 * 60_000
+const VERSION_TIMEOUT_MS = 5_000
+const STOP_TIMEOUT_MS = 3_000
+const BIND_ATTEMPTS = 2
+// Spawn errors that mean the file cannot run; Windows reports a file that is no executable as UNKNOWN.
+const FILE_ERRORS = new Set([
+  'ENOENT',
+  'ENOTDIR',
+  'EACCES',
+  'EPERM',
+  'EINVAL',
+  'ENOEXEC',
+  'UNKNOWN'
+])
+
+/** Tunnel settings with every secret already decrypted. */
+export type ResolvedCloudflaredTunnel = {
+  hostname: string
+  authMethod: CloudflaredAuthMethod
+  serviceTokenId?: string
+  serviceTokenSecret?: string
+  /** Absent = `cloudflared` resolved through PATH. */
+  binaryPath?: string
+}
+
+export class CloudflaredNotFoundError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'CloudflaredNotFoundError'
+  }
+}
+
+export class CloudflaredAuthError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'CloudflaredAuthError'
+  }
+}
+
+export class CloudflaredTunnelError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'CloudflaredTunnelError'
+  }
+}
+
+// Keeps the parent's name, so a bind failure the retry cannot fix still maps to cloudflared_failed.
+class PortTakenError extends CloudflaredTunnelError {}
+
+/** Process and socket primitives, injectable so tests never start cloudflared. */
+export type CloudflaredRuntime = {
+  spawn: (command: string, args: string[], env: NodeJS.ProcessEnv) => ChildProcess
+  freePort: () => Promise<number>
+  /** True once something accepts TCP connections on the loopback port. */
+  isListening: (port: number) => Promise<boolean>
+}
+
+const nodeRuntime: CloudflaredRuntime = {
+  spawn: (command, args, env) =>
+    // No shell: the hostname and path reach cloudflared as plain argv entries.
+    spawn(command, args, { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }),
+  freePort: () =>
+    new Promise<number>((resolve, reject) => {
+      const server = createServer()
+      server.once('error', reject)
+      server.listen(0, LOOPBACK, () => {
+        const { port } = server.address() as AddressInfo
+        server.close(() => resolve(port))
+      })
+    }),
+  isListening: (port) =>
+    new Promise<boolean>((resolve) => {
+      const socket = connect({ host: LOOPBACK, port })
+      socket.once('connect', () => {
+        socket.destroy()
+        resolve(true)
+      })
+      socket.once('error', () => resolve(false))
+    })
+}
+
+type Exit = { code: number | null; error: Error | null }
+
+type Launched = {
+  child: ChildProcess
+  output: OutputTail
+  /** Settles once the process is gone and its output has been read to the end. */
+  exited: Promise<Exit>
+  /** What `exited` settled with, or null while the process still runs. */
+  ended: () => Exit | null
+}
+
+/** Runs one `cloudflared access tcp` process per tunnel, on a free loopback port the driver dials. */
+export class CloudflaredTunnelService {
+  private readonly active = new Set<Tunnel>()
+  private readonly processes = new Set<ChildProcess>()
+  private closing = false
+
+  constructor(
+    private readonly onLogin: (prompt: CloudflaredLoginPrompt) => void,
+    /** Overridable so tests never spawn cloudflared. */
+    private readonly runtime: CloudflaredRuntime = nodeRuntime
+  ) {}
+
+  get openCount(): number {
+    return this.active.size
+  }
+
+  /**
+   * Version of the cloudflared that would run.
+   * @param binaryPath absolute path; omit to use PATH.
+   * @throws CloudflaredNotFoundError when it cannot be run or reports no version.
+   */
+  async version(binaryPath?: string): Promise<string> {
+    const command = commandFor(binaryPath)
+    const { child, output, exited } = this.launch(command, ['--version'], cleanEnv())
+    const timer = setTimeout(() => void this.stop(child), VERSION_TIMEOUT_MS)
+    const { error } = await exited
+    clearTimeout(timer)
+    if (error !== null) throw spawnFailure(command, error)
+    const version = /cloudflared version (\S+)/.exec(output.text())?.[1]
+    if (version === undefined) {
+      throw new CloudflaredNotFoundError(`${command} did not report a cloudflared version!`)
+    }
+    return version
+  }
+
+  /**
+   * Starts a tunnel, signing in first for browser auth.
+   * @param onDropped fires when cloudflared dies on its own, never on `close()`.
+   * @param signal aborting it stops a pending sign-in; the open then rejects as cancelled.
+   */
+  async open(
+    config: ResolvedCloudflaredTunnel,
+    onDropped?: (reason: string) => void,
+    signal?: AbortSignal
+  ): Promise<Tunnel> {
+    const command = commandFor(config.binaryPath)
+    // Before any spawn, so an incomplete service token fails without starting anything.
+    const env = tunnelEnv(config)
+    // access tcp fetches its token only when the driver connects, racing the driver's timeout; access login returns at once with a cached session.
+    if (config.authMethod === 'browser') await this.login(command, config.hostname, signal)
+
+    for (let attempt = 1; ; attempt++) {
+      try {
+        const port = await this.runtime.freePort()
+        throwIfCancelled(signal, config.hostname)
+        return await this.start(command, config, env, port, onDropped)
+      } catch (error) {
+        // The port was only free when it was picked; another process can bind it before cloudflared does.
+        if (error instanceof PortTakenError && attempt < BIND_ATTEMPTS) continue
+        throw error
+      }
+    }
+  }
+
+  async closeAll(): Promise<void> {
+    // One-way, since only quitting calls this: an open still on its way must not spawn after the sweep below.
+    this.closing = true
+    await Promise.allSettled([...this.active].map((tunnel) => tunnel.close()))
+    // Sign-ins and tunnels still starting have no handle yet.
+    await Promise.allSettled([...this.processes].map((child) => this.stop(child)))
+  }
+
+  private async login(command: string, hostname: string, signal?: AbortSignal): Promise<void> {
+    throwIfCancelled(signal, hostname)
+    let prompted = false
+    let timedOut = false
+    const { child, output, exited } = this.launch(
+      command,
+      // --quiet keeps the JWT out of the captured output.
+      ['access', 'login', '--quiet', '--auto-close', `https://${hostname}`],
+      cleanEnv(),
+      this.announceLogin(hostname, () => {
+        prompted = true
+      })
+    )
+    const timer = setTimeout(() => {
+      timedOut = true
+      void this.stop(child)
+    }, LOGIN_TIMEOUT_MS)
+    const stopOnAbort = (): void => void this.stop(child)
+    signal?.addEventListener('abort', stopOnAbort, { once: true })
+    const { code, error } = await exited
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', stopOnAbort)
+
+    if (prompted) this.onLogin({ hostname, state: 'finished' })
+    if (error !== null) throw spawnFailure(command, error)
+    throwIfCancelled(signal, hostname)
+    if (timedOut) {
+      throw new CloudflaredAuthError(
+        `The Cloudflare Access sign-in to ${hostname} did not finish within ${LOGIN_TIMEOUT_MS / 60_000} minutes!`
+      )
+    }
+    if (code !== 0) {
+      throw new CloudflaredAuthError(
+        `Cloudflare Access sign-in to ${hostname} failed: ${output.describe()}!`
+      )
+    }
+  }
+
+  private async start(
+    command: string,
+    config: ResolvedCloudflaredTunnel,
+    env: NodeJS.ProcessEnv,
+    port: number,
+    onDropped?: (reason: string) => void
+  ): Promise<Tunnel> {
+    const { hostname } = config
+    let loginPrompted = false
+    const { child, output, exited, ended } = this.launch(
+      command,
+      ['access', 'tcp', `--hostname=${hostname}`, `--url=${LOOPBACK}:${port}`],
+      env,
+      // An Access session that expires while connected starts a browser sign-in of its own.
+      this.announceLogin(hostname, () => {
+        loginPrompted = true
+      })
+    )
+
+    const deadline = Date.now() + STARTUP_TIMEOUT_MS
+    // cloudflared logs "Start Websocket listener" before it binds, so only a TCP probe shows the port is ready.
+    for (;;) {
+      const listening = await this.runtime.isListening(port)
+      const exit = ended()
+      if (exit !== null) throw startupFailure(command, hostname, port, exit, output)
+      if (listening) break
+      if (Date.now() >= deadline) {
+        await this.stop(child)
+        throw new CloudflaredTunnelError(
+          `cloudflared did not open its local port for ${hostname} within ${STARTUP_TIMEOUT_MS / 1000} s: ${output.describe()}!`
+        )
+      }
+      await delay(PROBE_INTERVAL_MS)
+    }
+
+    let closed = false
+    let diedWith: string | null = null
+    const tunnel: Tunnel = {
+      route: { kind: 'localPort', host: LOOPBACK, port },
+      pinnedHostKey: null,
+      failure: () => {
+        // A service token Access did not accept falls back to the browser flow (non-strict organisations).
+        if (loginPrompted && config.authMethod === 'serviceToken') {
+          return new CloudflaredAuthError(
+            `Cloudflare Access asked for a browser sign-in although a service token is configured — check the client ID and secret, and that ${hostname} has a Service Auth policy!`
+          )
+        }
+        if (diedWith !== null) {
+          return new CloudflaredTunnelError(`Cloudflare tunnel to ${hostname} failed: ${diedWith}!`)
+        }
+        const reason = output.lastError()
+        return reason === null
+          ? null
+          : new CloudflaredTunnelError(`Cloudflare tunnel to ${hostname} failed: ${reason}!`)
+      },
+      close: async () => {
+        if (closed) return
+        closed = true
+        this.active.delete(tunnel)
+        await this.stop(child)
+        log.info(`Cloudflare tunnel to ${hostname} closed`)
+      }
+    }
+    this.active.add(tunnel)
+
+    void exited.then(({ code }) => {
+      if (closed) return
+      closed = true
+      this.active.delete(tunnel)
+      diedWith = `cloudflared exited${code !== null ? ` with code ${code}` : ''}: ${output.describe()}`
+      log.warn(`Cloudflare tunnel to ${hostname} dropped: ${diedWith}`)
+      onDropped?.(diedWith)
+    })
+
+    log.info(`Cloudflare tunnel to ${hostname} up on ${LOOPBACK}:${port}`)
+    return tunnel
+  }
+
+  private announceLogin(hostname: string, onPrompt: () => void): (line: string) => void {
+    return (line) => {
+      const url = findLoginUrl(line, hostname)
+      if (url === null) return
+      onPrompt()
+      this.onLogin({ hostname, state: 'waiting', url })
+    }
+  }
+
+  private launch(
+    command: string,
+    args: string[],
+    env: NodeJS.ProcessEnv,
+    onLine?: (line: string) => void
+  ): Launched {
+    if (this.closing) throw new CloudflaredTunnelError('MongoBench is shutting down!')
+    let child: ChildProcess
+    try {
+      child = this.runtime.spawn(command, args, env)
+    } catch (error) {
+      // Node refuses some spawns synchronously, e.g. UNKNOWN for a file that is no executable.
+      throw spawnFailure(command, error)
+    }
+    this.processes.add(child)
+
+    const output = new OutputTail()
+    for (const stream of [child.stdout, child.stderr]) {
+      if (stream === null) continue
+      stream.setEncoding('utf8')
+      const lines = splitLines((line) => {
+        output.add(line)
+        onLine?.(line)
+      })
+      stream.on('data', (chunk: string) => lines.write(chunk))
+      stream.on('end', () => lines.end())
+    }
+
+    let result: Exit | null = null
+    const exited = new Promise<Exit>((resolve) => {
+      // 'exit' may not follow 'error', and output can still be arriving at 'exit'.
+      child.once('close', (code: number | null) => resolve({ code, error: null }))
+      // Stays attached: an 'error' with no listener would take the main process down.
+      child.on('error', (error: Error) => resolve({ code: null, error }))
+    }).then((exit) => {
+      this.processes.delete(child)
+      result = exit
+      return exit
+    })
+    return { child, output, exited, ended: () => result }
+  }
+
+  private stop(child: ChildProcess): Promise<void> {
+    if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL')
+        resolve()
+      }, STOP_TIMEOUT_MS)
+      child.once('exit', () => {
+        clearTimeout(timer)
+        resolve()
+      })
+      child.kill()
+    })
+  }
+}
+
+function commandFor(binaryPath?: string): string {
+  if (binaryPath === undefined) return PATH_COMMAND
+  // Checked again here: the schema guards new input, not what connections.json already holds.
+  if (!isCloudflaredExecutable(binaryPath)) {
+    throw new CloudflaredNotFoundError(`${binaryPath} is not a cloudflared executable!`)
+  }
+  return binaryPath
+}
+
+function cleanEnv(): NodeJS.ProcessEnv {
+  // An inherited TUNNEL_SERVICE_* variable would silently change what this connection configures.
+  return Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('TUNNEL_SERVICE_'))
+  )
+}
+
+function tunnelEnv(config: ResolvedCloudflaredTunnel): NodeJS.ProcessEnv {
+  if (config.authMethod === 'browser') return cleanEnv()
+  const id = config.serviceTokenId ?? ''
+  const secret = config.serviceTokenSecret ?? ''
+  if (id.length === 0) throw new CloudflaredAuthError('No service token client ID is configured!')
+  if (secret.length === 0) {
+    throw new CloudflaredAuthError('No service token secret is stored for this connection!')
+  }
+  // Environment, not argv: argv shows up in process listings.
+  return { ...cleanEnv(), TUNNEL_SERVICE_TOKEN_ID: id, TUNNEL_SERVICE_TOKEN_SECRET: secret }
+}
+
+function spawnFailure(
+  command: string,
+  error: unknown
+): CloudflaredNotFoundError | CloudflaredTunnelError {
+  const code =
+    error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : null
+  if (code === null || !FILE_ERRORS.has(code)) {
+    // Only the code: Node's message for a refused environment quotes the value, which can be the token.
+    return new CloudflaredTunnelError(`Cannot start ${command}: ${code ?? 'unknown error'}!`, {
+      cause: error
+    })
+  }
+  const message =
+    command === PATH_COMMAND && code === 'ENOENT'
+      ? 'cloudflared was not found on PATH — install it or choose its executable in the connection settings!'
+      : `Cannot run ${command}: ${code}!`
+  return new CloudflaredNotFoundError(message, { cause: error })
+}
+
+function throwIfCancelled(signal: AbortSignal | undefined, hostname: string): void {
+  if (signal?.aborted === true) {
+    throw cancelledError(`Connecting to ${hostname} through Cloudflare Access was cancelled!`)
+  }
+}
+
+function startupFailure(
+  command: string,
+  hostname: string,
+  port: number,
+  exit: Exit,
+  output: OutputTail
+): Error {
+  if (exit.error !== null) return spawnFailure(command, exit.error)
+  // Matched on cloudflared's own wording; the OS part of the message after it is localized.
+  if (output.text().includes('failed to start forwarding server')) {
+    return new PortTakenError(
+      `cloudflared could not listen on ${LOOPBACK}:${port}: ${output.describe()}!`
+    )
+  }
+  return new CloudflaredTunnelError(
+    `cloudflared stopped before the tunnel to ${hostname} was up: ${output.describe()}!`
+  )
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
diff --git a/src/main/services/ConnectionService.test.ts b/src/main/services/ConnectionService.test.ts
new file mode 100644
index 0000000..ead4b50
--- /dev/null
+++ b/src/main/services/ConnectionService.test.ts
@@ -0,0 +1,430 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type {
+  ConnectionInput,
+  StoredCloudflaredTunnel,
+  StoredConnection,
+  StoredSshTunnel
+} from '@shared/types'
+import type { Tunnel, TunnelRoute } from '../lib/tunnel'
+import type { ConnectionsRepository } from '../stores/ConnectionsRepository'
+import type { CloudflaredTunnelService } from './CloudflaredTunnelService'
+import type { SshTunnelService } from './SshTunnelService'
+
+vi.mock('electron-log/main', () => ({
+  default: { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+}))
+// The repository module reads electron's userData path; these tests pass a fake repository.
+vi.mock('electron', () => ({ app: { getPath: () => '' } }))
+
+/** MongoClient stand-in: records how it was built; `connect` is steered per test. */
+const driver = vi.hoisted(() => {
+  const created: FakeMongoClient[] = []
+  const connect = vi.fn((): Promise<void> => Promise.resolve())
+  class FakeMongoClient {
+    readonly close = vi.fn((): Promise<void> => Promise.resolve())
+    readonly connect = connect
+    constructor(
+      readonly uri: string,
+      readonly options: Record<string, unknown>
+    ) {
+      created.push(this)
+    }
+    db(): { command: (command: Record<string, unknown>) => Promise<unknown> } {
+      return {
+        command: (command) => Promise.resolve('ping' in command ? { ok: 1 } : { version: '8.0.4' })
+      }
+    }
+  }
+  return { FakeMongoClient, created, connect }
+})
+vi.mock('mongodb', () => ({ MongoClient: driver.FakeMongoClient }))
+
+const { ConnectionService } = await import('./ConnectionService')
+
+const ID = '6f1d3c2a-8b4e-4f5a-9c7d-1e2f3a4b5c6d'
+const SOCKS_ROUTE: TunnelRoute = {
+  kind: 'socks5',
+  proxy: { proxyHost: '127.0.0.1', proxyPort: 1080, proxyUsername: 'u', proxyPassword: 'p' }
+}
+const LOCAL_ROUTE: TunnelRoute = { kind: 'localPort', host: '127.0.0.1', port: 5001 }
+const SSH: StoredSshTunnel = {
+  enabled: true,
+  host: 'gateway.example.com',
+  username: 'tunneluser',
+  authMethod: 'agent'
+}
+const CLOUDFLARED: StoredCloudflaredTunnel = {
+  enabled: true,
+  hostname: 'mongo.example.com',
+  authMethod: 'serviceToken',
+  serviceTokenId: 'abc.access',
+  encryptedServiceTokenSecret: 'enc:secret'
+}
+const STORED_SECRET = 'decrypted-token-secret'
+
+function stored(overrides: Partial<StoredConnection> = {}): StoredConnection {
+  return {
+    id: ID,
+    name: 'Production',
+    uri: 'mongodb://db.example.com:27017/admin',
+    createdAt: '2026-10-16T00:00:00.000Z',
+    updatedAt: '2026-10-16T00:00:00.000Z',
+    ...overrides
+  }
+}
+
+type Opened = { config: unknown; onDropped?: (reason: string) => void; tunnel: Tunnel }
+
+function fakeTunnels(route: TunnelRoute): {
+  service: { open: ReturnType<typeof vi.fn>; closeAll: ReturnType<typeof vi.fn> }
+  opened: Opened[]
+} {
+  const opened: Opened[] = []
+  const service = {
+    open: vi.fn((config: unknown, onDropped?: (reason: string) => void) => {
+      const tunnel: Tunnel = {
+        route,
+        pinnedHostKey: null,
+        failure: vi.fn((): Error | null => null),
+        close: vi.fn((): Promise<void> => Promise.resolve())
+      }
+      opened.push({ config, ...(onDropped !== undefined ? { onDropped } : {}), tunnel })
+      return Promise.resolve(tunnel)
+    }),
+    closeAll: vi.fn((): Promise<void> => Promise.resolve())
+  }
+  return { service, opened }
+}
+
+function setup(connections: StoredConnection[], options: { password?: string } = {}) {
+  const repo = {
+    getStored: vi.fn((id: string) => Promise.resolve(connections.find((c) => c.id === id) ?? null)),
+    decryptPassword: vi.fn(() => options.password ?? null),
+    decryptSsh: vi.fn(() => ({})),
+    decryptCloudflared: vi.fn((connection: StoredConnection) =>
+      connection.cloudflared?.encryptedServiceTokenSecret !== undefined
+        ? { serviceTokenSecret: STORED_SECRET }
+        : {}
+    )
+  }
+  const ssh = fakeTunnels(SOCKS_ROUTE)
+  const cloudflared = fakeTunnels(LOCAL_ROUTE)
+  const onDropped = vi.fn()
+  const service = new ConnectionService(
+    repo as unknown as ConnectionsRepository,
+    ssh.service as unknown as SshTunnelService,
+    cloudflared.service as unknown as CloudflaredTunnelService,
+    onDropped
+  )
+  return { service, repo, ssh, cloudflared, onDropped }
+}
+
+function deferred(): { promise: Promise<void>; resolve: () => void; reject: (e: unknown) => void } {
+  let resolve!: () => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+function createdAt(index: number): InstanceType<typeof driver.FakeMongoClient> {
+  const client = driver.created[index]
+  if (client === undefined) throw new Error(`no client at ${index}`)
+  return client
+}
+
+function openedAt(opened: Opened[], index: number): Opened {
+  const call = opened[index]
+  if (call === undefined) throw new Error(`no tunnel at ${index}`)
+  return call
+}
+
+function driverError(name: string): Error {
+  return Object.assign(new Error(`${name} from the driver`), { name })
+}
+
+afterEach(() => {
+  driver.created.length = 0
+  driver.connect.mockReset()
+  driver.connect.mockImplementation(() => Promise.resolve())
+})
+
+describe('connect', () => {
+  it('joins a connect already in flight instead of opening a second client and tunnel', async () => {
+    const { service, ssh } = setup([stored({ ssh: SSH })])
+    const gate = deferred()
+    driver.connect.mockImplementation(() => gate.promise)
+
+    const first = service.connect(ID)
+    const second = service.connect(ID)
+    await vi.waitFor(() => expect(driver.created).toHaveLength(1))
+    gate.resolve()
+
+    expect(await first).toEqual({ connectionId: ID })
+    expect(await second).toEqual({ connectionId: ID })
+    expect(driver.created).toHaveLength(1)
+    expect(ssh.service.open).toHaveBeenCalledTimes(1)
+    expect(service.isConnected(ID)).toBe(true)
+  })
+
+  it('lets a failed connect be retried', async () => {
+    const { service } = setup([stored()])
+    driver.connect.mockImplementationOnce(() =>
+      Promise.reject(driverError('MongoServerSelectionError'))
+    )
+
+    await expect(service.connect(ID)).rejects.toThrow('MongoServerSelectionError')
+    await expect(service.connect(ID)).resolves.toEqual({ connectionId: ID })
+    expect(driver.created).toHaveLength(2)
+    expect(createdAt(0).close).toHaveBeenCalled()
+  })
+})
+
+describe('disconnect', () => {
+  it('waits for a connect in flight and then closes what it opened', async () => {
+    const { service, ssh } = setup([stored({ ssh: SSH })])
+    const gate = deferred()
+    driver.connect.mockImplementation(() => gate.promise)
+
+    const connecting = service.connect(ID)
+    await vi.waitFor(() => expect(driver.created).toHaveLength(1))
+    let disconnected = false
+    const disconnecting = service.disconnect(ID).then(() => {
+      disconnected = true
+    })
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    expect(disconnected).toBe(false)
+
+    gate.resolve()
+    await connecting
+    await disconnecting
+
+    expect(service.isConnected(ID)).toBe(false)
+    expect(createdAt(0).close).toHaveBeenCalled()
+    expect(openedAt(ssh.opened, 0).tunnel.close).toHaveBeenCalled()
+  })
+
+  it('aborts a Cloudflare sign-in in flight instead of waiting for it', async () => {
+    const { service, cloudflared } = setup([
+      stored({ cloudflared: { ...CLOUDFLARED, authMethod: 'browser' } })
+    ])
+    cloudflared.service.open.mockImplementationOnce(
+      (_config: unknown, _onDropped: unknown, signal?: AbortSignal) =>
+        new Promise<Tunnel>((_resolve, reject) => {
+          signal?.addEventListener('abort', () =>
+            reject(Object.assign(new Error('sign-in cancelled'), { name: 'CancelledError' }))
+          )
+        })
+    )
+
+    const connecting = service.connect(ID).catch((e: unknown) => e)
+    await vi.waitFor(() => expect(cloudflared.service.open).toHaveBeenCalled())
+    await service.disconnect(ID)
+
+    expect(((await connecting) as Error).name).toBe('CancelledError')
+    expect(service.isConnected(ID)).toBe(false)
+    expect(driver.created).toHaveLength(0)
+  })
+
+  it('still returns when the connect in flight fails', async () => {
+    const { service } = setup([stored()])
+    const gate = deferred()
+    driver.connect.mockImplementation(() => gate.promise)
+
+    const connecting = service.connect(ID).catch((e: unknown) => e)
+    await vi.waitFor(() => expect(driver.created).toHaveLength(1))
+    const disconnecting = service.disconnect(ID)
+    gate.reject(driverError('MongoServerSelectionError'))
+
+    await disconnecting
+    expect(await connecting).toBeInstanceOf(Error)
+    expect(service.isConnected(ID)).toBe(false)
+  })
+})
+
+describe('tunnel drops', () => {
+  it('closes the connection when its own tunnel dies', async () => {
+    const { service, ssh, onDropped } = setup([stored({ ssh: SSH })])
+    await service.connect(ID)
+
+    openedAt(ssh.opened, 0).onDropped?.('the SSH connection closed')
+
+    expect(service.isConnected(ID)).toBe(false)
+    expect(createdAt(0).close).toHaveBeenCalled()
+    expect(onDropped).toHaveBeenCalledWith(ID, 'the SSH connection closed')
+  })
+
+  it('ignores the death of a tunnel that belonged to an earlier connection', async () => {
+    const { service, ssh, onDropped } = setup([stored({ ssh: SSH })])
+    await service.connect(ID)
+    await service.disconnect(ID)
+    await service.connect(ID)
+
+    openedAt(ssh.opened, 0).onDropped?.('stale tunnel died')
+
+    expect(service.isConnected(ID)).toBe(true)
+    expect(createdAt(1).close).not.toHaveBeenCalled()
+    expect(onDropped).not.toHaveBeenCalled()
+  })
+})
+
+describe('Cloudflare tunnel', () => {
+  it('points the driver at the tunnel port with the stored secret decrypted', async () => {
+    const { service, ssh, cloudflared } = setup(
+      [
+        stored({
+          uri: 'mongodb://alice:%3CMONGOBENCH_PWD%3E@Mongo.Example.com:27017/admin?tls=true',
+          username: 'alice',
+          encryptedPassword: 'enc:pw',
+          cloudflared: CLOUDFLARED
+        })
+      ],
+      { password: 'mongo-pw' }
+    )
+
+    await service.connect(ID)
+
+    expect(cloudflared.service.open).toHaveBeenCalledWith(
+      {
+        hostname: 'mongo.example.com',
+        authMethod: 'serviceToken',
+        serviceTokenId: 'abc.access',
+        serviceTokenSecret: STORED_SECRET
+      },
+      expect.any(Function),
+      expect.any(AbortSignal)
+    )
+    expect(ssh.service.open).not.toHaveBeenCalled()
+    const client = createdAt(0)
+    expect(client.uri).toBe('mongodb://alice:mongo-pw@127.0.0.1:5001/admin?tls=true')
+    expect(client.options).toMatchObject({
+      directConnection: true,
+      servername: 'mongo.example.com'
+    })
+  })
+
+  it('leaves a switched-off Cloudflare section alone', async () => {
+    const { service, cloudflared } = setup([
+      stored({ cloudflared: { ...CLOUDFLARED, enabled: false } })
+    ])
+    await service.connect(ID)
+    expect(cloudflared.service.open).not.toHaveBeenCalled()
+    expect(createdAt(0).uri).toBe('mongodb://db.example.com:27017/admin')
+  })
+
+  it('refuses a stored connection with both tunnels switched on', async () => {
+    const { service, ssh, cloudflared } = setup([stored({ ssh: SSH, cloudflared: CLOUDFLARED })])
+
+    const error = await service.connect(ID).catch((e: unknown) => e)
+    expect((error as Error).name).toBe('ValidationError')
+    expect(ssh.service.open).not.toHaveBeenCalled()
+    expect(cloudflared.service.open).not.toHaveBeenCalled()
+  })
+
+  it("reports the tunnel's own error instead of a driver timeout", async () => {
+    const { service, cloudflared } = setup([stored({ cloudflared: CLOUDFLARED })])
+    const reason = Object.assign(new Error('Cloudflare tunnel failed: bad handshake!'), {
+      name: 'CloudflaredTunnelError'
+    })
+    cloudflared.service.open.mockImplementationOnce(() =>
+      Promise.resolve({
+        route: LOCAL_ROUTE,
+        pinnedHostKey: null,
+        failure: () => reason,
+        close: vi.fn(() => Promise.resolve())
+      })
+    )
+    driver.connect.mockImplementation(() =>
+      Promise.reject(driverError('MongoServerSelectionError'))
+    )
+
+    await expect(service.connect(ID)).rejects.toBe(reason)
+    expect(createdAt(0).close).toHaveBeenCalled()
+  })
+
+  it('never hides a MongoDB authentication error behind the tunnel', async () => {
+    const { service, cloudflared } = setup([stored({ cloudflared: CLOUDFLARED })])
+    cloudflared.service.open.mockImplementationOnce(() =>
+      Promise.resolve({
+        route: LOCAL_ROUTE,
+        pinnedHostKey: null,
+        failure: () => new Error('tunnel trouble'),
+        close: vi.fn(() => Promise.resolve())
+      })
+    )
+    const authError = driverError('MongoAuthenticationError')
+    driver.connect.mockImplementation(() => Promise.reject(authError))
+
+    await expect(service.connect(ID)).rejects.toBe(authError)
+  })
+})
+
+describe('test', () => {
+  const input: ConnectionInput = {
+    name: 'Production',
+    uri: 'mongodb://localhost/admin',
+    cloudflared: {
+      enabled: true,
+      hostname: 'mongo.example.com',
+      authMethod: 'serviceToken',
+      serviceTokenId: 'abc.access',
+      serviceTokenSecret: ''
+    }
+  }
+
+  it('runs through a Cloudflare tunnel, using the saved secret when the form left it blank', async () => {
+    const { service, cloudflared } = setup([stored({ cloudflared: CLOUDFLARED })])
+
+    const result = await service.test(input, ID)
+
+    expect(result).toMatchObject({ ok: true, serverVersion: '8.0.4' })
+    expect(cloudflared.service.open).toHaveBeenCalledWith({
+      hostname: 'mongo.example.com',
+      authMethod: 'serviceToken',
+      serviceTokenId: 'abc.access',
+      serviceTokenSecret: STORED_SECRET
+    })
+    expect(createdAt(0).uri).toBe('mongodb://127.0.0.1:5001/admin')
+    expect(openedAt(cloudflared.opened, 0).tunnel.close).toHaveBeenCalled()
+    expect(createdAt(0).close).toHaveBeenCalled()
+  })
+
+  it.each([
+    ['another hostname', { hostname: 'other-app.attacker.invalid' }],
+    ['another client ID', { serviceTokenId: 'other.access' }]
+  ])('never sends the saved secret to %s', async (_case, edit) => {
+    const { service, cloudflared } = setup([stored({ cloudflared: CLOUDFLARED })])
+    const edited = { ...input, cloudflared: { ...input.cloudflared!, ...edit } }
+
+    await service.test(edited, ID)
+
+    const opened = openedAt(cloudflared.opened, 0).config as Record<string, unknown>
+    expect(opened).toMatchObject(edit)
+    expect(opened).not.toHaveProperty('serviceTokenSecret')
+  })
+
+  it('closes the tunnel when the connection string cannot go through it', async () => {
+    const { service, cloudflared } = setup([])
+
+    await expect(
+      service.test({ ...input, uri: 'mongodb+srv://cluster.example.com/admin' })
+    ).rejects.toThrow('mongodb+srv://')
+    expect(openedAt(cloudflared.opened, 0).tunnel.close).toHaveBeenCalled()
+  })
+})
+
+describe('closeAll', () => {
+  it('closes the connections, then sweeps both tunnel services', async () => {
+    const { service, ssh, cloudflared } = setup([stored()])
+    await service.connect(ID)
+
+    await service.closeAll()
+
+    expect(service.isConnected(ID)).toBe(false)
+    expect(createdAt(0).close).toHaveBeenCalled()
+    expect(ssh.service.closeAll).toHaveBeenCalled()
+    expect(cloudflared.service.closeAll).toHaveBeenCalled()
+  })
+})
diff --git a/src/main/services/ConnectionService.ts b/src/main/services/ConnectionService.ts
index 3f674b5..572d7ce 100644
--- a/src/main/services/ConnectionService.ts
+++ b/src/main/services/ConnectionService.ts
@@ -1,10 +1,13 @@
 import { MongoClient, type MongoClientOptions } from 'mongodb'
 import log from 'electron-log/main'
+import { canReuseServiceTokenSecret } from '@shared/cloudflared'
 import {
   DEFAULT_SSH_PORT,
+  type CloudflaredTunnelInput,
   type ConnectionInput,
   type ConnectionTestResult,
   type ConnectResult,
+  type StoredCloudflaredTunnel,
   type StoredSshTunnel,
   type SshTunnelInput,
   type StoredConnection
@@ -19,7 +22,13 @@ import {
   injectExternalCredentials,
   injectStoredPassword
 } from '../lib/connectionUri'
-import type { ResolvedSshTunnel, SshTunnelService, Tunnel } from './SshTunnelService'
+import { validationError } from '../lib/errorMap'
+import { applyTunnelRoute, preferTunnelFailure, type Tunnel } from '../lib/tunnel'
+import type {
+  CloudflaredTunnelService,
+  ResolvedCloudflaredTunnel
+} from './CloudflaredTunnelService'
+import type { ResolvedSshTunnel, SshTunnelService } from './SshTunnelService'
 
 const DEFAULT_TIMEOUT = 3000
 
@@ -43,10 +52,16 @@ type Active = { client: MongoClient; tunnel: Tunnel | null }
  */
 export class ConnectionService {
   private clients = new Map<string, Active>()
+  /** Connects still in progress, so a second request joins the first and a disconnect can abort it. */
+  private readonly pending = new Map<
+    string,
+    { opening: Promise<ConnectResult>; controller: AbortController }
+  >()
 
   constructor(
     private readonly repo: ConnectionsRepository,
-    private readonly tunnels: SshTunnelService,
+    private readonly sshTunnels: SshTunnelService,
+    private readonly cloudflaredTunnels: CloudflaredTunnelService,
     /** Called when main takes a connection down by itself. */
     private readonly onDropped: (connectionId: string, reason: string) => void
   ) {}
@@ -63,20 +78,15 @@ export class ConnectionService {
     const uri = await this.materializeFromInput(input, existingId)
     // A probe's tunnel is nobody else's: it is closed in the finally below, and
     // its death needs no drop callback — the in-flight ping reports it.
-    const tunnel =
-      input.ssh?.enabled === true
-        ? await this.tunnels.open(await this.resolveSshFromInput(input.ssh, existingId))
-        : null
+    const tunnel = await this.openTunnelFromInput(input, existingId)
 
     const startedAt = Date.now()
     let client: MongoClient | null = null
     try {
       // Inside the try: the constructor parses the URI and throws on a bad
       // option, which would otherwise leak the tunnel.
-      client = new MongoClient(uri, {
-        ...this.optionsFromInput(input),
-        ...(tunnel?.proxyOptions ?? {})
-      })
+      const target = routeThrough(tunnel, uri, this.optionsFromInput(input))
+      client = new MongoClient(target.uri, target.options)
       await client.connect()
       const ping = (await client.db('admin').command({ ping: 1 })) as { ok?: number }
       const buildInfo = (await client.db('admin').command({ buildInfo: 1 })) as {
@@ -88,6 +98,8 @@ export class ConnectionService {
         ...(buildInfo.version !== undefined ? { serverVersion: buildInfo.version } : {}),
         ...(tunnel?.pinnedHostKey ? { pinnedHostKey: tunnel.pinnedHostKey } : {})
       }
+    } catch (error) {
+      throw preferTunnelFailure(error, tunnel)
     } finally {
       await client?.close().catch(() => undefined)
       await tunnel?.close().catch(() => undefined)
@@ -96,39 +108,20 @@ export class ConnectionService {
 
   async connect(id: string): Promise<ConnectResult> {
     if (this.clients.has(id)) return { connectionId: id }
-    const stored = await this.repo.getStored(id)
-    if (!stored) throw new ConnectionNotFoundError(id)
-    const uri = this.materializeFromStored(stored)
-
-    const ssh = stored.ssh
-    const tunnel =
-      ssh?.enabled === true
-        ? await this.tunnels.open(this.resolveSshFromStored(stored, ssh), (reason) =>
-            this.dropConnection(id, reason)
-          )
-        : null
-
-    let client: MongoClient | null = null
-    try {
-      client = new MongoClient(uri, {
-        ...this.optionsFromStored(stored),
-        ...(tunnel?.proxyOptions ?? {})
-      })
-      await client.connect()
-    } catch (error) {
-      await client?.close().catch(() => undefined)
-      await tunnel?.close().catch(() => undefined)
-      throw error
-    }
-    this.clients.set(id, { client, tunnel })
-    log.info(`Connected ${stored.name} (${id})`)
-    return {
-      connectionId: id,
-      ...(tunnel?.pinnedHostKey ? { pinnedHostKey: tunnel.pinnedHostKey } : {})
-    }
+    const inflight = this.pending.get(id)
+    if (inflight !== undefined) return inflight.opening
+    const controller = new AbortController()
+    const opening = this.open(id, controller.signal).finally(() => this.pending.delete(id))
+    this.pending.set(id, { opening, controller })
+    return opening
   }
 
   async disconnect(id: string): Promise<void> {
+    const inflight = this.pending.get(id)
+    // Stops a browser sign-in nobody will finish instead of waiting out its timeout.
+    inflight?.controller.abort()
+    // A connect still in flight would otherwise register its client after this returned.
+    await inflight?.opening.catch(() => undefined)
     const active = this.clients.get(id)
     if (!active) return
     this.clients.delete(id)
@@ -144,7 +137,7 @@ export class ConnectionService {
     const ids = [...this.clients.keys()]
     await Promise.allSettled(ids.map((id) => this.disconnect(id)))
     // Sweeps anything a failed open left behind.
-    await this.tunnels.closeAll()
+    await Promise.allSettled([this.sshTunnels.closeAll(), this.cloudflaredTunnels.closeAll()])
   }
 
   isConnected(id: string): boolean {
@@ -157,16 +150,89 @@ export class ConnectionService {
     return active.client
   }
 
+  private async open(id: string, signal: AbortSignal): Promise<ConnectResult> {
+    const stored = await this.repo.getStored(id)
+    if (!stored) throw new ConnectionNotFoundError(id)
+    const uri = this.materializeFromStored(stored)
+
+    // Bound before the open so the drop callback can tell this tunnel from a later one.
+    let tunnel: Tunnel | null = null
+    tunnel = await this.openTunnelFromStored(
+      stored,
+      (reason) => this.dropConnection(id, tunnel, reason),
+      signal
+    )
+
+    let client: MongoClient | null = null
+    try {
+      const target = routeThrough(tunnel, uri, this.optionsFromStored(stored))
+      client = new MongoClient(target.uri, target.options)
+      await client.connect()
+    } catch (error) {
+      // Asked before the tunnel closes, while it still knows why traffic failed.
+      const reported = preferTunnelFailure(error, tunnel)
+      await client?.close().catch(() => undefined)
+      await tunnel?.close().catch(() => undefined)
+      throw reported
+    }
+    this.clients.set(id, { client, tunnel })
+    log.info(`Connected ${stored.name} (${id})`)
+    return {
+      connectionId: id,
+      ...(tunnel?.pinnedHostKey ? { pinnedHostKey: tunnel.pinnedHostKey } : {})
+    }
+  }
+
   /** The tunnel died on its own; the client on top of it is finished too. */
-  private dropConnection(id: string, reason: string): void {
+  private dropConnection(id: string, tunnel: Tunnel | null, reason: string): void {
     const active = this.clients.get(id)
-    if (active === undefined) return
+    // A tunnel outliving its connection must not take down a newer one under the same id.
+    if (active === undefined || active.tunnel !== tunnel) return
     this.clients.delete(id)
     void active.client.close().catch(() => undefined)
-    log.warn(`Closed ${id} because its SSH tunnel dropped: ${reason}`)
+    log.warn(`Closed ${id} because its tunnel dropped: ${reason}`)
     this.onDropped(id, reason)
   }
 
+  private async openTunnelFromInput(
+    input: ConnectionInput,
+    existingId?: string
+  ): Promise<Tunnel | null> {
+    if (input.ssh?.enabled === true) {
+      return this.sshTunnels.open(await this.resolveSshFromInput(input.ssh, existingId))
+    }
+    if (input.cloudflared?.enabled === true) {
+      return this.cloudflaredTunnels.open(
+        await this.resolveCloudflaredFromInput(input.cloudflared, existingId)
+      )
+    }
+    return null
+  }
+
+  private async openTunnelFromStored(
+    stored: StoredConnection,
+    onDropped: (reason: string) => void,
+    signal: AbortSignal
+  ): Promise<Tunnel | null> {
+    const { ssh, cloudflared } = stored
+    if (ssh?.enabled === true && cloudflared?.enabled === true) {
+      throw validationError(
+        `Connection ${stored.id} has both an SSH and a Cloudflare tunnel switched on`
+      )
+    }
+    if (ssh?.enabled === true) {
+      return this.sshTunnels.open(this.resolveSshFromStored(stored, ssh), onDropped)
+    }
+    if (cloudflared?.enabled === true) {
+      return this.cloudflaredTunnels.open(
+        this.resolveCloudflaredFromStored(stored, cloudflared),
+        onDropped,
+        signal
+      )
+    }
+    return null
+  }
+
   /**
    * Per-connection toggle: when true, the explorer should only list
    * databases / collections the authenticated user has privileges on.
@@ -258,6 +324,45 @@ export class ConnectionService {
     }
   }
 
+  private resolveCloudflaredFromStored(
+    stored: StoredConnection,
+    cloudflared: StoredCloudflaredTunnel
+  ): ResolvedCloudflaredTunnel {
+    const { serviceTokenSecret } = this.repo.decryptCloudflared(stored)
+    return {
+      hostname: cloudflared.hostname,
+      authMethod: cloudflared.authMethod,
+      ...(cloudflared.serviceTokenId !== undefined
+        ? { serviceTokenId: cloudflared.serviceTokenId }
+        : {}),
+      ...(serviceTokenSecret !== undefined ? { serviceTokenSecret } : {}),
+      ...(cloudflared.binaryPath !== undefined ? { binaryPath: cloudflared.binaryPath } : {})
+    }
+  }
+
+  private async resolveCloudflaredFromInput(
+    input: CloudflaredTunnelInput,
+    existingId?: string
+  ): Promise<ResolvedCloudflaredTunnel> {
+    let serviceTokenSecret = nonEmpty(input.serviceTokenSecret)
+    if (serviceTokenSecret === undefined && existingId !== undefined) {
+      const stored = await this.repo.getStored(existingId)
+      // A blank secret means the saved one, but only for the hostname and client ID it was saved for.
+      if (stored && canReuseServiceTokenSecret(stored.cloudflared, input)) {
+        serviceTokenSecret = this.repo.decryptCloudflared(stored).serviceTokenSecret
+      }
+    }
+    const serviceTokenId = nonEmpty(input.serviceTokenId)
+    const binaryPath = nonEmpty(input.binaryPath)
+    return {
+      hostname: input.hostname,
+      authMethod: input.authMethod,
+      ...(serviceTokenId !== undefined ? { serviceTokenId } : {}),
+      ...(serviceTokenSecret !== undefined ? { serviceTokenSecret } : {}),
+      ...(binaryPath !== undefined ? { binaryPath } : {})
+    }
+  }
+
   private optionsFromInput(input: ConnectionInput): MongoClientOptions {
     return buildOptions({
       serverSelectionTimeoutMS: input.serverSelectionTimeoutMS,
@@ -301,6 +406,14 @@ function nonEmpty(value: string | undefined): string | undefined {
   return value !== undefined && value.length > 0 ? value : undefined
 }
 
+function routeThrough(
+  tunnel: Tunnel | null,
+  uri: string,
+  options: MongoClientOptions
+): { uri: string; options: MongoClientOptions } {
+  return tunnel === null ? { uri, options } : applyTunnelRoute(uri, options, tunnel.route)
+}
+
 type DriverInputs = {
   serverSelectionTimeoutMS?: number
   appName?: string
diff --git a/src/main/services/DatabaseService.test.ts b/src/main/services/DatabaseService.test.ts
new file mode 100644
index 0000000..db4887f
--- /dev/null
+++ b/src/main/services/DatabaseService.test.ts
@@ -0,0 +1,329 @@
+import { describe, expect, it } from 'vitest'
+import { BSON, BSONRegExp, Double, Int32, Long, ObjectId, type Document } from 'bson'
+import { MongoServerError } from 'mongodb'
+import { mapError } from '../lib/errorMap'
+import { DatabaseService, databasesFromPrivileges } from './DatabaseService'
+import type { ConnectionService } from './ConnectionService'
+
+type Doc = Record<string, unknown>
+type Stage = Record<string, unknown>
+
+// Privileges as `connectionStatus` with `showPrivileges` reports them for readAnyDatabase.
+const READ_ANY_DATABASE = [
+  { resource: { db: '', collection: '' }, actions: ['find', 'listCollections'] },
+  { resource: { cluster: true }, actions: ['listDatabases'] },
+  { resource: { db: '', collection: 'system.js' }, actions: ['find'] }
+]
+
+const READ_WRITE_APP = [
+  { resource: { db: 'app', collection: '' }, actions: ['find', 'insert', 'update', 'remove'] },
+  { resource: { db: 'app', collection: 'system.js' }, actions: ['find', 'insert'] }
+]
+
+const ALL_DATABASES = [
+  { name: 'admin', sizeOnDisk: 40960, empty: false },
+  { name: 'app', sizeOnDisk: 81920, empty: false },
+  { name: 'reports', sizeOnDisk: 8192, empty: false }
+]
+
+/** Client double for the commands `listDatabases` and `collectionStats` send. */
+function serviceFor(opts: {
+  authorizedOnly?: boolean
+  privileges?: Doc[]
+  collStats?: Doc[]
+  estimatedCount?: number
+}): DatabaseService {
+  const client = {
+    db: () => ({
+      admin: () => ({ listDatabases: async () => ({ databases: ALL_DATABASES }) }),
+      command: async () => ({
+        authInfo: {
+          authenticatedUsers: [{ user: 'reporter', db: 'admin' }],
+          authenticatedUserPrivileges: opts.privileges ?? []
+        }
+      }),
+      collection: () => ({
+        aggregate: (pipeline: Stage[]) => ({
+          toArray: async () => {
+            const docs = opts.collStats ?? []
+            const limit = pipeline.find((s) => '$limit' in s)?.['$limit']
+            return typeof limit === 'number' ? docs.slice(0, limit) : docs
+          }
+        }),
+        estimatedDocumentCount: async () => opts.estimatedCount ?? 0
+      })
+    })
+  }
+  const connections = {
+    getClient: () => client,
+    isAuthorizedOnly: async () => opts.authorizedOnly ?? false
+  }
+  return new DatabaseService(connections as unknown as ConnectionService)
+}
+
+describe('databasesFromPrivileges', () => {
+  it('treats the any-database resource of readAnyDatabase as every database', () => {
+    expect(databasesFromPrivileges(READ_ANY_DATABASE)).toBe('all')
+  })
+
+  it('collects the databases of db-scoped privileges', () => {
+    expect(databasesFromPrivileges(READ_WRITE_APP)).toEqual(new Set(['app']))
+  })
+
+  it('treats anyResource as every database', () => {
+    expect(databasesFromPrivileges([{ resource: { anyResource: true } }])).toBe('all')
+  })
+
+  it('returns an empty set for no privileges', () => {
+    expect(databasesFromPrivileges([])).toEqual(new Set())
+  })
+})
+
+describe('DatabaseService.listDatabases', () => {
+  it('lists every database for a readAnyDatabase user with authorized-only on', async () => {
+    const service = serviceFor({ authorizedOnly: true, privileges: READ_ANY_DATABASE })
+
+    const databases = await service.listDatabases('c1')
+
+    expect(databases.map((d) => d.name)).toEqual(['admin', 'app', 'reports'])
+  })
+
+  it('keeps only the granted databases for a db-scoped user', async () => {
+    const service = serviceFor({ authorizedOnly: true, privileges: READ_WRITE_APP })
+
+    const databases = await service.listDatabases('c1')
+
+    expect(databases.map((d) => d.name)).toEqual(['app'])
+  })
+})
+
+describe('DatabaseService.collectionStats', () => {
+  it('sums the storage stats of every shard', async () => {
+    const service = serviceFor({
+      collStats: [
+        {
+          ns: 'app.players',
+          shard: 'shard-a',
+          storageStats: {
+            count: 1_000_000,
+            size: 100_000_000,
+            avgObjSize: 100,
+            storageSize: 40_000_000,
+            freeStorageSize: 1000,
+            totalIndexSize: 20_000_000,
+            totalSize: 60_000_000,
+            indexSizes: { _id_: 20_000_000 },
+            nindexes: 1,
+            capped: false
+          }
+        },
+        {
+          ns: 'app.players',
+          shard: 'shard-b',
+          storageStats: {
+            count: 1_000_000,
+            size: 300_000_000,
+            avgObjSize: 300,
+            storageSize: 80_000_000,
+            freeStorageSize: 0,
+            totalIndexSize: 25_000_000,
+            totalSize: 105_000_000,
+            indexSizes: { _id_: 25_000_000 },
+            nindexes: 1,
+            capped: false
+          }
+        }
+      ]
+    })
+
+    const stats = await service.collectionStats('c1', 'app', 'players')
+
+    expect(stats).toEqual({
+      ns: 'app.players',
+      count: 2_000_000,
+      size: 400_000_000,
+      storageSize: 120_000_000,
+      freeStorageSize: 1000,
+      avgObjSize: 200,
+      totalIndexSize: 45_000_000,
+      indexSizes: { _id_: 45_000_000 },
+      nindexes: 1,
+      capped: false,
+      totalSize: 165_000_000
+    })
+  })
+
+  it('counts a time-series collection, whose storage stats carry no count, from metadata', async () => {
+    const service = serviceFor({
+      estimatedCount: 50,
+      collStats: [
+        {
+          ns: 'app.system.buckets.readings',
+          storageStats: {
+            size: 959,
+            storageSize: 20480,
+            freeStorageSize: 0,
+            totalIndexSize: 4096,
+            totalSize: 24576,
+            indexSizes: { meta_1_ts_1: 4096 },
+            nindexes: 1,
+            capped: false,
+            timeseries: { bucketsNs: 'app.system.buckets.readings', bucketCount: 3 }
+          }
+        }
+      ]
+    })
+
+    const stats = await service.collectionStats('c1', 'app', 'readings')
+
+    expect(stats).toMatchObject({ count: 50, size: 959, avgObjSize: 959 / 50 })
+  })
+
+  it('reports avgObjSize 0 for an empty collection', async () => {
+    const service = serviceFor({
+      collStats: [{ ns: 'app.empty', storageStats: { count: 0, size: 0 } }]
+    })
+
+    const stats = await service.collectionStats('c1', 'app', 'empty')
+
+    expect(stats).toMatchObject({ count: 0, avgObjSize: 0 })
+  })
+
+  it('fails with DocumentNotFoundError when collStats returns nothing', async () => {
+    const service = serviceFor({ collStats: [] })
+
+    await expect(service.collectionStats('c1', 'app', 'players')).rejects.toMatchObject({
+      name: 'DocumentNotFoundError'
+    })
+  })
+})
+
+type ReadOptions = {
+  raw?: boolean
+  promoteValues?: boolean
+  bsonRegExp?: boolean
+  maxTimeMS?: number
+  limit?: number
+}
+
+/**
+ * Client double that stores BSON bytes and answers reads like the driver: raw bytes with `raw`,
+ * else decoded with the read's options; a `failure` reply is decoded with the same options.
+ */
+function schemaServiceFor(opts: {
+  type: 'collection' | 'view'
+  docs: Document[]
+  failure?: { code: number; errmsg: string }
+}) {
+  const bytes = opts.docs.map((d) => BSON.serialize(d))
+  const reads: Array<{ op: 'find' | 'aggregate'; arg: unknown; options: ReadOptions }> = []
+  const cursor = (options: ReadOptions) =>
+    (async function* () {
+      const bsonOptions = {
+        promoteValues: options.promoteValues,
+        bsonRegExp: options.bsonRegExp,
+        raw: options.raw
+      }
+      if (opts.failure) {
+        const reply = BSON.serialize({ ok: 0, ...opts.failure })
+        throw new MongoServerError(BSON.deserialize(reply, bsonOptions))
+      }
+      for (const b of bytes) yield options.raw ? b : BSON.deserialize(b, bsonOptions)
+    })()
+  const client = {
+    db: () => ({
+      listCollections: (filter: { name: string }) => ({
+        toArray: async () => [{ name: filter.name, type: opts.type }]
+      }),
+      collection: () => ({
+        find: (filter: unknown, options: ReadOptions) => {
+          reads.push({ op: 'find', arg: filter, options })
+          return cursor(options)
+        },
+        aggregate: (pipeline: unknown, options: ReadOptions) => {
+          reads.push({ op: 'aggregate', arg: pipeline, options })
+          return cursor(options)
+        }
+      })
+    })
+  }
+  const connections = { getClient: () => client }
+  return { service: new DatabaseService(connections as unknown as ConnectionService), reads }
+}
+
+describe('DatabaseService.collectionSchema', () => {
+  const docs = [
+    {
+      _id: new ObjectId(),
+      qty: new Int32(5),
+      price: new Double(5),
+      big: Long.fromNumber(7),
+      re: new BSONRegExp('dot.all', 's')
+    },
+    {
+      _id: new ObjectId(),
+      qty: new Int32(6),
+      price: new Double(2.5),
+      big: Long.fromNumber(8),
+      re: new BSONRegExp('(?i)abc', '')
+    }
+  ]
+
+  it('samples a collection with $sample and keeps the stored types', async () => {
+    const { service, reads } = schemaServiceFor({ type: 'collection', docs })
+
+    const schema = await service.collectionSchema('c1', 'app', 'orders')
+
+    expect(reads).toEqual([
+      {
+        op: 'aggregate',
+        arg: [{ $sample: { size: 200 } }],
+        options: { raw: true, maxTimeMS: 5000 }
+      }
+    ])
+    expect(schema.sampleSize).toBe(2)
+    expect(schema.fields.map((f) => [f.path, f.types])).toEqual([
+      ['_id', { objectId: 2 }],
+      ['big', { long: 2 }],
+      ['price', { double: 2 }],
+      ['qty', { int: 2 }],
+      ['re', { regex: 2 }]
+    ])
+  })
+
+  it('reads a view with a limited find instead of $sample', async () => {
+    const { service, reads } = schemaServiceFor({ type: 'view', docs })
+
+    const schema = await service.collectionSchema('c1', 'app', 'orders_view')
+
+    expect(reads).toEqual([
+      { op: 'find', arg: {}, options: { raw: true, maxTimeMS: 5000, limit: 200 } }
+    ])
+    expect(schema.sampleSize).toBe(2)
+  })
+
+  it('keeps the server error code a number when sampling fails', async () => {
+    const { service } = schemaServiceFor({
+      type: 'collection',
+      docs,
+      failure: { code: 189, errmsg: 'Primary stepped down' }
+    })
+
+    const error = await service.collectionSchema('c1', 'app', 'orders').then(
+      () => null,
+      (e: unknown) => e
+    )
+
+    expect(mapError(error)).toMatchObject({ code: 'driver_error', details: { mongoCode: 189 } })
+  })
+
+  it('returns an empty schema for an empty collection', async () => {
+    const { service } = schemaServiceFor({ type: 'collection', docs: [] })
+
+    await expect(service.collectionSchema('c1', 'app', 'empty')).resolves.toEqual({
+      sampleSize: 0,
+      fields: [],
+      truncated: false
+    })
+  })
+})
diff --git a/src/main/services/DatabaseService.ts b/src/main/services/DatabaseService.ts
index 3363dbc..49b28d1 100644
--- a/src/main/services/DatabaseService.ts
+++ b/src/main/services/DatabaseService.ts
@@ -1,8 +1,29 @@
 import type { MongoClient } from 'mongodb'
-import type { CollectionInfo, CollectionStats, DatabaseInfo, ServerStats } from '@shared/types'
+import { createSchemaBuilder } from '@shared/collectionSchema'
+import type {
+  CollectionInfo,
+  CollectionSchema,
+  CollectionStats,
+  DatabaseInfo,
+  ServerStats
+} from '@shared/types'
+import { decodeDocument, toCanonical } from '../lib/ejson'
+import { validationError } from '../lib/errorMap'
+import { mergeStorageStats } from '../lib/storageStats'
 import type { ConnectionService } from './ConnectionService'
 
 const COLLECTION_NAME_RE = /^[^$\0]+$/
+const SCHEMA_SAMPLE_SIZE = 200
+const SCHEMA_SAMPLE_MAX_TIME_MS = 5_000
+
+type Privilege = {
+  resource?: {
+    db?: string
+    collection?: string
+    cluster?: boolean
+    anyResource?: boolean
+  }
+}
 
 /** Metadata + light mutating operations on databases and collections. */
 export class DatabaseService {
@@ -44,27 +65,28 @@ export class DatabaseService {
   }
 
   async collectionStats(connectionId: string, db: string, coll: string): Promise<CollectionStats> {
-    const client = this.connections.getClient(connectionId)
-    const cursor = client
-      .db(db)
-      .collection(coll)
-      .aggregate([{ $collStats: { storageStats: {} } }, { $limit: 1 }])
+    const collection = this.connections.getClient(connectionId).db(db).collection(coll)
+    const cursor = collection.aggregate([{ $collStats: { storageStats: {} } }])
     const docs = await cursor.toArray()
-    const first = docs[0]
-    if (!first) {
+    if (docs.length === 0) {
       const e = new Error(`collStats returned no result for ${db}.${coll}`)
       e.name = 'DocumentNotFoundError'
       throw e
     }
-    const ns = (first['ns'] as string) ?? `${db}.${coll}`
-    const s = (first['storageStats'] as Record<string, unknown>) ?? {}
+    const merged = mergeStorageStats(docs)
+    const ns = merged.ns ?? `${db}.${coll}`
+    const s = merged.storage
+    // Time-series collections report the storage of their buckets but no document count.
+    const count =
+      typeof s['count'] === 'number' ? s['count'] : await collection.estimatedDocumentCount()
+    const size = numberOr(s['size'], 0)
     return {
       ns,
-      count: numberOr(s['count'], 0),
-      size: numberOr(s['size'], 0),
+      count,
+      size,
       storageSize: numberOr(s['storageSize'], 0),
       freeStorageSize: numberOr(s['freeStorageSize'], 0),
-      avgObjSize: numberOr(s['avgObjSize'], 0),
+      avgObjSize: count > 0 ? size / count : 0,
       totalIndexSize: numberOr(s['totalIndexSize'], 0),
       indexSizes: (s['indexSizes'] as Record<string, number>) ?? {},
       nindexes: numberOr(s['nindexes'], 0),
@@ -76,6 +98,28 @@ export class DatabaseService {
     }
   }
 
+  /** Field schema inferred from a random sample of up to 200 documents; empty for an empty collection. */
+  async collectionSchema(
+    connectionId: string,
+    db: string,
+    coll: string
+  ): Promise<CollectionSchema> {
+    const database = this.connections.getClient(connectionId).db(db)
+    const [info] = await database
+      .listCollections({ name: coll }, { nameOnly: true, authorizedCollections: true })
+      .toArray()
+    const collection = database.collection(coll)
+    const options = { raw: true, maxTimeMS: SCHEMA_SAMPLE_MAX_TIME_MS }
+    // $sample on a view runs the whole view pipeline first; a limited find streams.
+    const cursor =
+      info?.type === 'view'
+        ? collection.find<Uint8Array>({}, { ...options, limit: SCHEMA_SAMPLE_SIZE })
+        : collection.aggregate<Uint8Array>([{ $sample: { size: SCHEMA_SAMPLE_SIZE } }], options)
+    const builder = createSchemaBuilder()
+    for await (const bytes of cursor) builder.add(toCanonical(decodeDocument(bytes)))
+    return builder.build()
+  }
+
   async dropCollection(connectionId: string, db: string, coll: string): Promise<void> {
     const client = this.connections.getClient(connectionId)
     await client.db(db).collection(coll).drop()
@@ -113,14 +157,10 @@ export class DatabaseService {
   ): Promise<void> {
     if (newName === coll) return
     if (!COLLECTION_NAME_RE.test(newName)) {
-      const e = new Error('Collection name must not contain $ or null bytes')
-      e.name = 'ValidationError'
-      throw e
+      throw validationError('Collection name must not contain $ or null bytes')
     }
     if (newName.startsWith('system.')) {
-      const e = new Error('Collection name must not start with "system."')
-      e.name = 'ValidationError'
-      throw e
+      throw validationError('Collection name must not start with "system."')
     }
     const client = this.connections.getClient(connectionId)
     await client.db(db).collection(coll).rename(newName)
@@ -257,7 +297,7 @@ export class DatabaseService {
 
 /**
  * Returns the set of database names the authenticated user has any privilege on,
- * or 'all' when the user holds a cluster-wide / anyResource privilege (or auth
+ * or 'all' when the user holds an any-database / anyResource privilege (or auth
  * is disabled and no privilege list is reported).
  *
  * Why: `listDatabases({ authorizedDatabases: true })` is ignored server-side for
@@ -272,32 +312,29 @@ async function authorizedDatabases(client: MongoClient): Promise<Set<string> | '
       .command({ connectionStatus: 1, showPrivileges: true })) as {
       authInfo?: {
         authenticatedUsers?: Array<{ user: string; db: string }>
-        authenticatedUserPrivileges?: Array<{
-          resource?: {
-            db?: string
-            collection?: string
-            cluster?: boolean
-            anyResource?: boolean
-          }
-        }>
+        authenticatedUserPrivileges?: Privilege[]
       }
     }
     const auth = status.authInfo
     if (!auth || (auth.authenticatedUsers ?? []).length === 0) return 'all'
-    const privs = auth.authenticatedUserPrivileges ?? []
-    const dbs = new Set<string>()
-    for (const p of privs) {
-      const r = p.resource
-      if (!r) continue
-      if (r.anyResource) return 'all'
-      if (typeof r.db === 'string' && r.db.length > 0) dbs.add(r.db)
-    }
-    return dbs
+    return databasesFromPrivileges(auth.authenticatedUserPrivileges ?? [])
   } catch {
     return 'all'
   }
 }
 
+/** Databases the privileges reach, or 'all'; db '' means every database (*AnyDatabase roles). */
+export function databasesFromPrivileges(privs: readonly Privilege[]): Set<string> | 'all' {
+  const dbs = new Set<string>()
+  for (const p of privs) {
+    const r = p.resource
+    if (!r) continue
+    if (r.anyResource || r.db === '') return 'all'
+    if (typeof r.db === 'string') dbs.add(r.db)
+  }
+  return dbs
+}
+
 /**
  * Pull the raw cumulative latency / ops counters out of the
  * `opLatencies.{reads,writes,commands}` block. The renderer derives a
@@ -337,26 +374,18 @@ function basename(path: string): string {
 
 function assertCollectionName(name: string): void {
   if (!COLLECTION_NAME_RE.test(name)) {
-    const e = new Error('Collection name must not contain $ or null bytes')
-    e.name = 'ValidationError'
-    throw e
+    throw validationError('Collection name must not contain $ or null bytes')
   }
   if (name.startsWith('system.')) {
-    const e = new Error('Collection name must not start with "system."')
-    e.name = 'ValidationError'
-    throw e
+    throw validationError('Collection name must not start with "system."')
   }
 }
 
 function assertDatabaseName(name: string): void {
   if (name.length === 0 || name.length > 64) {
-    const e = new Error('Database name must be 1–64 characters')
-    e.name = 'ValidationError'
-    throw e
+    throw validationError('Database name must be 1–64 characters')
   }
   if (/[\s/\\."$*<>:|?\0]/.test(name)) {
-    const e = new Error('Database name contains invalid characters')
-    e.name = 'ValidationError'
-    throw e
+    throw validationError('Database name contains invalid characters')
   }
 }
diff --git a/src/main/services/IndexService.test.ts b/src/main/services/IndexService.test.ts
new file mode 100644
index 0000000..90b50e3
--- /dev/null
+++ b/src/main/services/IndexService.test.ts
@@ -0,0 +1,219 @@
+import { describe, expect, it } from 'vitest'
+import { BSON, Decimal128, ObjectId, type Document } from 'bson'
+import { IndexService } from './IndexService'
+import type { ConnectionService } from './ConnectionService'
+
+type Doc = Record<string, unknown>
+type Stage = Record<string, unknown>
+
+const SINCE = new Date('2026-10-01T08:00:00.000Z')
+
+/** Collection double whose aggregate answers by first stage and honours `$limit` like a server. */
+function fakeCollection(opts: {
+  indexes?: Doc[]
+  indexStats?: () => Promise<Doc[]>
+  collStats?: () => Promise<Doc[]>
+}) {
+  const created: Array<{ keys: Doc; options: Doc }> = []
+  return {
+    created,
+    createIndex: async (keys: Doc, options: Doc) => {
+      created.push({ keys, options })
+      return 'created_1'
+    },
+    listIndexes: () => ({ toArray: async () => opts.indexes ?? [] }),
+    aggregate: (pipeline: Stage[]) => ({
+      toArray: async () => {
+        const first = pipeline[0] ?? {}
+        const source =
+          '$indexStats' in first ? opts.indexStats : '$collStats' in first ? opts.collStats : null
+        if (!source) throw new Error(`unexpected pipeline ${JSON.stringify(pipeline)}`)
+        const docs = await source()
+        const limit = pipeline.find((s) => '$limit' in s)?.['$limit']
+        return typeof limit === 'number' ? docs.slice(0, limit) : docs
+      }
+    })
+  }
+}
+
+function serviceFor(collection: ReturnType<typeof fakeCollection>): IndexService {
+  const connections = {
+    getClient: () => ({ db: () => ({ collection: () => collection }) })
+  }
+  return new IndexService(connections as unknown as ConnectionService)
+}
+
+function shardStats(shard: string, indexSizes: Record<string, number>): Doc {
+  return { ns: 'app.players', shard, storageStats: { indexSizes } }
+}
+
+describe('IndexService.listIndexes', () => {
+  it('returns relaxed EJSON for the fields that carry user values', async () => {
+    const oid = new ObjectId('507f1f77bcf86cd799439011')
+    const service = serviceFor(
+      fakeCollection({
+        indexes: [
+          {
+            v: 2,
+            key: { status: 1 },
+            name: 'status_1',
+            partialFilterExpression: {
+              status: { $in: [oid] },
+              createdAt: { $gt: new Date('2026-01-15T10:30:00.123Z') },
+              price: { $lt: Decimal128.fromString('9.99') }
+            },
+            collation: { locale: 'de', strength: 2 }
+          },
+          {
+            v: 2,
+            key: { _fts: 'text', _ftsx: 1 },
+            name: 'bio_text',
+            weights: { bio: 3 },
+            default_language: 'german'
+          },
+          { v: 2, key: { '$**': 1 }, name: '$**_1', wildcardProjection: { secret: 0 } }
+        ]
+      })
+    )
+
+    const indexes = await service.listIndexes('c1', 'app', 'players')
+
+    expect(indexes).toEqual([
+      {
+        v: 2,
+        key: { status: 1 },
+        name: 'status_1',
+        partialFilterExpression: {
+          status: { $in: [{ $oid: '507f1f77bcf86cd799439011' }] },
+          createdAt: { $gt: { $date: '2026-01-15T10:30:00.123Z' } },
+          price: { $lt: { $numberDecimal: '9.99' } }
+        },
+        collation: { locale: 'de', strength: 2 }
+      },
+      {
+        v: 2,
+        key: { _fts: 'text', _ftsx: 1 },
+        name: 'bio_text',
+        weights: { bio: 3 },
+        default_language: 'german'
+      },
+      { v: 2, key: { '$**': 1 }, name: '$**_1', wildcardProjection: { secret: 0 } }
+    ])
+  })
+
+  it('lists indexes without reading storage stats', async () => {
+    const service = serviceFor(
+      fakeCollection({
+        indexes: [{ v: 2, key: { _id: 1 }, name: '_id_' }],
+        collStats: async () => [shardStats('shard-a', { _id_: 4096 })]
+      })
+    )
+
+    const indexes = await service.listIndexes('c1', 'app', 'players')
+
+    expect(indexes).toEqual([{ v: 2, key: { _id: 1 }, name: '_id_' }])
+  })
+})
+
+describe('IndexService.createIndex', () => {
+  it('sends an Int64 bound beyond 2^53 in a partial filter exactly', async () => {
+    const collection = fakeCollection({})
+
+    await serviceFor(collection).createIndex('c1', 'app', 'players', '{"big":1}', {
+      partialFilterExpression: '{"big":{"$gte":{"$numberLong":"9007199254740993"}}}'
+    })
+
+    const sent = collection.created[0]?.options['partialFilterExpression'] as Document
+    const encoded = BSON.deserialize(BSON.serialize(sent), { promoteLongs: false })
+    expect(String(encoded['big']['$gte'])).toBe('9007199254740993')
+    expect(encoded['big']['$gte']._bsontype).toBe('Long')
+  })
+
+  it('keeps numeric key directions plain numbers', async () => {
+    const collection = fakeCollection({})
+
+    await serviceFor(collection).createIndex('c1', 'app', 'players', '{"a":1,"b":-1}', undefined)
+
+    expect(collection.created[0]?.keys).toEqual({ a: 1, b: -1 })
+  })
+})
+
+describe('IndexService.indexStats', () => {
+  it('reads every shard and merges usage and sizes', async () => {
+    const service = serviceFor(
+      fakeCollection({
+        indexStats: async () => [
+          {
+            name: '_id_',
+            host: 'a1:27018',
+            shard: 'shard-a',
+            accesses: { ops: 4, since: SINCE }
+          },
+          {
+            name: '_id_',
+            host: 'b1:27018',
+            shard: 'shard-b',
+            accesses: { ops: 6, since: SINCE }
+          }
+        ],
+        collStats: async () => [
+          shardStats('shard-a', { _id_: 1000 }),
+          shardStats('shard-b', { _id_: 3000 })
+        ]
+      })
+    )
+
+    const report = await service.indexStats('c1', 'app', 'players')
+
+    expect(report).toEqual({
+      indexes: [
+        {
+          name: '_id_',
+          size: 4000,
+          building: false,
+          usage: [
+            { host: 'a1:27018', shard: 'shard-a', ops: 4, since: '2026-10-01T08:00:00.000Z' },
+            { host: 'b1:27018', shard: 'shard-b', ops: 6, since: '2026-10-01T08:00:00.000Z' }
+          ]
+        }
+      ],
+      usageUnavailable: null,
+      storageUnavailable: null
+    })
+  })
+
+  it('degrades the usage source alone when $indexStats is not authorized', async () => {
+    const service = serviceFor(
+      fakeCollection({
+        indexStats: async () => {
+          throw Object.assign(new Error('not authorized on app to execute command'), { code: 13 })
+        },
+        collStats: async () => [shardStats('shard-a', { _id_: 1000 })]
+      })
+    )
+
+    const report = await service.indexStats('c1', 'app', 'players')
+
+    expect(report).toEqual({
+      indexes: [{ name: '_id_', size: 1000, building: false, usage: [] }],
+      usageUnavailable: {
+        reason: 'unauthorized',
+        message: 'not authorized on app to execute command'
+      },
+      storageUnavailable: null
+    })
+  })
+
+  it('rejects when the connection is not open', async () => {
+    const connections = {
+      getClient: () => {
+        throw Object.assign(new Error('Connection c1 is not open'), { name: 'NotConnectedError' })
+      }
+    }
+    const service = new IndexService(connections as unknown as ConnectionService)
+
+    await expect(service.indexStats('c1', 'app', 'players')).rejects.toMatchObject({
+      name: 'NotConnectedError'
+    })
+  })
+})
diff --git a/src/main/services/IndexService.ts b/src/main/services/IndexService.ts
index 91b4bff..4a996b4 100644
--- a/src/main/services/IndexService.ts
+++ b/src/main/services/IndexService.ts
@@ -1,6 +1,10 @@
 import type { CreateIndexesOptions, IndexDirection, IndexSpecification } from 'mongodb'
 import { EJSON } from 'bson'
-import type { IndexCreateOptions, IndexInfo } from '@shared/types'
+import type { IndexCreateOptions, IndexInfo, IndexStatsReport } from '@shared/types'
+import { isDocument } from '@shared/writeOps'
+import { buildIndexStatsReport } from '../lib/indexStats'
+import { parseRelaxed, toRelaxed } from '../lib/ejson'
+import { validationError } from '../lib/errorMap'
 import type { ConnectionService } from './ConnectionService'
 
 /** Index management on a single collection. */
@@ -10,22 +14,18 @@ export class IndexService {
   async listIndexes(connectionId: string, db: string, coll: string): Promise<IndexInfo[]> {
     const client = this.connections.getClient(connectionId)
     const collection = client.db(db).collection(coll)
+    const raw = await collection.listIndexes().toArray()
+    return raw.map((info) => mapIndex(info as Record<string, unknown>))
+  }
 
-    const [raw, statsCursor] = await Promise.all([
-      collection.listIndexes().toArray(),
-      collection
-        .aggregate([{ $collStats: { storageStats: {} } }, { $limit: 1 }])
-        .toArray()
-        .catch(() => [] as Array<Record<string, unknown>>)
+  /** Per-index size, build state and usage; each source degrades on its own instead of failing. */
+  async indexStats(connectionId: string, db: string, coll: string): Promise<IndexStatsReport> {
+    const collection = this.connections.getClient(connectionId).db(db).collection(coll)
+    const [usage, storage] = await Promise.allSettled([
+      collection.aggregate([{ $indexStats: {} }]).toArray(),
+      collection.aggregate([{ $collStats: { storageStats: {} } }]).toArray()
     ])
-
-    const sizes =
-      ((statsCursor[0]?.['storageStats'] as Record<string, unknown> | undefined)?.['indexSizes'] as
-        Record<string, number> | undefined) ?? {}
-
-    return raw.map((info) =>
-      mapIndex(info as Record<string, unknown>, sizes[info['name'] as string])
-    )
+    return buildIndexStatsReport(usage, storage)
   }
 
   async createIndex(
@@ -38,7 +38,7 @@ export class IndexService {
     const client = this.connections.getClient(connectionId)
     const keys = parseObject(keysJson, 'keys')
     if (Object.keys(keys).length === 0) {
-      throwValidation('At least one key field is required')
+      throw validationError('At least one key field is required')
     }
     assertKeySpec(keys)
 
@@ -52,9 +52,11 @@ export class IndexService {
         driverOptions.expireAfterSeconds = options.expireAfterSeconds
       }
       if (options.partialFilterExpression !== undefined) {
+        // Filter bounds may be Int64 values beyond 2^53, which only a bigint keeps exact.
         driverOptions.partialFilterExpression = parseObject(
           options.partialFilterExpression,
-          'partialFilterExpression'
+          'partialFilterExpression',
+          parseRelaxed
         )
       }
       if (options.collation !== undefined) {
@@ -95,43 +97,49 @@ export class IndexService {
 
   async dropIndex(connectionId: string, db: string, coll: string, name: string): Promise<void> {
     if (name === '_id_') {
-      throwValidation('The default _id_ index cannot be dropped')
+      throw validationError('The default _id_ index cannot be dropped')
     }
     const client = this.connections.getClient(connectionId)
     await client.db(db).collection(coll).dropIndex(name)
   }
 }
 
-function parseObject(input: string, label: string): Record<string, unknown> {
+function parseObject(
+  input: string,
+  label: string,
+  parse: (text: string) => unknown = (text) => EJSON.parse(text, { relaxed: true })
+): Record<string, unknown> {
   let parsed: unknown
   try {
-    parsed = EJSON.parse(input, { relaxed: true })
+    parsed = parse(input)
   } catch (e) {
-    throwValidation(`${label} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`)
+    throw validationError(
+      `${label} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`
+    )
   }
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throwValidation(`${label} must be a JSON object`)
+  if (!isDocument(parsed)) {
+    throw validationError(`${label} must be a JSON object`)
   }
-  return parsed as Record<string, unknown>
+  return parsed
 }
 
 function assertKeySpec(keys: Record<string, unknown>): void {
   for (const [field, direction] of Object.entries(keys)) {
-    if (field.length === 0) throwValidation('Key field name cannot be empty')
+    if (field.length === 0) throw validationError('Key field name cannot be empty')
     if (typeof direction === 'number' ? direction !== 1 && direction !== -1 : false) {
-      throwValidation(`Numeric direction for "${field}" must be 1 or -1`)
+      throw validationError(`Numeric direction for "${field}" must be 1 or -1`)
     }
     if (typeof direction === 'string') {
       if (!['text', '2dsphere', '2d', 'hashed'].includes(direction)) {
-        throwValidation(`Unknown index type "${direction}" for field "${field}"`)
+        throw validationError(`Unknown index type "${direction}" for field "${field}"`)
       }
     } else if (typeof direction !== 'number') {
-      throwValidation(`Direction for "${field}" must be 1, -1, or a string type`)
+      throw validationError(`Direction for "${field}" must be 1, -1, or a string type`)
     }
   }
 }
 
-function mapIndex(raw: Record<string, unknown>, size: number | undefined): IndexInfo {
+function mapIndex(raw: Record<string, unknown>): IndexInfo {
   const out: IndexInfo = {
     name: String(raw['name']),
     key: (raw['key'] as Record<string, IndexDirection>) ?? {}
@@ -143,14 +151,16 @@ function mapIndex(raw: Record<string, unknown>, size: number | undefined): Index
     out.expireAfterSeconds = Number(raw['expireAfterSeconds'])
   }
   if (raw['partialFilterExpression'] !== undefined) {
-    out.partialFilterExpression = raw['partialFilterExpression'] as Record<string, unknown>
+    out.partialFilterExpression = toRelaxed(raw['partialFilterExpression'])
   }
   if (raw['collation'] !== undefined) {
-    out.collation = raw['collation'] as Record<string, unknown>
+    out.collation = toRelaxed(raw['collation'])
   }
   if (raw['hidden'] !== undefined) out.hidden = Boolean(raw['hidden'])
   if (raw['background'] !== undefined) out.background = Boolean(raw['background'])
-  if (raw['weights'] !== undefined) out.weights = raw['weights'] as Record<string, number>
+  if (raw['weights'] !== undefined) {
+    out.weights = toRelaxed(raw['weights']) as Record<string, number>
+  }
   if (raw['default_language'] !== undefined) out.default_language = String(raw['default_language'])
   if (raw['language_override'] !== undefined) {
     out.language_override = String(raw['language_override'])
@@ -163,14 +173,7 @@ function mapIndex(raw: Record<string, unknown>, size: number | undefined): Index
   if (raw['min'] !== undefined) out.min = Number(raw['min'])
   if (raw['max'] !== undefined) out.max = Number(raw['max'])
   if (raw['wildcardProjection'] !== undefined) {
-    out.wildcardProjection = raw['wildcardProjection'] as Record<string, unknown>
+    out.wildcardProjection = toRelaxed(raw['wildcardProjection'])
   }
-  if (size !== undefined) out.size = size
   return out
 }
-
-function throwValidation(message: string): never {
-  const e = new Error(message)
-  e.name = 'ValidationError'
-  throw e
-}
diff --git a/src/main/services/QueryService.test.ts b/src/main/services/QueryService.test.ts
new file mode 100644
index 0000000..6544f51
--- /dev/null
+++ b/src/main/services/QueryService.test.ts
@@ -0,0 +1,1184 @@
+import { describe, expect, it, vi } from 'vitest'
+import { BSON, BSONRegExp, Double, EJSON, Int32, Long, ObjectId, type Document } from 'bson'
+import { MongoServerError } from 'mongodb'
+import { rejectedStageMessage } from '@shared/pipeline'
+import { RESULT_CAP, type WriteOp } from '@shared/types'
+import {
+  bulkWriteError,
+  insertDocumentError,
+  replacementError,
+  updateError,
+  writeOptionsError
+} from '@shared/writeOps'
+import { mapError } from '../lib/errorMap'
+import type { ConnectionService } from './ConnectionService'
+import { QueryService } from './QueryService'
+
+const REF = { connectionId: '7f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f', db: 'app', coll: 'players' }
+const REQUEST_ID = '0b6e4a52-3c1d-4f7e-9a8b-2d5c6e7f8a9b'
+const OID = '507f1f77bcf86cd799439011'
+const BEYOND_2_53 = '9007199254740993'
+
+type ReadOptions = {
+  raw?: boolean
+  promoteValues?: boolean
+  promoteLongs?: boolean
+  bsonRegExp?: boolean
+  signal?: AbortSignal
+}
+
+type ServerReply = { code: number; errmsg: string }
+
+/**
+ * Holds documents as BSON bytes and answers reads like the driver: raw bytes with `raw`, else
+ * decoded with the call's BSON options. A `failure` reply is decoded with those same options into
+ * a MongoServerError, as the driver's connection does. With `hang`, reads settle only when their
+ * signal aborts, rejecting with `abortError` or else the signal's reason.
+ */
+function fakeCollection(
+  docs: Document[],
+  {
+    hang = false,
+    failure,
+    abortError
+  }: { hang?: boolean; failure?: ServerReply; abortError?: Error } = {}
+) {
+  const bytes = docs.map((d) => BSON.serialize(d))
+  const bsonOptions = (options: ReadOptions | undefined) => ({
+    promoteValues: options?.promoteValues,
+    promoteLongs: options?.promoteLongs,
+    bsonRegExp: options?.bsonRegExp,
+    raw: options?.raw
+  })
+  const decoded = (options: ReadOptions | undefined): Document[] =>
+    bytes.map((b) => BSON.deserialize(b, bsonOptions(options)))
+  const results = (options: ReadOptions | undefined): unknown[] =>
+    options?.raw ? bytes : decoded(options)
+  const read = <T>(options: ReadOptions | undefined, value: () => T): Promise<T> => {
+    if (failure) {
+      const reply = BSON.deserialize(BSON.serialize({ ok: 0, ...failure }), bsonOptions(options))
+      return Promise.reject(new MongoServerError(reply))
+    }
+    if (!hang) return Promise.resolve(value())
+    return new Promise((_resolve, reject) => {
+      options?.signal?.addEventListener('abort', () => reject(abortError ?? options.signal?.reason))
+    })
+  }
+
+  const cursor = (options: ReadOptions | undefined) => {
+    const c = {
+      project: vi.fn(() => c),
+      sort: vi.fn(() => c),
+      skip: vi.fn(() => c),
+      limit: vi.fn(() => c),
+      toArray: () => read(options, () => results(options))
+    }
+    return c
+  }
+
+  return {
+    find: vi.fn((_filter: Document, options?: ReadOptions) => cursor(options)),
+    aggregate: vi.fn((_pipeline: Document[], options?: ReadOptions) => ({
+      toArray: () => read(options, () => results(options))
+    })),
+    findOne: vi.fn((_filter: Document, options?: ReadOptions) =>
+      read(options, () => results(options)[0] ?? null)
+    ),
+    countDocuments: vi.fn((_filter: Document, options?: ReadOptions) =>
+      read(options, () => docs.length)
+    ),
+    estimatedDocumentCount: vi.fn(async () => docs.length),
+    distinct: vi.fn((field: string, _filter: Document, options?: ReadOptions) =>
+      read(options, () => decoded(options).map((d) => d[field]))
+    ),
+    replaceOne: vi.fn(async () => ({ matchedCount: 1, modifiedCount: 1 })),
+    deleteOne: vi.fn(async () => ({ deletedCount: 1 }))
+  }
+}
+
+function serviceFor(coll: object): QueryService {
+  const client = { db: () => ({ collection: () => coll }) }
+  return new QueryService({ getClient: () => client } as unknown as ConnectionService)
+}
+
+function manyDocs(n: number): Document[] {
+  return Array.from({ length: n }, (_, i) => ({ i }))
+}
+
+/** A filter value as the driver encodes it, with Longs left unpromoted. */
+function encodedAs(filter: unknown, field: string): string {
+  const encoded = BSON.deserialize(BSON.serialize(filter as Document), { promoteLongs: false })
+  return `${(encoded[field] as { _bsontype?: string })._bsontype}(${String(encoded[field])})`
+}
+
+describe('QueryService.find', () => {
+  it('reads without promoting values, so stored numeric types survive', async () => {
+    const coll = fakeCollection([
+      { _id: new ObjectId(OID), coins: Long.fromNumber(1500), ratio: new Double(2) }
+    ])
+    const { documents } = await serviceFor(coll).find({ ...REF, skip: 0 })
+
+    expect(JSON.parse(documents[0]?.canonical ?? '')).toEqual({
+      _id: { $oid: OID },
+      coins: { $numberLong: '1500' },
+      ratio: { $numberDouble: '2.0' }
+    })
+  })
+
+  it('keeps stored regexes that a JS RegExp cannot represent', async () => {
+    const coll = fakeCollection([
+      { _id: 1, dotAll: new BSONRegExp('dot.all', 's'), pcre: new BSONRegExp('(?i)abc', '') }
+    ])
+    const { documents } = await serviceFor(coll).find({ ...REF, skip: 0 })
+
+    expect(JSON.parse(documents[0]?.canonical ?? '')).toMatchObject({
+      dotAll: { $regularExpression: { pattern: 'dot.all', options: 's' } },
+      pcre: { $regularExpression: { pattern: '(?i)abc', options: '' } }
+    })
+  })
+
+  it('identifies a document by its canonical _id', async () => {
+    const coll = fakeCollection([{ _id: new ObjectId(OID), name: 'a' }])
+    const { documents } = await serviceFor(coll).find({ ...REF, skip: 0 })
+    expect(documents[0]?.id).toBe(`{"$oid":"${OID}"}`)
+  })
+
+  it('gives rows without _id a null id', async () => {
+    const coll = fakeCollection([{ name: 'a' }, { name: 'b' }])
+    const { documents } = await serviceFor(coll).find({
+      ...REF,
+      projection: '{"_id":0,"name":1}',
+      skip: 0
+    })
+    expect(documents.map((d) => d.id)).toEqual([null, null])
+  })
+
+  it('applies projection, sort, skip and limit to the cursor', async () => {
+    const coll = fakeCollection([{ _id: 1 }])
+    await serviceFor(coll).find({
+      ...REF,
+      filter: '{"a":1}',
+      projection: '{"a":1}',
+      sort: '{"b":-1}',
+      skip: 20,
+      limit: 10
+    })
+    const cursor = coll.find.mock.results[0]?.value as ReturnType<typeof coll.find>
+    expect(coll.find.mock.calls[0]?.[0]).toEqual({ a: 1 })
+    expect(cursor.project).toHaveBeenCalledWith({ a: 1 })
+    expect(cursor.sort).toHaveBeenCalledWith({ b: -1 })
+    expect(cursor.skip).toHaveBeenCalledWith(20)
+    expect(cursor.limit).toHaveBeenCalledWith(10)
+  })
+
+  it('reloads a document by an Int64 _id beyond 2^53 without rounding it', async () => {
+    const coll = fakeCollection([])
+    await serviceFor(coll).find({
+      ...REF,
+      filter: `{"_id":{"$numberLong":"${BEYOND_2_53}"}}`,
+      skip: 0,
+      limit: 1
+    })
+    expect(encodedAs(coll.find.mock.calls[0]?.[0], '_id')).toBe(`Long(${BEYOND_2_53})`)
+  })
+})
+
+describe('QueryService.aggregate', () => {
+  it('caps the pipeline server-side with one extra row to detect truncation', async () => {
+    const coll = fakeCollection([])
+    await serviceFor(coll).aggregate({ ...REF, pipeline: '[{"$match":{"a":"x"}}]' })
+    expect(coll.aggregate.mock.calls[0]?.[0]).toEqual([
+      { $match: { a: 'x' } },
+      { $limit: RESULT_CAP + 1 }
+    ])
+  })
+
+  it('keeps the stored numeric and regex types', async () => {
+    const coll = fakeCollection([{ _id: 1, d: new Double(5), re: new BSONRegExp('a b', 'x') }])
+    const res = await serviceFor(coll).aggregate({ ...REF, pipeline: '[]' })
+    expect(JSON.parse(res.documents[0]?.canonical ?? '')).toEqual({
+      _id: { $numberInt: '1' },
+      d: { $numberDouble: '5.0' },
+      re: { $regularExpression: { pattern: 'a b', options: 'x' } }
+    })
+  })
+
+  it('returns RESULT_CAP rows and flags truncation when more came back', async () => {
+    const coll = fakeCollection(manyDocs(RESULT_CAP + 1))
+    const res = await serviceFor(coll).aggregate({ ...REF, pipeline: '[]' })
+    expect(res.documents).toHaveLength(RESULT_CAP)
+    expect(res.truncated).toBe(true)
+  })
+
+  it('does not flag a result of exactly RESULT_CAP rows', async () => {
+    const coll = fakeCollection(manyDocs(RESULT_CAP))
+    const res = await serviceFor(coll).aggregate({ ...REF, pipeline: '[]' })
+    expect(res.documents).toHaveLength(RESULT_CAP)
+    expect(res.truncated).toBe(false)
+  })
+
+  it('gives derived rows without _id a null id', async () => {
+    const coll = fakeCollection([{ total: 3 }])
+    const res = await serviceFor(coll).aggregate({ ...REF, pipeline: '[{"$count":"total"}]' })
+    expect(res.documents[0]?.id).toBeNull()
+  })
+
+  it.each([
+    ['$out', 'target'],
+    ['$merge', 'target'],
+    ['$changeStream', {}]
+  ])('rejects a pipeline with %s before it reaches the server', async (stage, spec) => {
+    const coll = fakeCollection([])
+    const run = serviceFor(coll).aggregate({
+      ...REF,
+      pipeline: JSON.stringify([{ $match: {} }, { [stage]: spec }])
+    })
+    await expect(run).rejects.toMatchObject({
+      name: 'ValidationError',
+      message: rejectedStageMessage(stage)
+    })
+    expect(coll.aggregate).not.toHaveBeenCalled()
+  })
+
+  it('rejects a pipeline that is not an array of stage objects', async () => {
+    const coll = fakeCollection([])
+    const service = serviceFor(coll)
+    await expect(service.aggregate({ ...REF, pipeline: '{"$match":{}}' })).rejects.toMatchObject({
+      name: 'ValidationError'
+    })
+    await expect(service.aggregate({ ...REF, pipeline: '["$match"]' })).rejects.toMatchObject({
+      name: 'ValidationError'
+    })
+  })
+})
+
+describe('QueryService.count', () => {
+  it('estimates an empty filter from collection metadata by default', async () => {
+    const coll = fakeCollection(manyDocs(3))
+    const res = await serviceFor(coll).count({ ...REF })
+    expect(res).toMatchObject({ count: 3, estimated: true })
+    expect(res.tookMs).toBeGreaterThanOrEqual(0)
+    expect(coll.countDocuments).not.toHaveBeenCalled()
+  })
+
+  it('counts exactly when asked, even with an empty filter', async () => {
+    const coll = fakeCollection(manyDocs(3))
+    const res = await serviceFor(coll).count({ ...REF, filter: '{}', exact: true })
+    expect(res).toMatchObject({ count: 3, estimated: false })
+    expect(res.tookMs).toBeGreaterThanOrEqual(0)
+    expect(coll.estimatedDocumentCount).not.toHaveBeenCalled()
+  })
+
+  it('counts a non-empty filter exactly', async () => {
+    const coll = fakeCollection(manyDocs(2))
+    const res = await serviceFor(coll).count({ ...REF, filter: '{"i":{"$gte":0}}' })
+    expect(res).toMatchObject({ count: 2, estimated: false })
+    expect(coll.countDocuments.mock.calls[0]?.[0]).toEqual({ i: { $gte: 0 } })
+  })
+
+  it('counts on an Int64 beyond 2^53 without rounding it', async () => {
+    const coll = fakeCollection([])
+    await serviceFor(coll).count({ ...REF, filter: `{"uid":{"$numberLong":"${BEYOND_2_53}"}}` })
+    expect(encodedAs(coll.countDocuments.mock.calls[0]?.[0], 'uid')).toBe(`Long(${BEYOND_2_53})`)
+  })
+})
+
+describe('QueryService.distinct', () => {
+  it('wraps each value as a { value } row without an id', async () => {
+    const coll = fakeCollection([
+      { tag: 'a' },
+      { tag: Long.fromString(BEYOND_2_53) },
+      { tag: new BSONRegExp('dot.all', 's') }
+    ])
+    const res = await serviceFor(coll).distinct({ ...REF, field: 'tag', filter: '{"x":1}' })
+
+    expect(coll.distinct.mock.calls[0]?.slice(0, 2)).toEqual(['tag', { x: 1 }])
+    expect(res.documents.map((d) => d.id)).toEqual([null, null, null])
+    expect(res.documents.map((d) => JSON.parse(d.canonical))).toEqual([
+      { value: 'a' },
+      { value: { $numberLong: BEYOND_2_53 } },
+      { value: { $regularExpression: { pattern: 'dot.all', options: 's' } } }
+    ])
+    expect(res.truncated).toBe(false)
+  })
+
+  it('keeps an Int64 within 2^53 an Int64', async () => {
+    const coll = fakeCollection([{ n: Long.fromNumber(5) }])
+    const res = await serviceFor(coll).distinct({ ...REF, field: 'n' })
+
+    expect(res.documents.map((d) => JSON.parse(d.canonical))).toEqual([
+      { value: { $numberLong: '5' } }
+    ])
+  })
+
+  it('caps the values at RESULT_CAP and flags truncation', async () => {
+    const coll = fakeCollection(manyDocs(RESULT_CAP + 5))
+    const res = await serviceFor(coll).distinct({ ...REF, field: 'i' })
+    expect(res.documents).toHaveLength(RESULT_CAP)
+    expect(res.truncated).toBe(true)
+  })
+
+  it('filters on an Int64 beyond 2^53 without rounding it', async () => {
+    const coll = fakeCollection([])
+    await serviceFor(coll).distinct({
+      ...REF,
+      field: 'name',
+      filter: `{"uid":{"$numberLong":"${BEYOND_2_53}"}}`
+    })
+    expect(encodedAs(coll.distinct.mock.calls[0]?.[1], 'uid')).toBe(`Long(${BEYOND_2_53})`)
+  })
+})
+
+describe('QueryService server errors', () => {
+  const id = `{"$oid":"${OID}"}`
+
+  it.each([
+    ['find', (s: QueryService) => s.find({ ...REF, skip: 0 })],
+    ['aggregate', (s: QueryService) => s.aggregate({ ...REF, pipeline: '[]' })],
+    ['distinct', (s: QueryService) => s.distinct({ ...REF, field: 'a' })],
+    [
+      'the replace precondition',
+      (s: QueryService) =>
+        s.replaceOne({ ...REF, id, expectedHash: 'x', replacement: `{"_id":${id}}` })
+    ],
+    ['the delete precondition', (s: QueryService) => s.deleteOne({ ...REF, id, expectedHash: 'x' })]
+  ])('%s keeps the server error code a number, as driver retries require', async (_op, run) => {
+    const coll = fakeCollection([], { failure: { code: 189, errmsg: 'Primary stepped down' } })
+
+    const error = await run(serviceFor(coll)).then(
+      () => null,
+      (e: unknown) => e
+    )
+
+    expect(error).toBeInstanceOf(MongoServerError)
+    expect(mapError(error)).toEqual({
+      code: 'driver_error',
+      message: 'Primary stepped down',
+      details: { mongoCode: 189 }
+    })
+  })
+})
+
+describe('QueryService writes', () => {
+  it('checks the replace precondition against a document decoded like the envelope', async () => {
+    const coll = fakeCollection([
+      { _id: new ObjectId(OID), coins: Long.fromNumber(5), re: new BSONRegExp('a/b', 's') }
+    ])
+    const service = serviceFor(coll)
+    const [env] = (await service.find({ ...REF, skip: 0 })).documents
+    if (env?.id == null) throw new Error('expected an envelope with an id')
+
+    const res = await service.replaceOne({
+      ...REF,
+      id: env.id,
+      expectedHash: env.hash,
+      replacement: env.canonical
+    })
+
+    expect(res).toEqual({ matched: 1, modified: 1 })
+  })
+
+  it('checks the delete precondition against a document decoded like the envelope', async () => {
+    const coll = fakeCollection([
+      { _id: new ObjectId(OID), ratio: new Double(1), re: new BSONRegExp('', 'u') }
+    ])
+    const service = serviceFor(coll)
+    const [env] = (await service.find({ ...REF, skip: 0 })).documents
+    if (env?.id == null) throw new Error('expected an envelope with an id')
+
+    const res = await service.deleteOne({ ...REF, id: env.id, expectedHash: env.hash })
+
+    expect(res).toEqual({ deletedCount: 1 })
+  })
+
+  it('refuses a replace when the stored document changed', async () => {
+    const coll = fakeCollection([{ _id: new ObjectId(OID), coins: Long.fromNumber(5) }])
+    const id = `{"$oid":"${OID}"}`
+
+    const run = serviceFor(coll).replaceOne({
+      ...REF,
+      id,
+      expectedHash: 'stale',
+      replacement: `{"_id":${id}}`
+    })
+
+    await expect(run).rejects.toMatchObject({ name: 'DocumentConflictError' })
+    expect(coll.replaceOne).not.toHaveBeenCalled()
+  })
+})
+
+describe('QueryService.cancel', () => {
+  it('aborts a running find with a CancelledError', async () => {
+    const service = serviceFor(fakeCollection([{ _id: 1 }], { hang: true }))
+    const run = service.find({ ...REF, skip: 0, requestId: REQUEST_ID })
+    service.cancel(REQUEST_ID)
+    await expect(run).rejects.toMatchObject({ name: 'CancelledError' })
+  })
+
+  it('aborts a running aggregation', async () => {
+    const service = serviceFor(fakeCollection([], { hang: true }))
+    const run = service.aggregate({ ...REF, pipeline: '[]', requestId: REQUEST_ID })
+    service.cancel(REQUEST_ID)
+    await expect(run).rejects.toMatchObject({ name: 'CancelledError' })
+  })
+
+  it('aborts a running exact count', async () => {
+    const service = serviceFor(fakeCollection([], { hang: true }))
+    const run = service.count({ ...REF, exact: true, requestId: REQUEST_ID })
+    service.cancel(REQUEST_ID)
+    await expect(run).rejects.toMatchObject({ name: 'CancelledError' })
+  })
+
+  // An abort during getMore kills the cursor, so the in-flight getMore fails with the server's interrupt.
+  it.each([
+    ['find', 237, (s: QueryService) => s.find({ ...REF, skip: 0, requestId: REQUEST_ID })],
+    [
+      'aggregation',
+      11601,
+      (s: QueryService) => s.aggregate({ ...REF, pipeline: '[]', requestId: REQUEST_ID })
+    ]
+  ])('reports a %s cancelled during getMore as cancelled', async (_op, code, start) => {
+    const interrupted = new MongoServerError({
+      errmsg: 'Executor error during getMore :: caused by :: operation was interrupted',
+      code
+    })
+    const service = serviceFor(fakeCollection([], { hang: true, abortError: interrupted }))
+    const run = start(service)
+    service.cancel(REQUEST_ID)
+    await expect(run).rejects.toMatchObject({ name: 'CancelledError' })
+  })
+
+  it('passes on a server error of a run that was not cancelled', async () => {
+    const coll = fakeCollection([], { failure: { code: 2, errmsg: 'bad query' } })
+    const run = serviceFor(coll).find({ ...REF, skip: 0, requestId: REQUEST_ID })
+    await expect(run).rejects.toBeInstanceOf(MongoServerError)
+  })
+
+  it('aborts only the run with that id', async () => {
+    const otherId = '9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d'
+    const coll = fakeCollection([], { hang: true })
+    const service = serviceFor(coll)
+    void service.find({ ...REF, skip: 0, requestId: REQUEST_ID }).catch(() => undefined)
+    void service.find({ ...REF, skip: 0, requestId: otherId }).catch(() => undefined)
+
+    service.cancel(REQUEST_ID)
+
+    const signals = coll.find.mock.calls.map((call) => call[1]?.signal)
+    expect(signals.map((s) => s?.aborted)).toEqual([true, false])
+    service.cancel(otherId)
+  })
+
+  it('forgets a run once it settled', async () => {
+    const coll = fakeCollection([{ _id: 1 }])
+    const service = serviceFor(coll)
+    await service.find({ ...REF, skip: 0, requestId: REQUEST_ID })
+
+    service.cancel(REQUEST_ID)
+
+    expect(coll.find.mock.calls[0]?.[1]?.signal?.aborted).toBe(false)
+  })
+
+  it('ignores unknown ids', () => {
+    const service = serviceFor(fakeCollection([]))
+    expect(() => service.cancel(REQUEST_ID)).not.toThrow()
+  })
+})
+
+type WriteCallOptions = ReadOptions &
+  Document & { includeResultMetadata?: boolean; promoteLongs?: boolean }
+
+type ModifyReply = { value: Document | null; lastErrorObject: Document }
+
+type BulkIds = { insertedIds: Record<number, unknown>; upsertedIds: Record<number, unknown> }
+
+/**
+ * Takes writes like the driver and answers with fixed server results. A findOneAnd* reply is built
+ * as BSON and decoded with the call's BSON options; a `failure` reply is decoded the same way into
+ * a MongoServerError, as the driver's connection does.
+ */
+function fakeWriteCollection({
+  modify = { value: null, lastErrorObject: { n: 0 } },
+  upsertedId = null,
+  bulkIds = { insertedIds: { 0: new ObjectId(OID), 3: 7 }, upsertedIds: { 1: Long.fromNumber(9) } },
+  failure
+}: {
+  modify?: ModifyReply
+  upsertedId?: unknown
+  bulkIds?: BulkIds
+  failure?: ServerReply & Document
+} = {}) {
+  const decode = (reply: Document, options: WriteCallOptions | undefined): Document =>
+    BSON.deserialize(BSON.serialize(reply), {
+      promoteValues: options?.promoteValues,
+      promoteLongs: options?.promoteLongs,
+      bsonRegExp: options?.bsonRegExp,
+      raw: options?.raw
+    })
+  const findAndModify = (options: WriteCallOptions | undefined): Promise<unknown> => {
+    if (failure) return Promise.reject(new MongoServerError(decode({ ok: 0, ...failure }, options)))
+    const reply = decode({ ...modify, ok: 1 }, options)
+    return Promise.resolve(options?.includeResultMetadata ? reply : (reply['value'] ?? null))
+  }
+  // The server reports upserted ids; the driver takes inserted ids from the documents it was given.
+  const updated = async (options: WriteCallOptions | undefined) => {
+    const reply = decode(
+      upsertedId === null
+        ? { n: 2, nModified: 1 }
+        : { n: 1, nModified: 0, upserted: [{ index: 0, _id: upsertedId }] },
+      options
+    )
+    const upserts = (reply['upserted'] as Document[] | undefined) ?? []
+    return {
+      acknowledged: true,
+      matchedCount: upserts.length > 0 ? 0 : reply['n'],
+      modifiedCount: reply['nModified'],
+      upsertedCount: upserts.length,
+      upsertedId: upserts[0]?.['_id'] ?? null
+    }
+  }
+  const toArray = vi.fn(async () => [])
+
+  return {
+    insertOne: vi.fn(async (document: Document, _options?: WriteCallOptions) => ({
+      acknowledged: true,
+      insertedId: document['_id']
+    })),
+    insertMany: vi.fn(async (documents: Document[], _options?: WriteCallOptions) => ({
+      acknowledged: true,
+      insertedCount: documents.length,
+      insertedIds: Object.fromEntries(documents.map((d, i) => [i, d['_id']]))
+    })),
+    updateOne: vi.fn((_filter: Document, _update: unknown, options?: WriteCallOptions) =>
+      updated(options)
+    ),
+    updateMany: vi.fn((_filter: Document, _update: unknown, options?: WriteCallOptions) =>
+      updated(options)
+    ),
+    replaceOne: vi.fn((_filter: Document, _replacement: Document, options?: WriteCallOptions) =>
+      updated(options)
+    ),
+    deleteOne: vi.fn(async (_filter: Document, _options?: WriteCallOptions) => ({
+      acknowledged: true,
+      deletedCount: 1
+    })),
+    deleteMany: vi.fn(async (_filter: Document, _options?: WriteCallOptions) => ({
+      acknowledged: true,
+      deletedCount: 3
+    })),
+    findOneAndUpdate: vi.fn((_filter: Document, _update: unknown, options?: WriteCallOptions) =>
+      findAndModify(options)
+    ),
+    findOneAndReplace: vi.fn(
+      (_filter: Document, _replacement: Document, options?: WriteCallOptions) =>
+        findAndModify(options)
+    ),
+    findOneAndDelete: vi.fn((_filter: Document, options?: WriteCallOptions) =>
+      findAndModify(options)
+    ),
+    bulkWrite: vi.fn(async (_operations: Document[], options?: WriteCallOptions) => ({
+      insertedCount: 2,
+      matchedCount: 3,
+      modifiedCount: 2,
+      deletedCount: 4,
+      upsertedCount: 1,
+      insertedIds: bulkIds.insertedIds,
+      upsertedIds: decode({ ids: bulkIds.upsertedIds }, options)['ids'] as Record<number, unknown>
+    })),
+    aggregate: vi.fn((_pipeline: Document[], _options?: WriteCallOptions) => ({ toArray })),
+    toArray
+  }
+}
+
+const canonical = (value: unknown): string => EJSON.stringify(value, { relaxed: false })
+
+/** A value as the server receives it, in canonical EJSON object form. */
+function sentAs(value: unknown): unknown {
+  const { v } = BSON.deserialize(BSON.serialize({ v: value }), {
+    promoteValues: false,
+    bsonRegExp: true
+  })
+  return JSON.parse(canonical(v))
+}
+
+const writeOf = (op: WriteOp) => ({ ...REF, op })
+
+const TYPED = {
+  d: new Double(5),
+  l: Long.fromString(BEYOND_2_53),
+  i: new Int32(7),
+  re: new BSONRegExp('a/b', 's')
+}
+const TYPED_SENT = {
+  d: { $numberDouble: '5.0' },
+  l: { $numberLong: BEYOND_2_53 },
+  i: { $numberInt: '7' },
+  re: { $regularExpression: { pattern: 'a/b', options: 's' } }
+}
+
+describe('QueryService.write — inserts', () => {
+  it('sends the document with its exact BSON types and reports its id', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'insertOne', document: canonical({ _id: new ObjectId(OID), ...TYPED }) })
+    )
+
+    expect(sentAs(coll.insertOne.mock.calls[0]?.[0])).toEqual({
+      _id: { $oid: OID },
+      ...TYPED_SENT
+    })
+    expect(res).toMatchObject({
+      counts: { inserted: 1 },
+      ids: [`{"$oid":"${OID}"}`],
+      idsTruncated: false
+    })
+    expect(res.tookMs).toBeGreaterThanOrEqual(0)
+    expect(res).not.toHaveProperty('document')
+  })
+
+  it('passes the insert options to the driver', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'insertOne',
+        document: '{"_id":1}',
+        options: '{"bypassDocumentValidation":true}'
+      })
+    )
+    expect(coll.insertOne.mock.calls[0]?.[1]).toEqual({ bypassDocumentValidation: true })
+  })
+
+  it('reports insertMany ids in document order with their exact types', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({
+        method: 'insertMany',
+        documents: [canonical({ _id: new Double(1) }), canonical({ _id: Long.fromNumber(2) })],
+        options: '{"ordered":false}'
+      })
+    )
+
+    expect(coll.insertMany.mock.calls[0]?.[1]).toEqual({ ordered: false })
+    expect(res).toMatchObject({
+      counts: { inserted: 2 },
+      ids: ['{"$numberDouble":"1.0"}', '{"$numberLong":"2"}'],
+      idsTruncated: false
+    })
+  })
+
+  it('caps the reported insertMany ids at RESULT_CAP', async () => {
+    const coll = fakeWriteCollection()
+    const documents = Array.from({ length: RESULT_CAP + 1 }, (_, i) => `{"_id":${i}}`)
+    const res = await serviceFor(coll).write(writeOf({ method: 'insertMany', documents }))
+
+    expect(res.counts).toEqual({ inserted: RESULT_CAP + 1 })
+    expect(res.ids).toHaveLength(RESULT_CAP)
+    expect(res.ids[0]).toBe('{"$numberInt":"0"}')
+    expect(res.idsTruncated).toBe(true)
+  })
+
+  it('does not flag exactly RESULT_CAP ids as truncated', async () => {
+    const coll = fakeWriteCollection()
+    const documents = Array.from({ length: RESULT_CAP }, (_, i) => `{"_id":${i}}`)
+    const res = await serviceFor(coll).write(writeOf({ method: 'insertMany', documents }))
+    expect(res.ids).toHaveLength(RESULT_CAP)
+    expect(res.idsTruncated).toBe(false)
+  })
+})
+
+describe('QueryService.write — updates and deletes', () => {
+  it('sends the filter, the update and the options of updateOne with exact types', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'updateOne',
+        filter: `{"uid":{"$numberLong":"${BEYOND_2_53}"}}`,
+        update: canonical({ $set: TYPED }),
+        options: canonical({ upsert: true, arrayFilters: [{ 'e.k': new Int32(1) }], hint: 'uid_1' })
+      })
+    )
+
+    const [filter, update, options] = coll.updateOne.mock.calls[0] ?? []
+    expect(encodedAs(filter, 'uid')).toBe(`Long(${BEYOND_2_53})`)
+    expect(sentAs(update)).toEqual({ $set: TYPED_SENT })
+    expect(sentAs(options)).toMatchObject({
+      upsert: true,
+      arrayFilters: [{ 'e.k': { $numberInt: '1' } }],
+      hint: 'uid_1'
+    })
+  })
+
+  it.each(['updateOne', 'updateMany', 'replaceOne'] as const)(
+    '%s reports an upserted Long id exactly, decoding the reply without promoting Longs',
+    async (method) => {
+      const coll = fakeWriteCollection({ upsertedId: Long.fromNumber(77) })
+      const filter = '{"_id":{"$numberLong":"77"}}'
+      const op: WriteOp =
+        method === 'replaceOne'
+          ? { method, filter, replacement: '{"a":true}', options: '{"upsert":true}' }
+          : { method, filter, update: '{"$set":{"a":true}}', options: '{"upsert":true}' }
+      const res = await serviceFor(coll).write(writeOf(op))
+
+      expect(coll[method].mock.calls[0]?.[2]).toMatchObject({
+        upsert: true,
+        promoteLongs: false,
+        bsonRegExp: true
+      })
+      expect(coll[method].mock.calls[0]?.[2]).not.toHaveProperty('promoteValues')
+      expect(res).toMatchObject({ counts: { upserted: 1 }, ids: ['{"$numberLong":"77"}'] })
+    }
+  )
+
+  // An upsert copies the filter's equality fields into the new document.
+  it('sends the filter with its exact types', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'updateOne',
+        filter: canonical({ k: new Double(5), i: new Int32(1) }),
+        update: '{"$set":{"a":true}}',
+        options: '{"upsert":true}'
+      })
+    )
+    expect(sentAs(coll.updateOne.mock.calls[0]?.[0])).toEqual({
+      k: { $numberDouble: '5.0' },
+      i: { $numberInt: '1' }
+    })
+  })
+
+  it('reports matched, modified and upserted, without ids when nothing was upserted', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'updateMany', filter: '{}', update: '{"$inc":{"n":{"$numberInt":"1"}}}' })
+    )
+    expect(res).toMatchObject({
+      counts: { matched: 2, modified: 1, upserted: 0 },
+      ids: [],
+      idsTruncated: false
+    })
+  })
+
+  it('reports the upserted id', async () => {
+    const coll = fakeWriteCollection({ upsertedId: new ObjectId(OID) })
+    const res = await serviceFor(coll).write(
+      writeOf({
+        method: 'updateOne',
+        filter: '{"a":"x"}',
+        update: '{"$set":{"b":true}}',
+        options: '{"upsert":true}'
+      })
+    )
+    expect(res).toMatchObject({
+      counts: { matched: 0, modified: 0, upserted: 1 },
+      ids: [`{"$oid":"${OID}"}`]
+    })
+  })
+
+  it('passes an update pipeline through as an array', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'updateMany',
+        filter: '{}',
+        update: canonical([{ $set: { d: new Double(2) } }, { $unset: 'tmp' }])
+      })
+    )
+    expect(sentAs(coll.updateMany.mock.calls[0]?.[1])).toEqual([
+      { $set: { d: { $numberDouble: '2.0' } } },
+      { $unset: 'tmp' }
+    ])
+  })
+
+  it('sends a replacement with exact types and reports the update counters', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'replaceOne', filter: '{"_id":1}', replacement: canonical(TYPED) })
+    )
+    expect(sentAs(coll.replaceOne.mock.calls[0]?.[1])).toEqual(TYPED_SENT)
+    expect(res.counts).toEqual({ matched: 2, modified: 1, upserted: 0 })
+  })
+
+  it.each([
+    ['deleteOne', 1],
+    ['deleteMany', 3]
+  ] as const)('%s reports the deleted count', async (method, deleted) => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method, filter: '{"a":1}', options: '{"hint":"a_1"}' })
+    )
+
+    expect(sentAs(coll[method].mock.calls[0]?.slice(0, 2))).toEqual([
+      { a: { $numberInt: '1' } },
+      { hint: 'a_1' }
+    ])
+    expect(res).toMatchObject({ counts: { deleted }, ids: [], idsTruncated: false })
+    expect(res).not.toHaveProperty('document')
+  })
+})
+
+describe('QueryService.write — findOneAnd*', () => {
+  const stored = {
+    _id: new ObjectId(OID),
+    l: Long.fromNumber(5),
+    big: Long.fromString(BEYOND_2_53),
+    re: new BSONRegExp('dot.all', 's'),
+    half: new Double(2.5),
+    d: new Double(5)
+  }
+
+  it('reads the document with normal decoding, so error replies stay plain objects', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({ method: 'findOneAndUpdate', filter: '{}', update: '{"$set":{"seen":true}}' })
+    )
+
+    const options = coll.findOneAndUpdate.mock.calls[0]?.[2]
+    expect(options).toMatchObject({ promoteLongs: false, bsonRegExp: true })
+    expect(options).not.toHaveProperty('raw')
+    expect(options).not.toHaveProperty('promoteValues')
+  })
+
+  it('keeps Longs and regexes exact; an integral Double reads back as an integer', async () => {
+    const coll = fakeWriteCollection({
+      modify: { value: stored, lastErrorObject: { n: 1, updatedExisting: true } }
+    })
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'findOneAndUpdate', filter: '{}', update: '{"$set":{"seen":true}}' })
+    )
+
+    expect(res.document?.id).toBe(`{"$oid":"${OID}"}`)
+    expect(JSON.parse(res.document?.canonical ?? '')).toEqual({
+      _id: { $oid: OID },
+      l: { $numberLong: '5' },
+      big: { $numberLong: BEYOND_2_53 },
+      re: { $regularExpression: { pattern: 'dot.all', options: 's' } },
+      half: { $numberDouble: '2.5' },
+      d: { $numberInt: '5' }
+    })
+    expect(res).toMatchObject({ counts: { matched: 1, upserted: 0 }, ids: [] })
+  })
+
+  it('returns null when nothing matched', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'findOneAndDelete', filter: '{"a":1}' })
+    )
+    expect(res).toMatchObject({ document: null, counts: { deleted: 0 }, ids: [] })
+  })
+
+  it('reports a findOneAndDelete that removed a document', async () => {
+    const coll = fakeWriteCollection({ modify: { value: stored, lastErrorObject: { n: 1 } } })
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'findOneAndDelete', filter: '{}', options: '{"sort":{"d":-1}}' })
+    )
+    expect(res.counts).toEqual({ deleted: 1 })
+    expect(JSON.parse(res.document?.canonical ?? '')).toMatchObject({
+      big: { $numberLong: BEYOND_2_53 }
+    })
+  })
+
+  it('reports an upsert that returned no document, with the exact upserted id', async () => {
+    const coll = fakeWriteCollection({
+      modify: {
+        value: null,
+        lastErrorObject: { n: 1, updatedExisting: false, upserted: Long.fromNumber(42) }
+      }
+    })
+    const res = await serviceFor(coll).write(
+      writeOf({
+        method: 'findOneAndReplace',
+        filter: '{"_id":{"$numberLong":"42"}}',
+        replacement: canonical(TYPED),
+        options: '{"upsert":true}'
+      })
+    )
+
+    expect(sentAs(coll.findOneAndReplace.mock.calls[0]?.[1])).toEqual(TYPED_SENT)
+    expect(res).toMatchObject({
+      document: null,
+      counts: { matched: 0, upserted: 1 },
+      ids: ['{"$numberLong":"42"}']
+    })
+  })
+
+  it.each([
+    [true, 'after'],
+    [false, 'before']
+  ])('maps returnNewDocument %s to returnDocument %s', async (returnNewDocument, expected) => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'findOneAndUpdate',
+        filter: '{}',
+        update: '{"$set":{"a":true}}',
+        options: JSON.stringify({ returnNewDocument, upsert: true })
+      })
+    )
+
+    const options = coll.findOneAndUpdate.mock.calls[0]?.[2]
+    expect(options).toMatchObject({ returnDocument: expected, upsert: true })
+    expect(options).not.toHaveProperty('returnNewDocument')
+  })
+
+  it('passes returnDocument and projection through', async () => {
+    const coll = fakeWriteCollection()
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'findOneAndReplace',
+        filter: '{}',
+        replacement: '{"a":true}',
+        options: '{"returnDocument":"after","projection":{"a":{"$numberInt":"1"}}}'
+      })
+    )
+    const options = coll.findOneAndReplace.mock.calls[0]?.[2]
+    expect(options).toMatchObject({ returnDocument: 'after' })
+    expect(sentAs(options?.['projection'])).toEqual({ a: { $numberInt: '1' } })
+  })
+
+  it('keeps the server error code a number, as driver retries require', async () => {
+    const coll = fakeWriteCollection({ failure: { code: 189, errmsg: 'Primary stepped down' } })
+    const error = await serviceFor(coll)
+      .write(writeOf({ method: 'findOneAndDelete', filter: '{}' }))
+      .then(
+        () => null,
+        (e: unknown) => e
+      )
+
+    expect(error).toBeInstanceOf(MongoServerError)
+    expect(mapError(error)).toEqual({
+      code: 'driver_error',
+      message: 'Primary stepped down',
+      details: { mongoCode: 189 }
+    })
+  })
+
+  it("keeps a state-change error's topologyVersion an object, as SDAM's stale check requires", async () => {
+    const coll = fakeWriteCollection({
+      failure: {
+        code: 10107,
+        errmsg: 'not primary',
+        topologyVersion: { processId: new ObjectId(OID), counter: Long.fromNumber(6) }
+      }
+    })
+    const error = (await serviceFor(coll)
+      .write(writeOf({ method: 'findOneAndUpdate', filter: '{}', update: '{"$set":{"a":true}}' }))
+      .then(
+        () => null,
+        (e: unknown) => e
+      )) as MongoServerError
+
+    expect(error.code).toBe(10107)
+    expect(error['topologyVersion']).toEqual({
+      processId: new ObjectId(OID),
+      counter: Long.fromNumber(6)
+    })
+  })
+})
+
+describe('QueryService.write — bulkWrite', () => {
+  it('sends the operations with exact types and the options', async () => {
+    const coll = fakeWriteCollection()
+    const operations = [
+      { insertOne: { document: TYPED } },
+      {
+        updateOne: {
+          filter: { l: Long.fromString(BEYOND_2_53) },
+          update: { $set: { d: new Double(1) } },
+          upsert: true
+        }
+      },
+      { deleteMany: { filter: { i: new Int32(7) } } }
+    ]
+    await serviceFor(coll).write(
+      writeOf({
+        method: 'bulkWrite',
+        operations: canonical(operations),
+        options: '{"ordered":false}'
+      })
+    )
+
+    expect(sentAs(coll.bulkWrite.mock.calls[0]?.[0])).toEqual([
+      { insertOne: { document: TYPED_SENT } },
+      {
+        updateOne: {
+          filter: { l: { $numberLong: BEYOND_2_53 } },
+          update: { $set: { d: { $numberDouble: '1.0' } } },
+          upsert: true
+        }
+      },
+      { deleteMany: { filter: { i: { $numberInt: '7' } } } }
+    ])
+    expect(coll.bulkWrite.mock.calls[0]?.[1]).toEqual({
+      ordered: false,
+      promoteLongs: false,
+      bsonRegExp: true
+    })
+  })
+
+  it('reports every counter, then the inserted ids followed by the upserted ids', async () => {
+    const coll = fakeWriteCollection()
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'bulkWrite', operations: '[{"deleteMany":{"filter":{}}}]' })
+    )
+    expect(res).toMatchObject({
+      counts: { inserted: 2, matched: 3, modified: 2, deleted: 4, upserted: 1 },
+      ids: [`{"$oid":"${OID}"}`, '{"$numberInt":"7"}', '{"$numberLong":"9"}'],
+      idsTruncated: false
+    })
+  })
+
+  // An unordered bulkWrite indexes each map by position among operations of its own kind.
+  it('keeps inserted and upserted ids whose map keys coincide', async () => {
+    const coll = fakeWriteCollection({
+      bulkIds: { insertedIds: { 0: 'y1', 1: 'y2' }, upsertedIds: { 0: 'x1', 1: 'x2' } }
+    })
+    const res = await serviceFor(coll).write(
+      writeOf({
+        method: 'bulkWrite',
+        operations: '[{"deleteMany":{"filter":{}}}]',
+        options: '{"ordered":false}'
+      })
+    )
+    expect(res.ids).toEqual(['"y1"', '"y2"', '"x1"', '"x2"'])
+  })
+
+  it('caps the reported bulkWrite ids at RESULT_CAP', async () => {
+    const inserted = Object.fromEntries(Array.from({ length: RESULT_CAP }, (_, i) => [i, i]))
+    const coll = fakeWriteCollection({
+      bulkIds: { insertedIds: inserted, upsertedIds: { 0: 'u' } }
+    })
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'bulkWrite', operations: '[{"deleteMany":{"filter":{}}}]' })
+    )
+    expect(res.ids).toHaveLength(RESULT_CAP)
+    expect(res.ids).not.toContain('"u"')
+    expect(res.idsTruncated).toBe(true)
+  })
+})
+
+describe('QueryService.write — aggregation', () => {
+  it('runs the pipeline as given, without the read cap, and drains its cursor', async () => {
+    const coll = fakeWriteCollection()
+    const pipeline = [{ $set: { d: new Double(3) } }, { $merge: { into: 'copy' } }]
+    const res = await serviceFor(coll).write(
+      writeOf({ method: 'aggregate', pipeline: canonical(pipeline) })
+    )
+
+    expect(sentAs(coll.aggregate.mock.calls[0]?.[0])).toEqual([
+      { $set: { d: { $numberDouble: '3.0' } } },
+      { $merge: { into: 'copy' } }
+    ])
+    expect(coll.toArray).toHaveBeenCalledOnce()
+    expect(res).toMatchObject({ counts: {}, ids: [], idsTruncated: false })
+    expect(res).not.toHaveProperty('document')
+  })
+})
+
+describe('QueryService.write — validation', () => {
+  const methods = [
+    'insertOne',
+    'insertMany',
+    'updateOne',
+    'updateMany',
+    'replaceOne',
+    'deleteOne',
+    'deleteMany',
+    'findOneAndUpdate',
+    'findOneAndReplace',
+    'findOneAndDelete',
+    'bulkWrite',
+    'aggregate'
+  ] as const
+
+  async function rejection(op: WriteOp): Promise<unknown> {
+    const coll = fakeWriteCollection()
+    const error = await serviceFor(coll)
+      .write(writeOf(op))
+      .then(
+        () => null,
+        (e: unknown) => e
+      )
+    for (const method of methods) expect(coll[method]).not.toHaveBeenCalled()
+    return error
+  }
+
+  it.each<[string, WriteOp, string | null]>([
+    [
+      'a document that is not an object',
+      { method: 'insertOne', document: '[{"a":1}]' },
+      insertDocumentError([])
+    ],
+    [
+      'one insertMany document that is not an object',
+      { method: 'insertMany', documents: ['{"a":1}', '"x"'] },
+      insertDocumentError('x')
+    ],
+    [
+      'an update without operators',
+      { method: 'updateOne', filter: '{}', update: '{"a":1}' },
+      updateError({ a: 1 })
+    ],
+    [
+      'an update pipeline with a read stage',
+      { method: 'findOneAndUpdate', filter: '{}', update: '[{"$match":{}}]' },
+      updateError([{ $match: {} }])
+    ],
+    [
+      'a replacement with operators',
+      { method: 'findOneAndReplace', filter: '{}', replacement: '{"$set":{"a":1}}' },
+      replacementError({ $set: { a: 1 } })
+    ],
+    [
+      'a filter that is not an object',
+      { method: 'deleteOne', filter: '[{"a":1}]' },
+      'deleteOne() filter must be an object'
+    ],
+    [
+      'an unknown option',
+      { method: 'deleteMany', filter: '{}', options: '{"upsert":true}' },
+      writeOptionsError('deleteMany', { upsert: true })
+    ],
+    [
+      'options that are not an object',
+      { method: 'updateMany', filter: '{}', update: '{"$set":{}}', options: '[]' },
+      writeOptionsError('updateMany', [])
+    ],
+    [
+      'returnDocument together with returnNewDocument',
+      {
+        method: 'findOneAndUpdate',
+        filter: '{}',
+        update: '{"$set":{}}',
+        options: '{"returnDocument":"after","returnNewDocument":true}'
+      },
+      writeOptionsError('findOneAndUpdate', { returnDocument: 'after', returnNewDocument: true })
+    ],
+    [
+      'an invalid bulk operation',
+      { method: 'bulkWrite', operations: '[{"insertOne":{}}]' },
+      bulkWriteError([{ insertOne: {} }])
+    ],
+    [
+      'a pipeline that does not end in a write stage',
+      { method: 'aggregate', pipeline: '[{"$match":{}}]' },
+      'A write pipeline must end with $out or $merge'
+    ],
+    [
+      'a write stage before the last stage',
+      { method: 'aggregate', pipeline: '[{"$out":"a"},{"$merge":{"into":"b"}}]' },
+      'Stage 1: $out must be the last stage'
+    ],
+    [
+      'a change stream before the write stage',
+      { method: 'aggregate', pipeline: '[{"$changeStream":{}},{"$out":"a"}]' },
+      `Stage 1: ${rejectedStageMessage('$changeStream')}`
+    ],
+    [
+      'a pipeline that is not an array',
+      { method: 'aggregate', pipeline: '{"$out":"a"}' },
+      'Pipeline must be an array of stage objects'
+    ]
+  ])('rejects %s before it reaches the server', async (_case, op, message) => {
+    expect(message).not.toBeNull()
+    expect(await rejection(op)).toMatchObject({ name: 'ValidationError', message })
+  })
+})
diff --git a/src/main/services/QueryService.ts b/src/main/services/QueryService.ts
index 31b27b6..fa45956 100644
--- a/src/main/services/QueryService.ts
+++ b/src/main/services/QueryService.ts
@@ -1,26 +1,69 @@
-import type { Document, Filter, Sort } from 'mongodb'
-import { EJSON } from 'bson'
 import type {
-  AggregateRequest,
-  AggregateResponse,
-  DeleteManyRequest,
-  DeleteManyResponse,
-  DeleteOneRequest,
-  DeleteOneResponse,
-  DocumentEnvelope,
-  FindRequest,
-  FindResponse,
-  InsertManyRequest,
-  InsertManyResponse,
-  InsertOneRequest,
-  InsertOneResponse,
-  ReplaceOneRequest,
-  ReplaceOneResponse
+  AnyBulkWriteOperation,
+  Collection,
+  Document,
+  Filter,
+  ModifyResult,
+  Sort,
+  UpdateResult
+} from 'mongodb'
+import { EJSON } from 'bson'
+import {
+  finalWriteStage,
+  findRejectedStage,
+  rejectedStageMessage,
+  writePipelineError
+} from '@shared/pipeline'
+import {
+  bulkWriteError,
+  filterError,
+  insertDocumentError,
+  isDocument,
+  replacementError,
+  updateError,
+  writeOptionsError
+} from '@shared/writeOps'
+import {
+  RESULT_CAP,
+  type AggregateRequest,
+  type AggregateResponse,
+  type CountRequest,
+  type CountResponse,
+  type DeleteManyRequest,
+  type DeleteManyResponse,
+  type DeleteOneRequest,
+  type DeleteOneResponse,
+  type DistinctRequest,
+  type DistinctResponse,
+  type DocumentEnvelope,
+  type FindRequest,
+  type FindResponse,
+  type InsertManyRequest,
+  type InsertManyResponse,
+  type InsertOneRequest,
+  type InsertOneResponse,
+  type ReplaceOneRequest,
+  type ReplaceOneResponse,
+  type WriteMethod,
+  type WriteOp,
+  type WriteRequest,
+  type WriteResponse
 } from '@shared/types'
 import type { ConnectionService } from './ConnectionService'
-import { canonicalHash, parseFilter, toCanonicalString, toRelaxed } from '../lib/ejson'
+import {
+  REPLY_DECODE_OPTIONS,
+  canonicalHash,
+  decodeDocument,
+  hashCanonicalString,
+  parseFilter,
+  toCanonicalString,
+  toRelaxed
+} from '../lib/ejson'
+import { cancelledError, validationError } from '../lib/errorMap'
 
 export class QueryService {
+  private readonly running = new Map<string, AbortController>()
+
   constructor(private readonly connections: ConnectionService) {}
 
   async find(req: FindRequest): Promise<FindResponse> {
@@ -32,16 +75,17 @@ export class QueryService {
     const sort = parseFilter(req.sort) as Sort
 
     const startedAt = Date.now()
-    let cursor = coll.find(filter)
-    if (Object.keys(projection).length > 0) cursor = cursor.project(projection)
-    if (Object.keys(sort).length > 0) cursor = cursor.sort(sort)
-    if (req.skip > 0) cursor = cursor.skip(req.skip)
-    if (req.limit !== undefined && req.limit > 0) cursor = cursor.limit(req.limit)
-
-    const docs: Document[] = await cursor.toArray()
+    const docs = await this.track(req.requestId, (signal) => {
+      let cursor = coll.find<Uint8Array>(filter, { raw: true, signal })
+      if (Object.keys(projection).length > 0) cursor = cursor.project<Uint8Array>(projection)
+      if (Object.keys(sort).length > 0) cursor = cursor.sort(sort)
+      if (req.skip > 0) cursor = cursor.skip(req.skip)
+      if (req.limit !== undefined && req.limit > 0) cursor = cursor.limit(req.limit)
+      return cursor.toArray()
+    })
     const tookMs = Date.now() - startedAt
 
-    const documents: DocumentEnvelope[] = docs.map(toEnvelope)
+    const documents: DocumentEnvelope[] = docs.map((bytes) => toEnvelope(decodeDocument(bytes)))
 
     return { documents, tookMs }
   }
@@ -53,27 +97,56 @@ export class QueryService {
     const pipeline = parsePipeline(req.pipeline)
 
     const startedAt = Date.now()
-    const docs = await coll.aggregate(pipeline).toArray()
+    // The server applies the cap, so a $sort before it becomes a top-k sort.
+    const docs = await this.track(req.requestId, (signal) =>
+      coll
+        .aggregate<Uint8Array>([...pipeline, { $limit: RESULT_CAP + 1 }], { raw: true, signal })
+        .toArray()
+    )
     const tookMs = Date.now() - startedAt
 
-    return { documents: docs.map(toEnvelope), tookMs }
+    return {
+      documents: docs.slice(0, RESULT_CAP).map((bytes) => toEnvelope(decodeDocument(bytes))),
+      tookMs,
+      truncated: docs.length > RESULT_CAP
+    }
   }
 
-  async count(req: {
-    connectionId: string
-    db: string
-    coll: string
-    filter?: string
-  }): Promise<{ count: number; estimated: boolean }> {
+  async count(req: CountRequest): Promise<CountResponse> {
     const client = this.connections.getClient(req.connectionId)
     const coll = client.db(req.db).collection(req.coll)
     const filter = parseFilter(req.filter)
-    if (Object.keys(filter).length === 0) {
+    const startedAt = Date.now()
+    if (!req.exact && Object.keys(filter).length === 0) {
       const count = await coll.estimatedDocumentCount()
-      return { count, estimated: true }
+      return { count, estimated: true, tookMs: Date.now() - startedAt }
     }
-    const count = await coll.countDocuments(filter)
-    return { count, estimated: false }
+    const count = await this.track(req.requestId, (signal) =>
+      coll.countDocuments(filter, { signal })
+    )
+    return { count, estimated: false, tookMs: Date.now() - startedAt }
+  }
+
+  async distinct(req: DistinctRequest): Promise<DistinctResponse> {
+    const client = this.connections.getClient(req.connectionId)
+    const coll = client.db(req.db).collection(req.coll)
+    const filter = parseFilter(req.filter)
+
+    const startedAt = Date.now()
+    // distinct cannot read raw, so Int32 and Double values both arrive as numbers.
+    const values = await coll.distinct(req.field, filter, REPLY_DECODE_OPTIONS)
+    const tookMs = Date.now() - startedAt
+
+    return {
+      documents: values.slice(0, RESULT_CAP).map((value: unknown) => toEnvelope({ value })),
+      tookMs,
+      truncated: values.length > RESULT_CAP
+    }
+  }
+
+  /** Aborts the run registered under `requestId`; ids of settled or unknown runs are ignored. */
+  cancel(requestId: string): void {
+    this.running.get(requestId)?.abort(cancelledError('Query cancelled'))
   }
 
   async replaceOne(req: ReplaceOneRequest): Promise<ReplaceOneResponse> {
@@ -83,13 +156,13 @@ export class QueryService {
     const replacement = parseDocument(req.replacement)
 
     const idFilter = { _id: idValue } as Filter<Document>
-    const fresh = await coll.findOne(idFilter)
+    const fresh = await coll.findOne<Uint8Array>(idFilter, { raw: true })
     if (!fresh) {
       const e = new Error('Document not found — it may have been deleted')
       e.name = 'DocumentNotFoundError'
       throw e
     }
-    if (canonicalHash(fresh) !== req.expectedHash) {
+    if (canonicalHash(decodeDocument(fresh)) !== req.expectedHash) {
       const e = new Error('Document changed since you opened it')
       e.name = 'DocumentConflictError'
       throw e
@@ -142,11 +215,11 @@ export class QueryService {
     const idValue = parseId(req.id)
     const idFilter = { _id: idValue } as Filter<Document>
 
-    const fresh = await coll.findOne(idFilter)
+    const fresh = await coll.findOne<Uint8Array>(idFilter, { raw: true })
     if (!fresh) {
       return { deletedCount: 0 }
     }
-    if (canonicalHash(fresh) !== req.expectedHash) {
+    if (canonicalHash(decodeDocument(fresh)) !== req.expectedHash) {
       const e = new Error('Document changed since you opened it')
       e.name = 'DocumentConflictError'
       throw e
@@ -155,15 +228,42 @@ export class QueryService {
     const result = await coll.deleteOne(idFilter)
     return { deletedCount: result.deletedCount }
   }
+
+  /** Validates a shell write by the parser's rules, then runs it; writes take no abort signal. */
+  async write(req: WriteRequest): Promise<WriteResponse> {
+    const execute = prepareWrite(req.op)
+    const coll = this.connections.getClient(req.connectionId).db(req.db).collection(req.coll)
+    const startedAt = Date.now()
+    const outcome = await execute(coll)
+    return { ...outcome, tookMs: Date.now() - startedAt }
+  }
+
+  // Registers before the first await, so a cancel that arrives right after the request finds it.
+  private async track<T>(
+    requestId: string | undefined,
+    run: (signal: AbortSignal | undefined) => Promise<T>
+  ): Promise<T> {
+    if (requestId === undefined) return run(undefined)
+    const controller = new AbortController()
+    this.running.set(requestId, controller)
+    try {
+      return await run(controller.signal)
+    } catch (error) {
+      // A cancel during getMore surfaces as the server's interrupt error, not as the abort reason.
+      throw controller.signal.aborted ? controller.signal.reason : error
+    } finally {
+      if (this.running.get(requestId) === controller) this.running.delete(requestId)
+    }
+  }
 }
 
 function toEnvelope(doc: Document): DocumentEnvelope {
-  const idValue = doc['_id']
+  const canonical = toCanonicalString(doc)
   return {
-    id: toCanonicalString(idValue),
+    id: '_id' in doc ? toCanonicalString(doc['_id']) : null,
     data: toRelaxed(doc),
-    canonical: toCanonicalString(doc),
-    hash: canonicalHash(doc)
+    canonical,
+    hash: hashCanonicalString(canonical)
   }
 }
 
@@ -173,27 +273,203 @@ function parseId(canonical: string): unknown {
 
 function parseDocument(canonical: string): Document {
   const parsed = EJSON.parse(canonical, { relaxed: false })
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    const e = new Error('Document must be a JSON object')
-    e.name = 'ValidationError'
-    throw e
-  }
+  if (!isDocument(parsed)) throw validationError('Document must be a JSON object')
   return parsed as Document
 }
 
 function parsePipeline(canonical: string): Document[] {
+  const stages = parseStages(canonical)
+  const rejected = findRejectedStage(stages)
+  if (rejected !== null) throw validationError(rejectedStageMessage(rejected))
+  return stages
+}
+
+function parseStages(canonical: string): Document[] {
   const parsed = EJSON.parse(canonical, { relaxed: false })
-  if (!Array.isArray(parsed)) {
-    const e = new Error('Pipeline must be an array of stage objects')
-    e.name = 'ValidationError'
-    throw e
-  }
+  if (!Array.isArray(parsed)) throw validationError('Pipeline must be an array of stage objects')
   for (const stage of parsed) {
-    if (typeof stage !== 'object' || stage === null || Array.isArray(stage)) {
-      const e = new Error('Each pipeline stage must be an object')
-      e.name = 'ValidationError'
-      throw e
-    }
+    if (!isDocument(stage)) throw validationError('Each pipeline stage must be an object')
   }
   return parsed as Document[]
 }
+
+type WriteOutcome = Omit<WriteResponse, 'tookMs'>
+
+// Not raw: an error reply's topologyVersion would arrive as bytes and break failover detection.
+const MODIFY_OPTIONS = { ...REPLY_DECODE_OPTIONS, includeResultMetadata: true } as const
+
+// Parses and validates up front, so an invalid write throws before anything reaches the server.
+function prepareWrite(op: WriteOp): (coll: Collection) => Promise<WriteOutcome> {
+  switch (op.method) {
+    case 'insertOne': {
+      const document = parseChecked(op.document, insertDocumentError)
+      const options = parseOptions(op.method, op.options)
+      return async (coll) => {
+        const result = await coll.insertOne(document, options)
+        return { counts: { inserted: 1 }, ...idList([result.insertedId]) }
+      }
+    }
+    case 'insertMany': {
+      const documents = op.documents.map((text) => parseChecked(text, insertDocumentError))
+      const options = parseOptions(op.method, op.options)
+      return async (coll) => {
+        const result = await coll.insertMany(documents, options)
+        return {
+          counts: { inserted: result.insertedCount },
+          ...idList(Object.values(result.insertedIds))
+        }
+      }
+    }
+    case 'updateOne':
+    case 'updateMany': {
+      const { method } = op
+      const filter = parseWriteFilter(method, op.filter)
+      const update = parseChecked(op.update, updateError)
+      const options = { ...parseOptions(method, op.options), ...REPLY_DECODE_OPTIONS }
+      return async (coll) =>
+        updateOutcome(
+          method === 'updateOne'
+            ? await coll.updateOne(filter, update, options)
+            : await coll.updateMany(filter, update, options)
+        )
+    }
+    case 'replaceOne': {
+      const filter = parseWriteFilter(op.method, op.filter)
+      const replacement = parseChecked(op.replacement, replacementError)
+      const options = { ...parseOptions(op.method, op.options), ...REPLY_DECODE_OPTIONS }
+      return async (coll) => updateOutcome(await coll.replaceOne(filter, replacement, options))
+    }
+    case 'deleteOne':
+    case 'deleteMany': {
+      const { method } = op
+      const filter = parseWriteFilter(method, op.filter)
+      const options = parseOptions(method, op.options)
+      return async (coll) => {
+        const result =
+          method === 'deleteOne'
+            ? await coll.deleteOne(filter, options)
+            : await coll.deleteMany(filter, options)
+        return { counts: { deleted: result.deletedCount }, ...idList([]) }
+      }
+    }
+    case 'findOneAndUpdate': {
+      const filter = parseWriteFilter(op.method, op.filter)
+      const update = parseChecked(op.update, updateError)
+      const options = returnDocumentOptions(parseOptions(op.method, op.options))
+      return async (coll) =>
+        modifyOutcome(
+          await coll.findOneAndUpdate(filter, update, { ...options, ...MODIFY_OPTIONS }),
+          'update'
+        )
+    }
+    case 'findOneAndReplace': {
+      const filter = parseWriteFilter(op.method, op.filter)
+      const replacement = parseChecked(op.replacement, replacementError)
+      const options = returnDocumentOptions(parseOptions(op.method, op.options))
+      return async (coll) =>
+        modifyOutcome(
+          await coll.findOneAndReplace(filter, replacement, { ...options, ...MODIFY_OPTIONS }),
+          'update'
+        )
+    }
+    case 'findOneAndDelete': {
+      const filter = parseWriteFilter(op.method, op.filter)
+      const options = parseOptions(op.method, op.options)
+      return async (coll) =>
+        modifyOutcome(
+          await coll.findOneAndDelete(filter, { ...options, ...MODIFY_OPTIONS }),
+          'delete'
+        )
+    }
+    case 'bulkWrite': {
+      const operations = parseChecked(op.operations, bulkWriteError) as AnyBulkWriteOperation[]
+      const options = { ...parseOptions(op.method, op.options), ...REPLY_DECODE_OPTIONS }
+      return async (coll) => {
+        const result = await coll.bulkWrite(operations, options)
+        return {
+          counts: {
+            inserted: result.insertedCount,
+            matched: result.matchedCount,
+            modified: result.modifiedCount,
+            deleted: result.deletedCount,
+            upserted: result.upsertedCount
+          },
+          // Not merged by key: unordered writes key each map by position among operations of its kind.
+          ...idList([...Object.values(result.insertedIds), ...Object.values(result.upsertedIds)])
+        }
+      }
+    }
+    case 'aggregate': {
+      const stages = parseStages(op.pipeline)
+      rejectInvalid(
+        finalWriteStage(stages) === null
+          ? 'A write pipeline must end with $out or $merge'
+          : writePipelineError(stages)
+      )
+      return async (coll) => {
+        // The server writes while the cursor is drained; $out / $merge return no documents.
+        await coll.aggregate(stages).toArray()
+        return { counts: {}, ...idList([]) }
+      }
+    }
+  }
+}
+
+function updateOutcome(result: UpdateResult): WriteOutcome {
+  return {
+    counts: {
+      matched: result.matchedCount,
+      modified: result.modifiedCount,
+      upserted: result.upsertedCount
+    },
+    ...idList(result.upsertedCount > 0 ? [result.upsertedId] : [])
+  }
+}
+
+function modifyOutcome(result: ModifyResult, kind: 'update' | 'delete'): WriteOutcome {
+  const meta = result.lastErrorObject ?? {}
+  const n = Number(meta['n'] ?? 0)
+  const upserted = 'upserted' in meta ? [meta['upserted']] : []
+  return {
+    counts:
+      kind === 'delete'
+        ? { deleted: n }
+        : { matched: meta['updatedExisting'] === true ? n : 0, upserted: upserted.length },
+    ...idList(upserted),
+    document: result.value === null ? null : toEnvelope(result.value)
+  }
+}
+
+function idList(ids: readonly unknown[]): Pick<WriteResponse, 'ids' | 'idsTruncated'> {
+  return {
+    ids: ids.slice(0, RESULT_CAP).map((id) => toCanonicalString(id)),
+    idsTruncated: ids.length > RESULT_CAP
+  }
+}
+
+function parseChecked(canonical: string, problem: (value: unknown) => string | null): Document {
+  const value: unknown = EJSON.parse(canonical, { relaxed: false })
+  rejectInvalid(problem(value))
+  return value as Document
+}
+
+function parseWriteFilter(method: WriteMethod, canonical: string): Document {
+  return parseChecked(canonical, (filter) => filterError(method, filter))
+}
+
+function parseOptions(method: WriteMethod, canonical: string | undefined): Document {
+  return canonical === undefined
+    ? {}
+    : parseChecked(canonical, (options) => writeOptionsError(method, options))
+}
+
+// mongosh's returnNewDocument; the driver only knows returnDocument.
+function returnDocumentOptions({ returnNewDocument, ...options }: Document): Document {
+  return returnNewDocument === undefined
+    ? options
+    : { ...options, returnDocument: returnNewDocument === true ? 'after' : 'before' }
+}
+
+function rejectInvalid(message: string | null): void {
+  if (message !== null) throw validationError(message)
+}
diff --git a/src/main/services/SshTunnelService.test.ts b/src/main/services/SshTunnelService.test.ts
index 08d9175..a9753eb 100644
--- a/src/main/services/SshTunnelService.test.ts
+++ b/src/main/services/SshTunnelService.test.ts
@@ -1,8 +1,12 @@
 import { generateKeyPairSync } from 'node:crypto'
+import { promises as fs } from 'node:fs'
 import type { AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
 import { SocksClient } from 'socks'
 import { Server, utils, type Connection } from 'ssh2'
+import type { Tunnel, TunnelProxyOptions } from '../lib/tunnel'
 
 // The service logs through electron-log, which pulls in electron itself.
 vi.mock('electron-log/main', () => ({
@@ -12,8 +16,8 @@ vi.mock('electron-log/main', () => ({
 const { SshAuthError, SshHostKeyMismatchError, SshTunnelService } =
   await import('./SshTunnelService')
 const { fingerprint } = await import('../lib/knownHosts')
+const { default: log } = await import('electron-log/main')
 type SshTunnelServiceType = InstanceType<typeof SshTunnelService>
-type TunnelProxyOptions = Awaited<ReturnType<SshTunnelServiceType['open']>>['proxyOptions']
 
 const USERNAME = 'tunneluser'
 const PASSWORD = 'tunnelsecret'
@@ -21,6 +25,7 @@ const PASSWORD = 'tunnelsecret'
 const NO_KNOWN_HOSTS = 'C:\\nonexistent\\mongobench-test\\known_hosts'
 
 let hostKeyPem: string
+let ed25519HostKey: string
 
 beforeAll(() => {
   // RSA rather than ed25519: PEM is the format ssh2's server side reads
@@ -30,11 +35,12 @@ beforeAll(() => {
     publicKeyEncoding: { type: 'spki', format: 'pem' },
     privateKeyEncoding: { type: 'pkcs1', format: 'pem' }
   }).privateKey
+  ed25519HostKey = utils.generateKeyPairSync('ed25519').private
 })
 
 /** The public key blob as it goes over the wire, for the pin-store fixtures. */
-function hostKeyBlob(): Buffer {
-  const parsed = utils.parseKey(hostKeyPem)
+function hostKeyBlob(privateKey = hostKeyPem): Buffer {
+  const parsed = utils.parseKey(privateKey)
   if (parsed instanceof Error) throw parsed
   const key = Array.isArray(parsed) ? parsed[0] : parsed
   if (key === undefined) throw new Error('no key parsed')
@@ -63,18 +69,29 @@ afterEach(async () => {
   fixture = null
 })
 
+type FixtureOptions = {
+  storedHostKey?: Buffer
+  /** Also offer an ed25519 host key, which ssh2 clients prefer by default. */
+  withEd25519HostKey?: boolean
+  /** known_hosts content for the fixture's port; omitted means no file. */
+  knownHosts?: (sshPort: number) => string
+  /** Refuse every direct-tcpip channel, as sshd does with AllowTcpForwarding no. */
+  refuseForwards?: boolean
+}
+
 /**
  * A real in-process SSH server that accepts password auth and echoes back
  * everything sent through a direct-tcpip channel.
  */
-async function startFixture(options: { storedHostKey?: Buffer } = {}): Promise<Fixture> {
+async function startFixture(options: FixtureOptions = {}): Promise<Fixture> {
   const forwarded: Forwarded[] = []
   const pinned: Array<{ host: string; port: number }> = []
   const dropped: string[] = []
 
   const live = new Set<Connection>()
 
-  const server = new Server({ hostKeys: [hostKeyPem] }, (client: Connection) => {
+  const hostKeys = options.withEd25519HostKey ? [hostKeyPem, ed25519HostKey] : [hostKeyPem]
+  const server = new Server({ hostKeys }, (client: Connection) => {
     live.add(client)
     client.on('close', () => live.delete(client))
     client.on('authentication', (ctx) => {
@@ -86,8 +103,12 @@ async function startFixture(options: { storedHostKey?: Buffer } = {}): Promise<F
       ctx.reject(['password'])
     })
     client.on('ready', () => {
-      client.on('tcpip', (accept, _reject, info) => {
+      client.on('tcpip', (accept, reject, info) => {
         forwarded.push({ host: info.destIP, port: info.destPort })
+        if (options.refuseForwards) {
+          reject()
+          return
+        }
         const channel = accept()
         channel.on('data', (chunk: Buffer) => channel.write(chunk))
       })
@@ -110,7 +131,15 @@ async function startFixture(options: { storedHostKey?: Buffer } = {}): Promise<F
     }
   }
 
-  const service = new SshTunnelService(trustStore, NO_KNOWN_HOSTS)
+  let knownHostsDir: string | null = null
+  let knownHostsPath = NO_KNOWN_HOSTS
+  if (options.knownHosts) {
+    knownHostsDir = await fs.mkdtemp(join(tmpdir(), 'mongobench-known-hosts-'))
+    knownHostsPath = join(knownHostsDir, 'known_hosts')
+    await fs.writeFile(knownHostsPath, options.knownHosts(sshPort), 'utf8')
+  }
+
+  const service = new SshTunnelService(trustStore, knownHostsPath)
 
   const killClients = (): void => {
     for (const client of live) client.end()
@@ -125,15 +154,21 @@ async function startFixture(options: { storedHostKey?: Buffer } = {}): Promise<F
     dropped,
     killClients,
     // close() alone waits for open connections, so hang up first.
-    stop: () =>
-      new Promise<void>((resolve) => {
+    stop: async () => {
+      await new Promise<void>((resolve) => {
         killClients()
         server.close(() => resolve())
       })
+      if (knownHostsDir !== null) await fs.rm(knownHostsDir, { recursive: true, force: true })
+    }
   }
   return fixture
 }
 
+function rsaKnownHostsLine(sshPort: number, marker = ''): string {
+  return `${marker}[127.0.0.1]:${sshPort} ssh-rsa ${hostKeyBlob().toString('base64')}\n`
+}
+
 function passwordConfig(port: number) {
   return {
     host: '127.0.0.1',
@@ -144,18 +179,24 @@ function passwordConfig(port: number) {
   }
 }
 
+function socksProxy(tunnel: Tunnel): TunnelProxyOptions {
+  if (tunnel.route.kind !== 'socks5') throw new Error('expected a SOCKS5 route')
+  return tunnel.route.proxy
+}
+
 function throughProxy(
-  tunnel: { proxyOptions: TunnelProxyOptions },
+  tunnel: Tunnel,
   destination: { host: string; port: number },
   timeout?: number
 ): ReturnType<typeof SocksClient.createConnection> {
+  const proxy = socksProxy(tunnel)
   return SocksClient.createConnection({
     proxy: {
-      host: tunnel.proxyOptions.proxyHost,
-      port: tunnel.proxyOptions.proxyPort,
+      host: proxy.proxyHost,
+      port: proxy.proxyPort,
       type: 5,
-      userId: tunnel.proxyOptions.proxyUsername,
-      password: tunnel.proxyOptions.proxyPassword
+      userId: proxy.proxyUsername,
+      password: proxy.proxyPassword
     },
     command: 'connect',
     destination,
@@ -182,6 +223,20 @@ describe('SshTunnelService', () => {
     expect(f.forwarded).toEqual([{ host: 'mongo2.internal', port: 27017 }])
   })
 
+  it('logs the SSH reason when the server refuses to forward', async () => {
+    const f = await startFixture({ refuseForwards: true })
+    const tunnel = await f.service.open(passwordConfig(f.sshPort))
+    vi.mocked(log.warn).mockClear()
+
+    await expect(throughProxy(tunnel, { host: 'mongo1.internal', port: 27017 })).rejects.toThrow()
+
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'failed to forward to mongo1.internal:27017: (SSH) Channel open failure'
+      )
+    )
+  })
+
   it('pins a host key it has never seen and reports it', async () => {
     const f = await startFixture()
     const tunnel = await f.service.open(passwordConfig(f.sshPort))
@@ -205,6 +260,52 @@ describe('SshTunnelService', () => {
     expect(f.service.openCount).toBe(0)
   })
 
+  it('negotiates the key type known_hosts lists when the server also has a preferred one', async () => {
+    const f = await startFixture({
+      withEd25519HostKey: true,
+      knownHosts: (sshPort) => rsaKnownHostsLine(sshPort)
+    })
+    const tunnel = await f.service.open(passwordConfig(f.sshPort))
+    expect(tunnel.pinnedHostKey).toBeNull()
+    expect(f.pinned).toEqual([])
+  })
+
+  it('ignores the type of an older pin once known_hosts lists the host', async () => {
+    const f = await startFixture({
+      withEd25519HostKey: true,
+      storedHostKey: hostKeyBlob(ed25519HostKey),
+      knownHosts: (sshPort) => rsaKnownHostsLine(sshPort)
+    })
+    const tunnel = await f.service.open(passwordConfig(f.sshPort))
+    expect(tunnel.pinnedHostKey).toBeNull()
+  })
+
+  it('negotiates the pinned key type when the server gained a preferred one', async () => {
+    const f = await startFixture({ withEd25519HostKey: true, storedHostKey: hostKeyBlob() })
+    const tunnel = await f.service.open(passwordConfig(f.sshPort))
+    expect(tunnel.pinnedHostKey).toBeNull()
+    expect(f.pinned).toEqual([])
+  })
+
+  it('refuses a host key known_hosts marks as revoked instead of pinning it', async () => {
+    const f = await startFixture({
+      knownHosts: () => `@revoked * ssh-rsa ${hostKeyBlob().toString('base64')}\n`
+    })
+    const opening = f.service.open(passwordConfig(f.sshPort))
+    await expect(opening).rejects.toThrow(SshHostKeyMismatchError)
+    await expect(opening).rejects.toThrow(/marks as revoked!$/)
+    expect(f.pinned).toEqual([])
+    expect(f.service.openCount).toBe(0)
+  })
+
+  it('refuses a revoked host key even though it was pinned earlier', async () => {
+    const f = await startFixture({
+      storedHostKey: hostKeyBlob(),
+      knownHosts: (sshPort) => rsaKnownHostsLine(sshPort, '@revoked ')
+    })
+    await expect(f.service.open(passwordConfig(f.sshPort))).rejects.toThrow(SshHostKeyMismatchError)
+  })
+
   it('reports bad credentials as an auth failure', async () => {
     const f = await startFixture()
     await expect(
diff --git a/src/main/services/SshTunnelService.ts b/src/main/services/SshTunnelService.ts
index 65d1b8d..f82227d 100644
--- a/src/main/services/SshTunnelService.ts
+++ b/src/main/services/SshTunnelService.ts
@@ -4,16 +4,21 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Duplex } from 'node:stream'
 import log from 'electron-log/main'
-import { Client, type ConnectConfig } from 'ssh2'
+import { Client, type Algorithms, type ConnectConfig } from 'ssh2'
+import ssh2Constants from 'ssh2/lib/protocol/constants'
 import type { PinnedHostKeyNotice, SshAuthMethod } from '@shared/types'
 import {
   findHostKeys,
   fingerprint,
+  isRevoked,
   keyMatches,
+  keyTypeOf,
+  orderHostKeyAlgorithms,
   parseKnownHosts,
   type KnownHostEntry
 } from '../lib/knownHosts'
 import { createSocks5Server, type Socks5Server } from '../lib/socks5'
+import type { Tunnel } from '../lib/tunnel'
 
 const READY_TIMEOUT_MS = 15_000
 /** Idle sessions get dropped by firewalls and by sshd's own timeouts. */
@@ -31,22 +36,6 @@ export type ResolvedSshTunnel = {
   passphrase?: string
 }
 
-/** What the driver needs to route through the tunnel. */
-export type TunnelProxyOptions = {
-  proxyHost: string
-  proxyPort: number
-  proxyUsername: string
-  proxyPassword: string
-}
-
-/** An open tunnel. The caller owns it and is responsible for closing it. */
-export type Tunnel = {
-  proxyOptions: TunnelProxyOptions
-  /** Set only when this open pinned a host key it had never seen. */
-  pinnedHostKey: PinnedHostKeyNotice | null
-  close: () => Promise<void>
-}
-
 export class SshConnectError extends Error {
   constructor(message: string, options?: ErrorOptions) {
     super(message, options)
@@ -103,6 +92,7 @@ export class SshTunnelService {
   /** `onDropped` fires when the session dies on its own, never on `close()`. */
   async open(config: ResolvedSshTunnel, onDropped?: (reason: string) => void): Promise<Tunnel> {
     const auth = await authConfig(config)
+    const knownHosts = await readKnownHosts(this.knownHostsPath)
     const client = new Client()
 
     // hostVerifier can only answer yes/no, so the reason is kept here to make
@@ -119,14 +109,16 @@ export class SshTunnelService {
     })
 
     try {
+      const algorithms = await this.hostKeyAlgorithms(knownHosts, config.host, config.port)
       client.connect({
         host: config.host,
         port: config.port,
         username: config.username,
         readyTimeout: READY_TIMEOUT_MS,
         keepaliveInterval: KEEPALIVE_INTERVAL_MS,
+        algorithms,
         hostVerifier: (key: Buffer, verify: (valid: boolean) => void): void => {
-          this.verifyHostKey(config.host, config.port, key)
+          this.verifyHostKey(knownHosts, config.host, config.port, key)
             .then((pinned) => {
               pinnedHostKey = pinned
               verify(true)
@@ -154,7 +146,7 @@ export class SshTunnelService {
         username: proxyUsername,
         password: proxyPassword,
         connect: (host, port) => forwardOut(client, host, port),
-        onError: (error) => log.debug(`SOCKS5 proxy: ${error.message}`)
+        onError: (error) => log.warn(`SOCKS5 proxy: ${error.message}`)
       })
     } catch (error) {
       client.destroy()
@@ -169,8 +161,12 @@ export class SshTunnelService {
     }
 
     const tunnel: Tunnel = {
-      proxyOptions: { proxyHost: LOOPBACK, proxyPort: server.port, proxyUsername, proxyPassword },
+      route: {
+        kind: 'socks5',
+        proxy: { proxyHost: LOOPBACK, proxyPort: server.port, proxyUsername, proxyPassword }
+      },
       pinnedHostKey,
+      failure: () => null,
       close: async () => {
         if (closed) return
         await teardown()
@@ -202,16 +198,39 @@ export class SshTunnelService {
     await Promise.allSettled(tunnels.map((tunnel) => tunnel.close()))
   }
 
+  private async hostKeyAlgorithms(
+    knownHosts: KnownHostEntry[],
+    host: string,
+    port: number
+  ): Promise<Algorithms | undefined> {
+    // Same trust order as verifyHostKey: the pin store counts only when known_hosts lists nothing.
+    const listed = findHostKeys(knownHosts, host, port)
+    const pinned = listed.length > 0 ? null : await this.hostKeys.get(host, port)
+    const trusted = pinned === null ? listed : [pinned]
+    const types = trusted.map(keyTypeOf).filter((type): type is string => type !== null)
+    if (types.length === 0) return undefined
+    // hostVerifier sees only the negotiated key, so a trusted key type has to win the negotiation.
+    return { serverHostKey: orderHostKeyAlgorithms(types, ssh2Constants.DEFAULT_SERVER_HOST_KEY) }
+  }
+
   /**
-   * Trust order: the user's own known_hosts wins, then our pin store, and only
-   * a host neither knows about gets pinned on the spot.
+   * A key known_hosts revokes is refused outright. Otherwise the user's own
+   * known_hosts wins, then our pin store, and only a host neither knows about
+   * gets pinned on the spot.
    */
   private async verifyHostKey(
+    knownHosts: KnownHostEntry[],
     host: string,
     port: number,
     key: Buffer
   ): Promise<PinnedHostKeyNotice | null> {
-    const allowed = findHostKeys(await readKnownHosts(this.knownHostsPath), host, port)
+    if (isRevoked(knownHosts, host, port, key)) {
+      throw new SshHostKeyMismatchError(
+        `${host} presented host key ${fingerprint(key)}, which your ~/.ssh/known_hosts marks as revoked!`
+      )
+    }
+
+    const allowed = findHostKeys(knownHosts, host, port)
     if (allowed.length > 0) {
       if (allowed.some((known) => keyMatches(key, known))) return null
       throw new SshHostKeyMismatchError(
diff --git a/src/main/services/UserService.test.ts b/src/main/services/UserService.test.ts
new file mode 100644
index 0000000..0787e98
--- /dev/null
+++ b/src/main/services/UserService.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { ObjectId } from 'bson'
+import type { ConnectionService } from './ConnectionService'
+import { UserService } from './UserService'
+
+function serviceReturning(reply: Record<string, unknown>): {
+  service: UserService
+  calls: Array<{ db: string; command: Record<string, unknown> }>
+} {
+  const calls: Array<{ db: string; command: Record<string, unknown> }> = []
+  const connections = {
+    getClient: () => ({
+      db: (db: string) => ({
+        command: async (command: Record<string, unknown>) => {
+          calls.push({ db, command })
+          return reply
+        }
+      })
+    })
+  } as unknown as ConnectionService
+  return { service: new UserService(connections), calls }
+}
+
+describe('UserService.listUsers', () => {
+  it('returns customData as relaxed EJSON so it survives structured clone', async () => {
+    const id = new ObjectId('64b7f0c2a1b2c3d4e5f60718')
+    const { service } = serviceReturning({
+      users: [
+        {
+          user: 'svc',
+          db: 'shop',
+          roles: [{ role: 'read', db: 'shop' }],
+          customData: { owner: id, since: new Date('2024-01-02T03:04:05.678Z') }
+        }
+      ]
+    })
+    const [user] = await service.listUsers('c1', 'shop')
+    expect(user?.customData).toEqual({
+      owner: { $oid: '64b7f0c2a1b2c3d4e5f60718' },
+      since: { $date: '2024-01-02T03:04:05.678Z' }
+    })
+  })
+
+  it('leaves customData out when the user has none', async () => {
+    const { service } = serviceReturning({ users: [{ user: 'svc', db: 'shop' }] })
+    expect(await service.listUsers('c1', 'shop')).toEqual([{ user: 'svc', db: 'shop', roles: [] }])
+  })
+})
+
+describe('UserService.listRoles', () => {
+  it('runs rolesInfo with built-in roles on the given db', async () => {
+    const { service, calls } = serviceReturning({ roles: [] })
+    await service.listRoles('c1', 'shop')
+    expect(calls).toEqual([{ db: 'shop', command: { rolesInfo: 1, showBuiltinRoles: true } }])
+  })
+
+  it('maps the reported roles and flags built-ins', async () => {
+    const { service } = serviceReturning({
+      roles: [
+        { role: 'read', db: 'shop', isBuiltin: true, roles: [], inheritedRoles: [] },
+        { role: 'orderClerk', db: 'shop', isBuiltin: false },
+        { role: 'legacy', db: 'shop' }
+      ]
+    })
+    expect(await service.listRoles('c1', 'shop')).toEqual([
+      { role: 'read', db: 'shop', isBuiltin: true },
+      { role: 'orderClerk', db: 'shop', isBuiltin: false },
+      { role: 'legacy', db: 'shop', isBuiltin: false }
+    ])
+  })
+
+  it('returns an empty list when the server reports no roles field', async () => {
+    const { service } = serviceReturning({ ok: 1 })
+    expect(await service.listRoles('c1', 'shop')).toEqual([])
+  })
+})
diff --git a/src/main/services/UserService.ts b/src/main/services/UserService.ts
index 2df89fa..fae70e5 100644
--- a/src/main/services/UserService.ts
+++ b/src/main/services/UserService.ts
@@ -1,6 +1,7 @@
 import type { Document } from 'mongodb'
 import type { ConnectionService } from './ConnectionService'
-import type { DatabaseUser, DatabaseUserRole } from '@shared/types'
+import { toRelaxed } from '../lib/ejson'
+import type { DatabaseRoleInfo, DatabaseUser, DatabaseUserRole } from '@shared/types'
 
 export class UserService {
   constructor(private readonly connections: ConnectionService) {}
@@ -20,11 +21,23 @@ export class UserService {
       user: u.user,
       db: u.db,
       roles: u.roles ?? [],
-      ...(u.customData !== undefined ? { customData: u.customData } : {}),
+      ...(u.customData !== undefined ? { customData: toRelaxed(u.customData) } : {}),
       ...(u.mechanisms !== undefined ? { mechanisms: u.mechanisms } : {})
     }))
   }
 
+  async listRoles(connectionId: string, db: string): Promise<DatabaseRoleInfo[]> {
+    const client = this.connections.getClient(connectionId)
+    const result = (await client.db(db).command({ rolesInfo: 1, showBuiltinRoles: true })) as {
+      roles?: Array<{ role: string; db: string; isBuiltin?: boolean }>
+    }
+    return (result.roles ?? []).map((r) => ({
+      role: r.role,
+      db: r.db,
+      isBuiltin: r.isBuiltin === true
+    }))
+  }
+
   async createUser(
     connectionId: string,
     db: string,
diff --git a/src/main/ssh2Constants.d.ts b/src/main/ssh2Constants.d.ts
new file mode 100644
index 0000000..a654525
--- /dev/null
+++ b/src/main/ssh2Constants.d.ts
@@ -0,0 +1,10 @@
+// ssh2 ships no types for its internals; only the list SshTunnelService reorders is declared.
+declare module 'ssh2/lib/protocol/constants' {
+  import type { ServerHostKeyAlgorithm } from 'ssh2'
+
+  const constants: {
+    /** ssh2's host key preference order; it lists `ssh-ed25519` only where the runtime supports it. */
+    DEFAULT_SERVER_HOST_KEY: readonly ServerHostKeyAlgorithm[]
+  }
+  export = constants
+}
diff --git a/src/main/stores/ConnectionsRepository.test.ts b/src/main/stores/ConnectionsRepository.test.ts
index af21daa..f71620d 100644
--- a/src/main/stores/ConnectionsRepository.test.ts
+++ b/src/main/stores/ConnectionsRepository.test.ts
@@ -2,7 +2,7 @@ import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import type { ConnectionInput, SshTunnelInput } from '@shared/types'
+import type { CloudflaredTunnelInput, ConnectionInput, SshTunnelInput } from '@shared/types'
 
 // The repository imports electron for the default userData path; every test
 // passes an explicit directory instead, so getPath is never actually called.
@@ -26,6 +26,7 @@ const secrets = {
 const SSH_PASSWORD = 'ssh-cleartext-password'
 const SSH_PASSPHRASE = 'key-cleartext-passphrase'
 const MONGO_PASSWORD = 'mongo-cleartext-password'
+const TOKEN_SECRET = 'cfast_cleartext-token-secret'
 
 let dir: string
 let repo: InstanceType<typeof ConnectionsRepository>
@@ -61,6 +62,21 @@ function input(ssh?: Partial<SshTunnelInput>): ConnectionInput {
   }
 }
 
+function cloudflaredInput(cloudflared: Partial<CloudflaredTunnelInput>): ConnectionInput {
+  return {
+    name: 'Behind Access',
+    uri: 'mongodb://user@localhost/admin',
+    password: MONGO_PASSWORD,
+    cloudflared: {
+      enabled: true,
+      hostname: 'mongo.example.com',
+      authMethod: 'serviceToken',
+      serviceTokenId: 'abc.access',
+      ...cloudflared
+    }
+  }
+}
+
 describe('secrets on disk', () => {
   it('never writes a cleartext password or passphrase', async () => {
     await repo.create(
@@ -154,6 +170,90 @@ describe('secrets across edits', () => {
   })
 })
 
+describe('Cloudflare service token secret', () => {
+  it('never writes the cleartext secret and decrypts it back', async () => {
+    const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+    const stored = await repo.getStored(created.id)
+
+    expect(await onDisk()).not.toContain(TOKEN_SECRET)
+    expect(stored?.cloudflared?.encryptedServiceTokenSecret).toMatch(/^enc:/)
+    expect(repo.decryptCloudflared(stored!)).toEqual({ serviceTokenSecret: TOKEN_SECRET })
+  })
+
+  it('keeps the stored secret when the form leaves it blank', async () => {
+    const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+    await repo.update(created.id, cloudflaredInput({ serviceTokenSecret: '' }))
+    const stored = await repo.getStored(created.id)
+    expect(repo.decryptCloudflared(stored!)).toEqual({ serviceTokenSecret: TOKEN_SECRET })
+  })
+
+  it.each([
+    ['hostname', { hostname: 'other-app.example.com' }],
+    ['client ID', { serviceTokenId: 'other.access' }]
+  ])(
+    'drops the saved secret when the %s changes and the form leaves it blank',
+    async (_case, edit) => {
+      const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+      await repo.update(created.id, cloudflaredInput({ ...edit, serviceTokenSecret: '' }))
+      const stored = await repo.getStored(created.id)
+      expect(stored?.cloudflared?.encryptedServiceTokenSecret).toBeUndefined()
+      expect(repo.decryptCloudflared(stored!)).toEqual({})
+    }
+  )
+
+  it('stores the secret typed together with a new hostname', async () => {
+    const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+    await repo.update(
+      created.id,
+      cloudflaredInput({ hostname: 'other-app.example.com', serviceTokenSecret: 'other-secret' })
+    )
+    const stored = await repo.getStored(created.id)
+    expect(repo.decryptCloudflared(stored!)).toEqual({ serviceTokenSecret: 'other-secret' })
+  })
+
+  it('drops the secret when switching to browser sign-in', async () => {
+    const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+    await repo.update(created.id, cloudflaredInput({ authMethod: 'browser' }))
+    const stored = await repo.getStored(created.id)
+    expect(stored?.cloudflared?.encryptedServiceTokenSecret).toBeUndefined()
+    expect(repo.decryptCloudflared(stored!)).toEqual({})
+  })
+
+  it('stores no secret typed while browser sign-in is selected', async () => {
+    const created = await repo.create(
+      cloudflaredInput({ authMethod: 'browser', serviceTokenSecret: TOKEN_SECRET })
+    )
+    const stored = await repo.getStored(created.id)
+    expect(stored?.cloudflared?.encryptedServiceTokenSecret).toBeUndefined()
+  })
+
+  it('keeps the tunnel settings when it is switched off', async () => {
+    const created = await repo.create(
+      cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET, binaryPath: 'C:\\cf\\cloudflared.exe' })
+    )
+    await repo.update(created.id, cloudflaredInput({ enabled: false, serviceTokenSecret: '' }))
+    const stored = await repo.getStored(created.id)
+    expect(stored?.cloudflared).toMatchObject({
+      enabled: false,
+      hostname: 'mongo.example.com',
+      serviceTokenId: 'abc.access'
+    })
+    expect(repo.decryptCloudflared(stored!)).toEqual({ serviceTokenSecret: TOKEN_SECRET })
+  })
+
+  it('stores blank optional fields as absent', async () => {
+    const created = await repo.create(
+      cloudflaredInput({ authMethod: 'browser', serviceTokenId: '', binaryPath: '' })
+    )
+    const stored = await repo.getStored(created.id)
+    expect(Object.keys(stored?.cloudflared ?? {}).sort()).toEqual([
+      'authMethod',
+      'enabled',
+      'hostname'
+    ])
+  })
+})
+
 describe('toRendererView', () => {
   it('replaces the SSH secrets with hasStored flags', async () => {
     const created = await repo.create(input({ password: SSH_PASSWORD }))
@@ -193,6 +293,23 @@ describe('toRendererView', () => {
     const created = await repo.create(input())
     const view = toRendererView((await repo.getStored(created.id))!)
     expect(view.ssh).toBeUndefined()
+    expect(view.cloudflared).toBeUndefined()
     expect(view.hasStoredPassword).toBe(true)
   })
+
+  it('replaces the service token secret with a hasStored flag', async () => {
+    const created = await repo.create(cloudflaredInput({ serviceTokenSecret: TOKEN_SECRET }))
+    const view = toRendererView((await repo.getStored(created.id))!)
+
+    expect(view.cloudflared).toEqual({
+      enabled: true,
+      hostname: 'mongo.example.com',
+      authMethod: 'serviceToken',
+      serviceTokenId: 'abc.access',
+      hasStoredServiceTokenSecret: true
+    })
+    const serialized = JSON.stringify(view)
+    expect(serialized).not.toContain(CIPHER_PREFIX)
+    expect(serialized).not.toContain(TOKEN_SECRET)
+  })
 })
diff --git a/src/main/stores/ConnectionsRepository.ts b/src/main/stores/ConnectionsRepository.ts
index 4c741d9..c0d2cbb 100644
--- a/src/main/stores/ConnectionsRepository.ts
+++ b/src/main/stores/ConnectionsRepository.ts
@@ -2,11 +2,15 @@ import { app } from 'electron'
 import { promises as fs } from 'node:fs'
 import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
+import { canReuseServiceTokenSecret } from '@shared/cloudflared'
 import type {
+  CloudflaredTunnelInput,
+  CloudflaredTunnelView,
   ConnectionConfig,
   ConnectionInput,
   SshTunnelInput,
   SshTunnelView,
+  StoredCloudflaredTunnel,
   StoredConnection,
   StoredSshTunnel
 } from '@shared/types'
@@ -116,6 +120,12 @@ export class ConnectionsRepository {
     }
   }
 
+  /** The Cloudflare service token secret in cleartext. Empty when the connection has none. */
+  decryptCloudflared(stored: StoredConnection): { serviceTokenSecret?: string } {
+    const encrypted = stored.cloudflared?.encryptedServiceTokenSecret
+    return encrypted !== undefined ? { serviceTokenSecret: this.secrets.decrypt(encrypted) } : {}
+  }
+
   private fromInput(input: ConnectionInput, existing?: StoredConnection): StoredConnection {
     const now = new Date().toISOString()
     const canonical = canonicalize({
@@ -127,6 +137,7 @@ export class ConnectionsRepository {
     })
 
     const ssh = this.sshFromInput(input.ssh, existing?.ssh)
+    const cloudflared = this.cloudflaredFromInput(input.cloudflared, existing?.cloudflared)
     let encryptedPassword: string | undefined = existing?.encryptedPassword
     let storageUri = canonical.storageUri
 
@@ -157,6 +168,7 @@ export class ConnectionsRepository {
         : {}),
       ...(input.appName !== undefined ? { appName: input.appName } : {}),
       ...(ssh !== undefined ? { ssh } : {}),
+      ...(cloudflared !== undefined ? { cloudflared } : {}),
       ...(input.directConnection !== undefined ? { directConnection: input.directConnection } : {}),
       ...(input.replicaSet !== undefined ? { replicaSet: input.replicaSet } : {}),
       ...(input.readPreference !== undefined ? { readPreference: input.readPreference } : {}),
@@ -217,6 +229,37 @@ export class ConnectionsRepository {
     }
   }
 
+  private cloudflaredFromInput(
+    input: CloudflaredTunnelInput | undefined,
+    existing: StoredCloudflaredTunnel | undefined
+  ): StoredCloudflaredTunnel | undefined {
+    if (input === undefined) return undefined
+
+    const usesSecret = input.authMethod === 'serviceToken'
+    // Blank keeps the saved secret only while a service token still targets the hostname and client ID it was saved for.
+    const carriedSecret =
+      usesSecret && canReuseServiceTokenSecret(existing, input)
+        ? existing?.encryptedServiceTokenSecret
+        : undefined
+    const encryptedServiceTokenSecret =
+      usesSecret && input.serviceTokenSecret !== undefined && input.serviceTokenSecret.length > 0
+        ? this.secrets.encrypt(input.serviceTokenSecret)
+        : carriedSecret
+
+    return {
+      enabled: input.enabled,
+      hostname: input.hostname,
+      authMethod: input.authMethod,
+      ...(input.serviceTokenId !== undefined && input.serviceTokenId.length > 0
+        ? { serviceTokenId: input.serviceTokenId }
+        : {}),
+      ...(encryptedServiceTokenSecret !== undefined ? { encryptedServiceTokenSecret } : {}),
+      ...(input.binaryPath !== undefined && input.binaryPath.length > 0
+        ? { binaryPath: input.binaryPath }
+        : {})
+    }
+  }
+
   private async load(): Promise<StoredConnection[]> {
     if (this.cache !== null) return [...this.cache]
     try {
@@ -248,18 +291,19 @@ export class ConnectionsRepository {
  * renderer never sees either the placeholder token or any cleartext.
  * The username remains available as its own field; the renderer can
  * reconstruct a display string from `{uri, username, hasStoredPassword}`.
- * The SSH secrets go the same way, down to `hasStored…` flags.
+ * The tunnel secrets go the same way, down to `hasStored…` flags.
  *
  * THIS IS THE ONLY PLACE THIS PROJECTION SHOULD HAPPEN.
  */
 export function toRendererView(stored: StoredConnection): ConnectionConfig {
-  const { encryptedPassword, ssh, ...rest } = stored
+  const { encryptedPassword, ssh, cloudflared, ...rest } = stored
   const parts = parseUri(stored.uri)
   const bareUri = `${parts.schemeWithSep}${parts.hostAndRest}`
   return {
     ...rest,
     uri: bareUri,
     ...(ssh !== undefined ? { ssh: toSshView(ssh) } : {}),
+    ...(cloudflared !== undefined ? { cloudflared: toCloudflaredView(cloudflared) } : {}),
     hasStoredPassword: encryptedPassword !== undefined
   }
 }
@@ -272,3 +316,8 @@ function toSshView(ssh: StoredSshTunnel): SshTunnelView {
     hasStoredPassphrase: encryptedPassphrase !== undefined
   }
 }
+
+function toCloudflaredView(cloudflared: StoredCloudflaredTunnel): CloudflaredTunnelView {
+  const { encryptedServiceTokenSecret, ...rest } = cloudflared
+  return { ...rest, hasStoredServiceTokenSecret: encryptedServiceTokenSecret !== undefined }
+}
diff --git a/src/preload/index.ts b/src/preload/index.ts
index b32fd1b..9f46d5a 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -1,11 +1,18 @@
 import { contextBridge, ipcRenderer } from 'electron'
 import type { Api } from '@shared/api'
-import type { ConnectionDropped, UpdateCheckResult, UpdateProgress } from '@shared/events'
+import type {
+  CloudflaredLoginPrompt,
+  ConnectionDropped,
+  UpdateCheckResult,
+  UpdateProgress
+} from '@shared/events'
 import type { Result } from '@shared/result'
 import type {
   AggregateRequest,
   AggregateResponse,
+  CancelQueryRequest,
   CollectionInfo,
+  CollectionSchema,
   CollectionStats,
   ConnectionConfig,
   ConnectionInput,
@@ -17,16 +24,20 @@ import type {
   CreateIndexPayload,
   CreateUserPayload,
   DatabaseInfo,
+  DatabaseRoleInfo,
   DatabaseUser,
   DeleteManyRequest,
   DeleteManyResponse,
   DeleteOneRequest,
   DeleteOneResponse,
+  DistinctRequest,
+  DistinctResponse,
   DropIndexPayload,
   DropUserPayload,
   FindRequest,
   FindResponse,
   IndexInfo,
+  IndexStatsReport,
   InsertManyRequest,
   InsertManyResponse,
   InsertOneRequest,
@@ -35,7 +46,9 @@ import type {
   ReplaceOneRequest,
   ReplaceOneResponse,
   ServerStats,
-  UpdateUserPayload
+  UpdateUserPayload,
+  WriteRequest,
+  WriteResponse
 } from '@shared/types'
 
 const invoke = <T>(channel: string, payload?: unknown): Promise<Result<T>> =>
@@ -69,8 +82,14 @@ const api: Api = {
     onDropped: (listener: (payload: ConnectionDropped) => void) =>
       subscribe<ConnectionDropped>('connections:dropped', listener)
   },
+  cloudflared: {
+    version: (binaryPath?: string) => invoke<string>('cloudflared:version', { binaryPath }),
+    onLogin: (listener: (prompt: CloudflaredLoginPrompt) => void) =>
+      subscribe<CloudflaredLoginPrompt>('cloudflared:login', listener)
+  },
   dialog: {
-    pickPrivateKey: () => invoke<string | null>('dialog:pickPrivateKey')
+    pickPrivateKey: () => invoke<string | null>('dialog:pickPrivateKey'),
+    pickCloudflared: () => invoke<string | null>('dialog:pickCloudflared')
   },
   databases: {
     list: (connectionId: string) => invoke<DatabaseInfo[]>('databases:list', { connectionId }),
@@ -90,7 +109,9 @@ const api: Api = {
       invoke<void>('collections:create', payload),
     drop: (payload: { connectionId: string; db: string; coll: string }) =>
       invoke<void>('collections:drop', payload),
-    rename: (payload: RenameCollectionPayload) => invoke<void>('collections:rename', payload)
+    rename: (payload: RenameCollectionPayload) => invoke<void>('collections:rename', payload),
+    schema: (payload: { connectionId: string; db: string; coll: string }) =>
+      invoke<CollectionSchema>('collections:schema', payload)
   },
   query: {
     find: (request: FindRequest) => invoke<FindResponse>('query:find', request),
@@ -103,7 +124,10 @@ const api: Api = {
       invoke<InsertManyResponse>('query:insertMany', request),
     deleteOne: (request: DeleteOneRequest) => invoke<DeleteOneResponse>('query:deleteOne', request),
     deleteMany: (request: DeleteManyRequest) =>
-      invoke<DeleteManyResponse>('query:deleteMany', request)
+      invoke<DeleteManyResponse>('query:deleteMany', request),
+    distinct: (request: DistinctRequest) => invoke<DistinctResponse>('query:distinct', request),
+    cancel: (request: CancelQueryRequest) => invoke<void>('query:cancel', request),
+    write: (request: WriteRequest) => invoke<WriteResponse>('query:write', request)
   },
   users: {
     list: (payload: { connectionId: string; db: string }) =>
@@ -112,11 +136,17 @@ const api: Api = {
     update: (payload: UpdateUserPayload) => invoke<void>('users:update', payload),
     drop: (payload: DropUserPayload) => invoke<void>('users:drop', payload)
   },
+  roles: {
+    list: (payload: { connectionId: string; db: string }) =>
+      invoke<DatabaseRoleInfo[]>('roles:list', payload)
+  },
   indexes: {
     list: (payload: { connectionId: string; db: string; coll: string }) =>
       invoke<IndexInfo[]>('indexes:list', payload),
     create: (payload: CreateIndexPayload) => invoke<{ name: string }>('indexes:create', payload),
-    drop: (payload: DropIndexPayload) => invoke<void>('indexes:drop', payload)
+    drop: (payload: DropIndexPayload) => invoke<void>('indexes:drop', payload),
+    stats: (payload: { connectionId: string; db: string; coll: string }) =>
+      invoke<IndexStatsReport>('indexes:stats', payload)
   },
   updater: {
     check: () => invoke<UpdateCheckResult>('updater:check'),
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 4228f75..375c280 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -7,6 +7,7 @@ import { CollectionTab } from '@/features/collection/CollectionTab'
 import { ConnectionDashboard } from '@/features/dashboard/ConnectionDashboard'
 import { ServerStatsCollector } from '@/features/dashboard/ServerStatsCollector'
 import { CommandPalette } from '@/features/palette/CommandPalette'
+import { showCloudflaredLogin } from '@/features/connections/cloudflaredLoginToast'
 import { UpdateNotifier } from '@/features/updater/UpdateNotifier'
 import { Welcome } from '@/features/welcome/Welcome'
 import { useTabsStore } from '@/store/tabs'
@@ -41,7 +42,7 @@ export default function App() {
   const onWelcome = !activeTab && !dashboardConnection
 
   // Main took a connection down without being asked — today that means a dead
-  // SSH tunnel. Subscribed here because the sidebar is not always mounted.
+  // tunnel. Subscribed here because the sidebar is not always mounted.
   // Open tabs are left alone: a drop is usually followed by a reconnect, and
   // discarding the user's queries over a network hiccup would be worse.
   useEffect(() => {
@@ -51,6 +52,9 @@ export default function App() {
     })
   }, [markDisconnected])
 
+  // Sign-ins start from every place that connects, and mid-session once an Access session expires.
+  useEffect(() => api.cloudflared.onLogin(showCloudflaredLogin), [])
+
   return (
     <div className="flex h-full w-full bg-background text-foreground">
       <ServerStatsCollector />
diff --git a/src/renderer/src/components/ui/autocomplete-input.tsx b/src/renderer/src/components/ui/autocomplete-input.tsx
new file mode 100644
index 0000000..8d84076
--- /dev/null
+++ b/src/renderer/src/components/ui/autocomplete-input.tsx
@@ -0,0 +1,122 @@
+import * as React from 'react'
+import { Input, type InputProps } from '@/components/ui/input'
+import { rankSuggestions } from '@/lib/suggestions'
+import { cn } from '@/lib/utils'
+
+type AutocompleteInputProps = Omit<InputProps, 'value' | 'onChange' | 'onFocus' | 'onBlur'> & {
+  value: string
+  onValueChange: (value: string) => void
+  suggestions: readonly string[]
+  /** Layout of the positioning wrapper, e.g. `flex-1` or a fixed width. */
+  wrapperClassName?: string
+}
+
+/** Input with a ranked suggestion list that owns Arrow keys, Tab, Enter and Escape while open. */
+const AutocompleteInput = React.forwardRef<HTMLInputElement, AutocompleteInputProps>(
+  (
+    { value, onValueChange, suggestions, wrapperClassName, className, onKeyDown, ...props },
+    ref
+  ) => {
+    const [open, setOpen] = React.useState(false)
+    const [active, setActive] = React.useState(0)
+    const listId = React.useId()
+    const listRef = React.useRef<HTMLUListElement>(null)
+
+    const matches = React.useMemo(() => rankSuggestions(value, suggestions), [value, suggestions])
+    const visible = open && matches.length > 0
+    const current = active < matches.length ? active : 0
+
+    React.useEffect(() => {
+      setActive(0)
+    }, [value])
+
+    React.useEffect(() => {
+      if (visible) listRef.current?.children[current]?.scrollIntoView({ block: 'nearest' })
+    }, [visible, current])
+
+    const accept = (suggestion: string) => {
+      onValueChange(suggestion)
+      setOpen(false)
+    }
+
+    const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (visible) {
+        if (e.key === 'ArrowDown') {
+          e.preventDefault()
+          setActive((current + 1) % matches.length)
+          return
+        }
+        if (e.key === 'ArrowUp') {
+          e.preventDefault()
+          setActive((current - 1 + matches.length) % matches.length)
+          return
+        }
+        if (e.key === 'Tab' || e.key === 'Enter') {
+          e.preventDefault()
+          accept(matches[current]!)
+          return
+        }
+        if (e.key === 'Escape') {
+          e.preventDefault()
+          setOpen(false)
+          return
+        }
+      }
+      onKeyDown?.(e)
+    }
+
+    return (
+      <div className={cn('relative', wrapperClassName)}>
+        <Input
+          ref={ref}
+          {...props}
+          value={value}
+          onChange={(e) => {
+            onValueChange(e.target.value)
+            setOpen(true)
+          }}
+          onFocus={() => setOpen(true)}
+          onBlur={() => setOpen(false)}
+          onKeyDown={handleKeyDown}
+          className={cn('w-full font-mono', className)}
+          role="combobox"
+          aria-autocomplete="list"
+          aria-expanded={visible}
+          aria-controls={visible ? listId : undefined}
+          aria-activedescendant={visible ? `${listId}-${current}` : undefined}
+          data-consumes-escape={visible ? '' : undefined}
+        />
+        {visible && (
+          <ul
+            ref={listRef}
+            id={listId}
+            className="absolute left-0 right-0 top-full z-50 mt-1 max-h-40 overflow-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md"
+            role="listbox"
+            // Keep focus in the input so onBlur doesn't close the list before an option click registers.
+            onMouseDown={(e) => e.preventDefault()}
+          >
+            {matches.map((s, i) => (
+              <li
+                key={s}
+                id={`${listId}-${i}`}
+                role="option"
+                aria-selected={i === current}
+                onMouseEnter={() => setActive(i)}
+                onClick={() => accept(s)}
+                className={cn(
+                  'cursor-pointer rounded-sm px-2 py-1 font-mono text-xs',
+                  i === current ? 'bg-accent text-accent-foreground' : 'text-foreground'
+                )}
+              >
+                {s}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    )
+  }
+)
+AutocompleteInput.displayName = 'AutocompleteInput'
+
+export { AutocompleteInput }
diff --git a/src/renderer/src/components/ui/dialog.tsx b/src/renderer/src/components/ui/dialog.tsx
index 8d5fa11..848b7e5 100644
--- a/src/renderer/src/components/ui/dialog.tsx
+++ b/src/renderer/src/components/ui/dialog.tsx
@@ -23,28 +23,52 @@ const DialogOverlay = React.forwardRef<
 ))
 DialogOverlay.displayName = DialogPrimitive.Overlay.displayName
 
+const isInside = (target: EventTarget | null, selector: string): boolean =>
+  target instanceof Element && target.closest(selector) !== null
+
+/** Dialog panel; Escape first closes an open Monaco widget or `[data-consumes-escape]` popup inside it. */
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
->(({ className, children, ...props }, ref) => (
-  <DialogPortal>
-    <DialogOverlay />
-    <DialogPrimitive.Content
-      ref={ref}
-      className={cn(
-        'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg',
-        className
-      )}
-      {...props}
-    >
-      {children}
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
-        <X className="h-4 w-4" />
-        <span className="sr-only">Close</span>
-      </DialogPrimitive.Close>
-    </DialogPrimitive.Content>
-  </DialogPortal>
-))
+>(({ className, children, onEscapeKeyDown, onKeyDown, ...props }, ref) => {
+  const closeRef = React.useRef<HTMLButtonElement>(null)
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        ref={ref}
+        className={cn(
+          'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 sm:rounded-lg',
+          className
+        )}
+        onEscapeKeyDown={(event) => {
+          onEscapeKeyDown?.(event)
+          // Radix handles Escape on document in the capture phase, before the focused widget sees it.
+          if (isInside(event.target, '.monaco-editor, [data-consumes-escape]')) {
+            event.preventDefault()
+          }
+        }}
+        onKeyDown={(event) => {
+          onKeyDown?.(event)
+          // Monaco stops propagation of keys it consumes, so an Escape arriving here was left unhandled.
+          if (event.key === 'Escape' && isInside(event.target, '.monaco-editor')) {
+            closeRef.current?.click()
+          }
+        }}
+        {...props}
+      >
+        {children}
+        <DialogPrimitive.Close
+          ref={closeRef}
+          className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none"
+        >
+          <X className="h-4 w-4" />
+          <span className="sr-only">Close</span>
+        </DialogPrimitive.Close>
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  )
+})
 DialogContent.displayName = DialogPrimitive.Content.displayName
 
 const DialogHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
diff --git a/src/renderer/src/components/ui/tooltip.test.ts b/src/renderer/src/components/ui/tooltip.test.ts
new file mode 100644
index 0000000..7b1bc9a
--- /dev/null
+++ b/src/renderer/src/components/ui/tooltip.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { placeTooltip } from './tooltip'
+
+const viewport = { width: 1266, height: 763 }
+// The Run button: 16 px from the right edge, 48 px from the top.
+const runButton = { top: 48, bottom: 80, left: 1186, width: 64 }
+// A three-line explanation at the max-w-sm cap.
+const reason = { width: 384, height: 58 }
+
+describe('placeTooltip', () => {
+  it('stays above the trigger while it fits there', () => {
+    const trigger = { top: 300, bottom: 330, left: 500, width: 100 }
+    expect(placeTooltip(trigger, reason, viewport, 'top')).toEqual({ top: 234, left: 358 })
+  })
+
+  it('moves below the trigger when the tooltip is taller than the room above', () => {
+    expect(placeTooltip(runButton, reason, viewport, 'top').top).toBe(88)
+  })
+
+  it('keeps a wide tooltip next to the right edge inside the window', () => {
+    const { left } = placeTooltip(runButton, reason, viewport, 'top')
+    expect(left).toBe(viewport.width - 8 - reason.width)
+  })
+
+  it('keeps it inside the left edge', () => {
+    const trigger = { top: 300, bottom: 330, left: 0, width: 20 }
+    expect(placeTooltip(trigger, reason, viewport, 'top').left).toBe(8)
+  })
+
+  it('moves above when there is no room below', () => {
+    const trigger = { top: 720, bottom: 750, left: 500, width: 100 }
+    expect(placeTooltip(trigger, reason, viewport, 'bottom').top).toBe(654)
+  })
+})
diff --git a/src/renderer/src/components/ui/tooltip.tsx b/src/renderer/src/components/ui/tooltip.tsx
index 7ccb2b5..840af31 100644
--- a/src/renderer/src/components/ui/tooltip.tsx
+++ b/src/renderer/src/components/ui/tooltip.tsx
@@ -1,9 +1,42 @@
-import { cloneElement, useEffect, useRef, useState, type ReactElement, type Ref } from 'react'
+import {
+  cloneElement,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactElement,
+  type Ref
+} from 'react'
 import { createPortal } from 'react-dom'
 import { cn } from '@/lib/utils'
 
 type Side = 'top' | 'bottom'
 
+type Box = { top: number; left: number }
+
+const GAP = 8
+const EDGE_MARGIN = 8
+
+/**
+ * Places a tooltip of `size` next to `trigger`, on the other side when `side` lacks room.
+ * @returns Viewport coordinates of the tooltip's top-left corner, kept inside the window.
+ */
+export function placeTooltip(
+  trigger: { top: number; bottom: number; left: number; width: number },
+  size: { width: number; height: number },
+  viewport: { width: number; height: number },
+  side: Side
+): Box {
+  const above = trigger.top - GAP - size.height
+  const below = trigger.bottom + GAP
+  const fitsAbove = above >= EDGE_MARGIN
+  const fitsBelow = below + size.height <= viewport.height - EDGE_MARGIN
+  const top = side === 'top' ? (fitsAbove ? above : below) : fitsBelow ? below : above
+  const centered = trigger.left + trigger.width / 2 - size.width / 2
+  const left = Math.max(EDGE_MARGIN, Math.min(centered, viewport.width - EDGE_MARGIN - size.width))
+  return { top, left }
+}
+
 type TriggerProps = {
   ref?: Ref<HTMLElement>
   onMouseEnter?: (e: React.MouseEvent<HTMLElement>) => void
@@ -28,44 +61,35 @@ type Props = {
  * tokens so it doesn't look like the OS-native yellow `title` bubble.
  *
  * Positions via fixed coordinates measured against the trigger's bounding
- * rect; the tooltip itself is rendered into a portal at `document.body`
- * to escape the parent's overflow clipping (relevant for the document
- * table's scroll container).
+ * rect and its own rendered size; the tooltip itself is rendered into a
+ * portal at `document.body` to escape the parent's overflow clipping
+ * (relevant for the document table's scroll container).
  */
 export function Tooltip({ content, children, delay = 350, side = 'top', disabled }: Props) {
   const [open, setOpen] = useState(false)
-  const [box, setBox] = useState<{ top: number; left: number; placement: Side }>({
-    top: 0,
-    left: 0,
-    placement: side
-  })
+  const [box, setBox] = useState<Box>({ top: 0, left: 0 })
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   const triggerRef = useRef<HTMLElement | null>(null)
+  const tooltipRef = useRef<HTMLDivElement | null>(null)
 
-  const measure = (): void => {
-    if (!triggerRef.current) return
-    const rect = triggerRef.current.getBoundingClientRect()
-    const gap = 8
-    let placement: Side = side
-    let top = placement === 'top' ? rect.top - gap : rect.bottom + gap
-    if (placement === 'top' && top < 28) {
-      placement = 'bottom'
-      top = rect.bottom + gap
-    } else if (placement === 'bottom' && top > window.innerHeight - 28) {
-      placement = 'top'
-      top = rect.top - gap
-    }
-    const left = Math.min(Math.max(rect.left + rect.width / 2, 16), window.innerWidth - 16)
-    setBox({ top, left, placement })
-  }
+  // Placement needs the rendered size; a layout effect corrects it before the first paint.
+  useLayoutEffect(() => {
+    const trigger = triggerRef.current
+    const tooltip = tooltipRef.current
+    if (!open || !trigger || !tooltip) return
+    const next = placeTooltip(
+      trigger.getBoundingClientRect(),
+      { width: tooltip.offsetWidth, height: tooltip.offsetHeight },
+      { width: window.innerWidth, height: window.innerHeight },
+      side
+    )
+    setBox((prev) => (prev.top === next.top && prev.left === next.left ? prev : next))
+  }, [open, content, side])
 
   const show = (): void => {
     if (disabled) return
     if (timerRef.current) clearTimeout(timerRef.current)
-    timerRef.current = setTimeout(() => {
-      measure()
-      setOpen(true)
-    }, delay)
+    timerRef.current = setTimeout(() => setOpen(true), delay)
   }
   const hide = (): void => {
     if (timerRef.current) {
@@ -135,16 +159,14 @@ export function Tooltip({ content, children, delay = 350, side = 'top', disabled
         visibleContent &&
         createPortal(
           <div
+            ref={tooltipRef}
             role="tooltip"
             className={cn(
-              'pointer-events-none fixed z-[200] max-w-sm rounded-md border border-border bg-popover px-2 py-1 text-xs leading-snug text-popover-foreground shadow-lg',
+              // w-max: a fixed box otherwise shrinks to the room right of `left` near the edge.
+              'pointer-events-none fixed z-[200] w-max max-w-sm rounded-md border border-border bg-popover px-2 py-1 text-xs leading-snug text-popover-foreground shadow-lg',
               'animate-in fade-in-0 zoom-in-95 duration-100'
             )}
-            style={{
-              top: box.top,
-              left: box.left,
-              transform: box.placement === 'top' ? 'translate(-50%, -100%)' : 'translate(-50%, 0)'
-            }}
+            style={{ top: box.top, left: box.left }}
           >
             {content}
           </div>,
diff --git a/src/renderer/src/features/collection/CollectionTab.tsx b/src/renderer/src/features/collection/CollectionTab.tsx
index 82ce6a9..291813c 100644
--- a/src/renderer/src/features/collection/CollectionTab.tsx
+++ b/src/renderer/src/features/collection/CollectionTab.tsx
@@ -1,22 +1,110 @@
-import { useMemo } from 'react'
-import { useQuery, useQueryClient } from '@tanstack/react-query'
-import { ServerCrash } from 'lucide-react'
+import { useMemo, useState } from 'react'
+import {
+  hashKey,
+  isCancelledError,
+  useMutation,
+  useMutationState,
+  useQuery,
+  useQueryClient,
+  type MutationState,
+  type QueryKey,
+  type UseQueryResult
+} from '@tanstack/react-query'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle
+} from '@/components/ui/alert-dialog'
+import { compilePipelineSource } from '@/lib/aggregationPipeline'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
-import { parseMongoQuery } from '@/lib/mongoQueryLang'
-import { parseShellCommand } from '@/lib/shellParser'
+import { useCompletionEnv } from '@/lib/completion/useCompletionEnv'
+import { cancelRequests } from '@/lib/queryCancellation'
+import {
+  explicitRunOptions,
+  mutationKeys,
+  queryKeys,
+  runQueryOptions,
+  shellWriteOptions,
+  simpleRunOptions,
+  type RunnableQuery,
+  type ShellWriteVariables
+} from '@/lib/queryClient'
+import {
+  compileFind,
+  runAggregation,
+  runFind,
+  runShellCommand,
+  type QueryResult,
+  type ShellWriteCommand,
+  type ShellWriteResult
+} from '@/lib/queryRun'
+import { parseShellCommand, writeConfirmation } from '@/lib/shellParser'
 import {
   useTabsStore,
-  type CollectionTab as CollectionTabType,
-  type QueryPatch
+  type AppliedSimple,
+  type AppliedSource,
+  type CollectionTab as CollectionTabType
 } from '@/store/tabs'
+import type { CollectionRef, UuidEncoding } from '@shared/types'
 import { QueryToolbar } from './QueryToolbar'
 import { DocumentTable } from './DocumentTable'
-import { StatusBar } from './StatusBar'
-import type { FindResponse, UuidEncoding } from '@shared/types'
+import {
+  CancelledState,
+  CountResult,
+  ErrorState,
+  IdleState,
+  LoadingState,
+  WriteResult
+} from './ResultStates'
+import { StatusBar, type StatusSummary } from './StatusBar'
+
+type DocumentsResult = Extract<QueryResult, { kind: 'documents' }>
+
+type ShellWriteState = MutationState<ShellWriteResult, Error, ShellWriteVariables>
+
+/** What the view reads of a shell write: the run it belongs to and its outcome. */
+type ShownWrite = Pick<ShellWriteState, 'status' | 'data' | 'error'> &
+  Partial<Pick<ShellWriteVariables, 'tabId' | 'epoch'>>
+
+/** A write waiting for the user to confirm it. */
+type PendingWrite = { tabId: string; reason: string }
+
+/** The visible mode's applied query: never run, not compilable, ready with its result key, or a write. */
+type ResultRun =
+  | { kind: 'idle'; mode: 'aggregation' | 'shell' }
+  | { kind: 'invalid'; error: string }
+  | ({ kind: 'ready' } & RunnableQuery<QueryResult>)
+  // Run executes it once as a mutation; it has no query, so no refetch or invalidation repeats it.
+  | { kind: 'write'; epoch: number }
+
+const runnable = (run: ResultRun | null): RunnableQuery<QueryResult> | null =>
+  run?.kind === 'ready' ? run : null
+
+const isCancelled = (error: unknown): boolean =>
+  isCancelledError(error) || (error instanceof ApiError && error.code === 'cancelled')
+
+const EMPTY_MESSAGES: Record<DocumentsResult['origin'], string> = {
+  find: 'No documents match the current filter.',
+  aggregate: 'The pipeline returned no documents.',
+  distinct: 'No values found.'
+}
+
+const TRUNCATION_HINTS: Record<DocumentsResult['origin'], string> = {
+  find: 'Use .skip() / .limit() to page through the rest.',
+  aggregate: 'Add $skip / $limit stages to page through the rest.',
+  distinct: 'Narrow the filter to see the remaining values.'
+}
 
 export function CollectionTab({ tab }: { tab: CollectionTabType }) {
-  const setQuery = useTabsStore((s) => s.setQuery)
+  // Only the mode: the rest of the draft changes on every keystroke and never affects results.
+  const mode = useTabsStore((s) => s.drafts[tab.id]?.mode ?? 'simple')
+  const setSkip = useTabsStore((s) => s.setSkip)
+  const commitRun = useTabsStore((s) => s.run)
   const queryClient = useQueryClient()
 
   const connectionsQuery = useQuery({
@@ -27,277 +115,377 @@ export function CollectionTab({ tab }: { tab: CollectionTabType }) {
   const uuidEncoding: UuidEncoding = connectionConfig?.uuidEncoding ?? 'default'
   const timezone = connectionConfig?.timezone ?? 'UTC'
 
-  // Compile all three modes' inputs up-front; the active query just picks
-  // its slice. parseMongoQuery rejects anything that isn't valid mongo
-  // shell syntax (with our $-operator extensions).
-  const compiled = useMemo(() => {
-    if (tab.mode === 'simple') {
-      const f = parseMongoQuery(tab.filter)
-      const p = parseMongoQuery(tab.projection)
-      const s = parseMongoQuery(tab.sort)
-      const ok = f.ok && p.ok && s.ok
-      return {
-        mode: 'simple' as const,
-        ok,
-        filter: f.ok ? f.ejson : null,
-        projection: p.ok ? p.ejson : null,
-        sort: s.ok ? s.ejson : null,
-        error:
-          (!f.ok && `Filter: ${f.error}`) ||
-          (!p.ok && `Projection: ${p.error}`) ||
-          (!s.ok && `Sort: ${s.error}`) ||
-          null
-      }
-    }
-    if (tab.mode === 'aggregation') {
-      const r = parseMongoQuery(tab.pipeline)
-      if (!r.ok) {
-        return { mode: 'aggregation' as const, ok: false, pipeline: null, error: r.error }
-      }
-      if (!Array.isArray(r.value)) {
-        return {
-          mode: 'aggregation' as const,
-          ok: false,
-          pipeline: null,
-          error: 'Pipeline must be an array'
-        }
-      }
-      return { mode: 'aggregation' as const, ok: true, pipeline: r.ejson, error: null }
-    }
-    // shell
-    const r = parseShellCommand(tab.shell)
-    if (!r.ok) {
-      return { mode: 'shell' as const, ok: false, parsed: null, error: r.error }
-    }
-    if (r.coll !== tab.coll) {
-      return {
-        mode: 'shell' as const,
-        ok: false,
-        parsed: null,
-        error: `Command targets "${r.coll}" but this tab is "${tab.coll}"`
-      }
-    }
-    return { mode: 'shell' as const, ok: true, parsed: r, error: null }
-  }, [tab.mode, tab.filter, tab.projection, tab.sort, tab.pipeline, tab.shell, tab.coll])
+  const { id, connectionId, db, coll, applied } = tab
+  const simple = applied.simple
+  const appliedSource =
+    mode === 'aggregation' ? applied.aggregation : mode === 'shell' ? applied.shell : null
+  const compiledFind = useMemo(() => compileFind(simple), [simple])
+  const findRun = useMemo(
+    () => simpleRun({ connectionId, db, coll }, simple, compiledFind),
+    [connectionId, db, coll, simple, compiledFind]
+  )
+  const sourceRun = useMemo(
+    () =>
+      mode === 'simple' ? null : explicitRun(id, { connectionId, db, coll }, mode, appliedSource),
+    [id, connectionId, db, coll, mode, appliedSource]
+  )
 
-  const findQuery = useQuery({
-    queryKey:
-      compiled.mode === 'simple'
-        ? queryKeys.find(
-            tab.connectionId,
-            tab.db,
-            tab.coll,
-            tab.filter,
-            tab.projection,
-            tab.sort,
-            tab.skip,
-            tab.limit,
-            tab.runEpoch
-          )
-        : compiled.mode === 'aggregation'
-          ? queryKeys.aggregate(tab.connectionId, tab.db, tab.coll, tab.pipeline, tab.runEpoch)
-          : queryKeys.shell(tab.connectionId, tab.db, tab.coll, tab.shell, tab.runEpoch),
-    queryFn: () => runForMode(tab, compiled),
-    enabled: compiled.ok,
-    // Don't auto-refetch when the user just switches between tabs; the
-    // query only re-runs when its key changes (filter / mode / runEpoch).
-    refetchOnMount: false,
-    staleTime: Infinity
-  })
+  // Observed in every mode so a mode switch shows the kept result without re-running it.
+  const findQuery = useQuery(
+    runQueryOptions(id, runnable(findRun), simpleRunOptions, mode === 'simple')
+  )
+  const sourceQuery = useQuery(runQueryOptions(id, runnable(sourceRun), explicitRunOptions))
+  const run = sourceRun ?? findRun
+  const resultQuery = sourceRun ? sourceQuery : findQuery
 
-  // Count is only meaningful for the simple mode — aggregation/shell show
-  // the result size in the StatusBar instead.
-  const countQuery = useQuery({
-    queryKey: queryKeys.count(tab.connectionId, tab.db, tab.coll, tab.filter),
-    queryFn: () =>
-      api.query.count({
-        connectionId: tab.connectionId,
-        db: tab.db,
-        coll: tab.coll,
-        ...(compiled.mode === 'simple' && compiled.filter ? { filter: compiled.filter } : {})
-      }),
-    enabled: compiled.mode === 'simple' && compiled.ok
+  const writeMutation = useMutation(shellWriteOptions(queryClient))
+  // Filtered while rendering: useMutationState applies changed filters only on its next cache event.
+  const writeStates = useMutationState({
+    filters: { mutationKey: mutationKeys.shellWrite },
+    select: (mutation): ShownWrite => {
+      const { variables, status, data, error } = mutation.state as ShellWriteState
+      return { tabId: variables?.tabId, epoch: variables?.epoch, status, data, error }
+    }
   })
+  const writeState =
+    run.kind === 'write'
+      ? writeStates.find((write) => write.tabId === id && write.epoch === run.epoch)
+      : undefined
+  const writing = writeState?.status === 'pending'
 
-  const apply = (patch: QueryPatch) => setQuery(tab.id, patch)
+  const [confirming, setConfirming] = useState<PendingWrite | null>(null)
+  // One view serves every tab; a confirmation belongs to the tab that asked for it.
+  if (confirming !== null && confirming.tabId !== id) setConfirming(null)
+
+  const runWrite = () => {
+    // Committing first gives the write its run's epoch, which releases the tab's previous write.
+    const committed = commitRun(id)
+    if (committed === null || !('source' in committed)) return
+    // Parsed from the committed source, so the write is exactly the run the tab records and shows.
+    const parsed = parseShellCommand(committed.source)
+    if (!parsed.ok) return
+    const { command } = parsed
+    if (command.op.kind !== 'write') return
+    writeMutation.mutate({
+      tabId: id,
+      epoch: committed.epoch,
+      target: { connectionId, db },
+      command: { coll: command.coll, op: command.op }
+    })
+  }
+
+  const requestWrite = (command: ShellWriteCommand) => {
+    const reason = writeConfirmation(command, db)
+    if (reason === null) runWrite()
+    else setConfirming({ tabId: id, reason })
+  }
+
+  const countKey = queryKeys.count(connectionId, db, coll, simple.filter, simple.epoch)
+  const countQuery = useQuery(
+    runQueryOptions(
+      id,
+      compiledFind.ok
+        ? {
+            key: countKey,
+            execute: (requestId) =>
+              api.query.count({
+                connectionId,
+                db,
+                coll,
+                ...(compiledFind.find.filter ? { filter: compiledFind.find.filter } : {}),
+                requestId
+              })
+          }
+        : null,
+      simpleRunOptions,
+      // Only Simple mode pages, so only it needs the total.
+      mode === 'simple'
+    )
+  )
 
   const cancel = () => {
-    // Soft cancel via react-query: the IPC promise still settles in main
-    // but its result is discarded, so the UI returns to its previous state
-    // immediately. No queryFn signal plumbing needed.
-    const key =
-      tab.mode === 'simple'
-        ? queryKeys.find(
-            tab.connectionId,
-            tab.db,
-            tab.coll,
-            tab.filter,
-            tab.projection,
-            tab.sort,
-            tab.skip,
-            tab.limit,
-            tab.runEpoch
-          )
-        : tab.mode === 'aggregation'
-          ? queryKeys.aggregate(tab.connectionId, tab.db, tab.coll, tab.pipeline, tab.runEpoch)
-          : queryKeys.shell(tab.connectionId, tab.db, tab.coll, tab.shell, tab.runEpoch)
-    void queryClient.cancelQueries({ queryKey: key })
+    const keys: QueryKey[] = run.kind === 'ready' ? [run.key] : []
+    if (mode === 'simple') keys.push(countKey)
+    for (const key of keys) {
+      const hash = hashKey(key)
+      cancelRequests((k) => hashKey(k) === hash)
+      // Kept as a failure instead of reverting, so the cancelled run is never re-executed implicitly.
+      void queryClient.cancelQueries({ queryKey: key, exact: true }, { revert: false })
+    }
   }
 
-  const documents = findQuery.data?.documents ?? []
-  const tookMs = findQuery.data?.tookMs
+  const result = resultQuery.data
+  const completionEnv = useCompletionEnv({
+    connectionId,
+    db,
+    coll,
+    uuidEncoding,
+    timezone,
+    // Projected, derived or other collections' rows would teach the schema fields `coll` does not store.
+    documents:
+      result?.kind === 'documents' && result.rowAccess === 'full' && result.coll === coll
+        ? result.documents
+        : undefined
+  })
+  const loading = resultQuery.isFetching
+  // A slow count shows as running but never blocks Run.
+  const countLoading = mode === 'simple' && countQuery.isFetching
+  const summary: StatusSummary =
+    mode === 'simple'
+      ? {
+          kind: 'paged',
+          count: countQuery.data?.count,
+          countError:
+            countQuery.error && !isCancelled(countQuery.error) ? countQuery.error.message : null,
+          estimated: countQuery.data?.estimated ?? false,
+          pageSize: simple.limit,
+          skip: simple.skip,
+          pageDocs: result?.kind === 'documents' ? result.documents.length : 0,
+          busy: findQuery.isFetching,
+          onJump: (skip) => setSkip(id, skip)
+        }
+      : result?.kind === 'documents'
+        ? rowsSummary(result, coll)
+        : { kind: 'none' }
 
   return (
     <section className="flex h-full flex-col">
       <QueryToolbar
         tab={tab}
-        onApply={apply}
         onCancel={cancel}
-        loading={findQuery.isFetching}
-        documents={documents}
+        onRunWrite={requestWrite}
+        loading={loading}
+        writing={writing}
+        completionEnv={completionEnv}
         uuidEncoding={uuidEncoding}
         timezone={timezone}
-        compiledFilter={compiled.mode === 'simple' ? compiled.filter : null}
-        compiledProjection={compiled.mode === 'simple' ? compiled.projection : null}
-        compiledSort={compiled.mode === 'simple' ? compiled.sort : null}
+        exportFind={compiledFind.ok ? compiledFind.find : null}
+        exportDocCount={
+          mode === 'simple' && result?.kind === 'documents' ? result.documents.length : 0
+        }
       />
 
       <StatusBar
-        loading={findQuery.isFetching || countQuery.isFetching}
-        count={
-          compiled.mode === 'simple' ? countQuery.data?.count : findQuery.data?.documents.length
-        }
-        estimated={compiled.mode === 'simple' ? (countQuery.data?.estimated ?? false) : false}
-        pageSize={compiled.mode === 'simple' ? tab.limit : 0}
-        skip={tab.skip}
-        pageDocs={documents.length}
-        tookMs={tookMs}
-        onJump={(skip) => setQuery(tab.id, { skip })}
+        loading={loading || countLoading || writing}
+        tookMs={run.kind === 'write' ? writeState?.data?.tookMs : result?.tookMs}
+        summary={summary}
       />
 
       <div className="relative flex-1 overflow-hidden">
-        {compiled.error ? (
-          <ErrorState message={compiled.error} />
-        ) : findQuery.error instanceof ApiError ? (
-          <ErrorState message={findQuery.error.message} />
-        ) : (
-          <DocumentTable
-            documents={documents}
-            loading={findQuery.isFetching}
-            connectionId={tab.connectionId}
-            db={tab.db}
-            coll={tab.coll}
-            uuidEncoding={uuidEncoding}
-            timezone={timezone}
-          />
-        )}
+        <ResultView
+          run={run}
+          query={resultQuery}
+          write={writeState}
+          tab={tab}
+          uuidEncoding={uuidEncoding}
+          timezone={timezone}
+        />
       </div>
+
+      <AlertDialog
+        open={confirming !== null}
+        onOpenChange={(open) => {
+          if (!open) setConfirming(null)
+        }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Run this write?</AlertDialogTitle>
+            <AlertDialogDescription>
+              {confirming?.reason} A write can&apos;t be cancelled once it runs.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+              // The closing dialog still takes a second click or Enter; only the first one confirms.
+              onClick={() => {
+                if (confirming !== null) runWrite()
+              }}
+            >
+              Run write
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </section>
   )
 }
 
-type Compiled =
-  | {
-      mode: 'simple'
-      ok: boolean
-      filter: string | null
-      projection: string | null
-      sort: string | null
-      error: string | null
-    }
-  | { mode: 'aggregation'; ok: boolean; pipeline: string | null; error: string | null }
-  | {
-      mode: 'shell'
-      ok: boolean
-      parsed: (ReturnType<typeof parseShellCommand> & { ok: true }) | null
-      error: string | null
-    }
-
-async function runForMode(tab: CollectionTabType, compiled: Compiled): Promise<FindResponse> {
-  if (compiled.mode === 'simple') {
-    return api.query.find({
-      connectionId: tab.connectionId,
-      db: tab.db,
-      coll: tab.coll,
-      ...(compiled.filter ? { filter: compiled.filter } : {}),
-      ...(compiled.projection ? { projection: compiled.projection } : {}),
-      ...(compiled.sort ? { sort: compiled.sort } : {}),
-      skip: tab.skip,
-      ...(tab.limit > 0 ? { limit: tab.limit } : {})
-    })
-  }
-  if (compiled.mode === 'aggregation') {
-    if (!compiled.pipeline) throw new Error('unreachable: aggregation enabled without pipeline')
-    return api.query.aggregate({
-      connectionId: tab.connectionId,
-      db: tab.db,
-      coll: tab.coll,
-      pipeline: compiled.pipeline
-    })
+function ResultView({
+  run,
+  query,
+  write,
+  tab,
+  uuidEncoding,
+  timezone
+}: {
+  run: ResultRun
+  query: Pick<UseQueryResult<QueryResult>, 'data' | 'error' | 'fetchStatus'>
+  write: ShownWrite | undefined
+  tab: CollectionTabType
+  uuidEncoding: UuidEncoding
+  timezone: string
+}) {
+  const { id, connectionId, db, coll } = tab
+  if (run.kind === 'idle') return <IdleState mode={run.mode} coll={coll} db={db} />
+  if (run.kind === 'invalid') return <ErrorState message={run.error} />
+  if (run.kind === 'write') {
+    return (
+      <ShellWriteView
+        state={write}
+        tabId={id}
+        connectionId={connectionId}
+        db={db}
+        coll={coll}
+        uuidEncoding={uuidEncoding}
+        timezone={timezone}
+      />
+    )
   }
-  // shell
-  if (!compiled.parsed || !compiled.parsed.ok)
-    throw new Error('unreachable: shell enabled without parsed command')
-  const op = compiled.parsed.op
-  if (op.kind === 'aggregate') {
-    return api.query.aggregate({
-      connectionId: tab.connectionId,
-      db: tab.db,
-      coll: tab.coll,
-      pipeline: op.pipeline
-    })
+  const { data: result, error } = query
+  if (isCancelled(error)) return <CancelledState />
+  if (error) return <ErrorState message={error.message} />
+  if (!result) return query.fetchStatus === 'idle' ? <CancelledState /> : <LoadingState />
+  if (result.kind === 'count') {
+    return (
+      <CountResult
+        count={result.count}
+        estimated={result.estimated}
+        method={result.method}
+        coll={result.coll}
+      />
+    )
   }
-  if (op.kind === 'find') {
-    return api.query.find({
-      connectionId: tab.connectionId,
-      db: tab.db,
-      coll: tab.coll,
-      filter: op.filter,
-      ...(op.projection ? { projection: op.projection } : {}),
-      ...(op.sort ? { sort: op.sort } : {}),
-      skip: op.skip ?? 0,
-      ...(op.limit !== null ? { limit: op.limit } : {})
-    })
+  return (
+    <DocumentTable
+      // Selection, lookup target and column widths belong to one tab's view of one collection.
+      key={`${id}:${result.coll}`}
+      documents={result.documents}
+      connectionId={connectionId}
+      db={db}
+      coll={result.coll}
+      rowAccess={result.rowAccess}
+      emptyMessage={EMPTY_MESSAGES[result.origin]}
+      uuidEncoding={uuidEncoding}
+      timezone={timezone}
+    />
+  )
+}
+
+function ShellWriteView({
+  state,
+  tabId,
+  connectionId,
+  db,
+  coll,
+  uuidEncoding,
+  timezone
+}: {
+  state: ShownWrite | undefined
+  tabId: string
+  connectionId: string
+  db: string
+  coll: string
+  uuidEncoding: UuidEncoding
+  timezone: string
+}) {
+  const returned = state?.data?.returned
+  const documents = useMemo(() => (returned?.document ? [returned.document] : []), [returned])
+  if (!state) return <IdleState mode="shell" coll={coll} db={db} />
+  if (state.error) return <ErrorState title="Write failed" message={state.error.message} />
+  if (!state.data) return <LoadingState label="Writing…" />
+  const { writes } = state.data
+  return (
+    <WriteResult result={state.data} db={db} uuidEncoding={uuidEncoding} timezone={timezone}>
+      {returned && (
+        <DocumentTable
+          key={`${tabId}:${writes.coll}`}
+          documents={documents}
+          connectionId={connectionId}
+          db={writes.db}
+          coll={writes.coll}
+          rowAccess={returned.rowAccess}
+          emptyMessage="No document matched."
+          uuidEncoding={uuidEncoding}
+          timezone={timezone}
+        />
+      )}
+    </WriteResult>
+  )
+}
+
+function simpleRun(
+  ref: CollectionRef,
+  simple: AppliedSimple,
+  compiled: ReturnType<typeof compileFind>
+): ResultRun {
+  if (!compiled.ok) return { kind: 'invalid', error: compiled.error }
+  const { find } = compiled
+  return {
+    kind: 'ready',
+    key: queryKeys.find(
+      ref.connectionId,
+      ref.db,
+      ref.coll,
+      simple.filter,
+      simple.projection,
+      simple.sort,
+      simple.skip,
+      simple.limit,
+      simple.epoch
+    ),
+    execute: (requestId) => runFind(ref, find, requestId)
   }
-  if (op.kind === 'findOne') {
-    return api.query.find({
-      connectionId: tab.connectionId,
-      db: tab.db,
-      coll: tab.coll,
-      filter: op.filter,
-      skip: 0,
-      limit: 1
-    })
+}
+
+function explicitRun(
+  tabId: string,
+  ref: CollectionRef,
+  mode: 'aggregation' | 'shell',
+  applied: AppliedSource | null
+): ResultRun {
+  if (applied === null || applied.source.trim() === '') return { kind: 'idle', mode }
+  if (mode === 'aggregation') {
+    const compiled = compilePipelineSource(applied.source)
+    if (!compiled.ok) return { kind: 'invalid', error: compiled.error }
+    return {
+      kind: 'ready',
+      key: queryKeys.aggregate(
+        tabId,
+        ref.connectionId,
+        ref.db,
+        ref.coll,
+        applied.source,
+        applied.epoch
+      ),
+      execute: (requestId) => runAggregation(ref, compiled, requestId)
+    }
   }
-  // countDocuments — return an empty docs response; the count shows in the
-  // StatusBar via a one-off api.query.count call below.
-  const countResp = await api.query.count({
-    connectionId: tab.connectionId,
-    db: tab.db,
-    coll: tab.coll,
-    filter: op.filter
-  })
+  const parsed = parseShellCommand(applied.source)
+  if (!parsed.ok) return { kind: 'invalid', error: parsed.error }
+  const { coll, op } = parsed.command
+  if (op.kind === 'write') return { kind: 'write', epoch: applied.epoch }
   return {
-    documents: [
-      {
-        id: '"_count"',
-        data: { _count: countResp.count },
-        canonical: `{"_count":${countResp.count}}`,
-        hash: 'a'.repeat(64)
-      }
-    ],
-    tookMs: 0
+    kind: 'ready',
+    key: queryKeys.shell(tabId, ref.connectionId, ref.db, applied.source, applied.epoch),
+    execute: (requestId) => runShellCommand(ref, { coll, op }, requestId)
   }
 }
 
-function ErrorState({ message }: { message: string }) {
-  return (
-    <div className="m-6 flex items-start gap-3 rounded-md border border-destructive/30 bg-destructive/5 p-4 text-sm text-destructive">
-      <ServerCrash className="mt-0.5 h-4 w-4" />
-      <div>
-        <div className="font-medium">Query failed</div>
-        <div className="text-xs opacity-80">{message}</div>
-      </div>
-    </div>
-  )
+function rowsSummary(result: DocumentsResult, tabColl: string): StatusSummary {
+  return {
+    kind: 'rows',
+    rows: result.documents.length,
+    truncated: result.truncated,
+    truncationHint: TRUNCATION_HINTS[result.origin],
+    readOnlyReason:
+      result.rowAccess !== 'none'
+        ? null
+        : result.origin === 'distinct'
+          ? "Distinct values aren't documents."
+          : `Pipeline output isn't 1:1 documents of ${result.coll}, so rows can't be edited or deleted.`,
+    foreignColl: result.coll === tabColl ? null : result.coll
+  }
 }
diff --git a/src/renderer/src/features/collection/DocumentTable.tsx b/src/renderer/src/features/collection/DocumentTable.tsx
index b1e22f3..1e9289c 100644
--- a/src/renderer/src/features/collection/DocumentTable.tsx
+++ b/src/renderer/src/features/collection/DocumentTable.tsx
@@ -13,7 +13,8 @@ import {
   ContextMenuSubTrigger,
   ContextMenuTrigger
 } from '@/components/ui/context-menu'
-import { queryKeys } from '@/lib/queryClient'
+import { invalidateWrittenCollection, queryKeys } from '@/lib/queryClient'
+import type { RowAccess } from '@/lib/queryRun'
 import { useTabsStore } from '@/store/tabs'
 import {
   AlertDialog,
@@ -30,6 +31,7 @@ import { api, ApiError } from '@/lib/api'
 import { extractColumns, inspectBson, kindBadgeClass, kindLabel } from '@/lib/bsonDisplay'
 import { cn } from '@/lib/utils'
 import type { DocumentEnvelope, UuidEncoding } from '@shared/types'
+import { Notice } from './ResultStates'
 
 const MAX_CELL_CHARS = 80
 const COL_MIN_WIDTH = 72
@@ -47,23 +49,31 @@ type RowMenuState = {
   envelope: DocumentEnvelope | null
 }
 
+/** A row with an `_id`, so it can address its stored document. */
+type StoredEnvelope = DocumentEnvelope & { id: string }
+
+const hasId = (doc: DocumentEnvelope): doc is StoredEnvelope => doc.id !== null
+
 type PendingDelete =
-  { kind: 'one'; envelope: DocumentEnvelope } | { kind: 'many'; ids: string[] } | null
+  { kind: 'one'; envelope: StoredEnvelope } | { kind: 'many'; ids: string[] } | null
 
 export function DocumentTable({
   documents,
-  loading,
   connectionId,
   db,
   coll,
+  rowAccess,
+  emptyMessage,
   uuidEncoding,
   timezone
 }: {
   documents: DocumentEnvelope[]
-  loading: boolean
   connectionId: string
   db: string
+  /** Collection the rows belong to; every write targets it. */
   coll: string
+  rowAccess: RowAccess
+  emptyMessage: string
   uuidEncoding: UuidEncoding
   timezone: string
 }) {
@@ -71,11 +81,12 @@ export function DocumentTable({
   const [editorState, setEditorState] = useState<RowMenuState>({ mode: null, envelope: null })
   const [pendingDelete, setPendingDelete] = useState<PendingDelete>(null)
   const [selected, setSelected] = useState<Set<string>>(() => new Set())
-  const [activeLookup, setActiveLookup] = useState<{ docId: string; ref: ExtractedRef } | null>(
+  const [activeLookup, setActiveLookup] = useState<{ rowKey: string; ref: ExtractedRef } | null>(
     null
   )
   const lastClickedIdRef = useRef<string | null>(null)
-  const openTab = useTabsStore((s) => s.open)
+  const openWithFilter = useTabsStore((s) => s.openWithFilter)
+  const rowsWritable = rowAccess !== 'none'
 
   // Prefetched in the background as soon as the table mounts so the
   // ObjectId-lookup submenu (right-click on an ObjectId cell) doesn't have to
@@ -90,12 +101,6 @@ export function DocumentTable({
   /** User-set widths; auto-estimated widths fill in for the rest. */
   const [userColumnWidths, setUserColumnWidths] = useState<Record<string, number>>({})
 
-  // Reset manual widths when the *coll* changes — different schema means
-  // different "natural" widths. Filter/sort within the same coll keeps them.
-  useEffect(() => {
-    setUserColumnWidths({})
-  }, [connectionId, db, coll])
-
   const autoColumnWidths = useMemo(() => {
     const widths: Record<string, number> = {}
     for (const col of columns) {
@@ -144,7 +149,7 @@ export function DocumentTable({
   // Drop selections that no longer correspond to any visible document
   // (e.g. after a query change or pagination).
   useEffect(() => {
-    const visible = new Set(documents.map((d) => d.id))
+    const visible = new Set(rowsWritable ? documents.map((d) => d.id) : [])
     setSelected((prev) => {
       let changed = false
       const next = new Set<string>()
@@ -154,10 +159,10 @@ export function DocumentTable({
       }
       return changed ? next : prev
     })
-  }, [documents])
+  }, [documents, rowsWritable])
 
   const deleteOneMutation = useMutation({
-    mutationFn: (env: DocumentEnvelope) =>
+    mutationFn: (env: StoredEnvelope) =>
       api.query.deleteOne({
         connectionId,
         db,
@@ -168,8 +173,7 @@ export function DocumentTable({
     onSuccess: (result) => {
       if (result.deletedCount > 0) {
         toast.success('Document deleted')
-        void queryClient.invalidateQueries({ queryKey: ['find'] })
-        void queryClient.invalidateQueries({ queryKey: ['count'] })
+        void invalidateWrittenCollection(queryClient, { connectionId, db, coll })
       } else {
         toast.warning('Document was already gone')
       }
@@ -188,8 +192,7 @@ export function DocumentTable({
       toast.success(
         `Deleted ${result.deletedCount} document${result.deletedCount === 1 ? '' : 's'}`
       )
-      void queryClient.invalidateQueries({ queryKey: ['find'] })
-      void queryClient.invalidateQueries({ queryKey: ['count'] })
+      void invalidateWrittenCollection(queryClient, { connectionId, db, coll })
       setSelected(new Set())
       setPendingDelete(null)
     },
@@ -213,6 +216,24 @@ export function DocumentTable({
     }
   }
 
+  // Partial rows can't be written back and their hash never matches; act on the stored document.
+  const withStoredDocument = (doc: StoredEnvelope, act: (stored: StoredEnvelope) => void) => {
+    if (rowAccess === 'full') {
+      act(doc)
+      return
+    }
+    void api.query
+      .find({ connectionId, db, coll, filter: `{"_id":${doc.id}}`, skip: 0, limit: 1 })
+      .then(({ documents: [stored] }) => {
+        if (stored && hasId(stored)) act(stored)
+        else toast.error('Document not found')
+      })
+      .catch((e: unknown) => {
+        const message = e instanceof ApiError ? e.message : String(e)
+        toast.error(`Loading the document failed: ${message}`)
+      })
+  }
+
   /**
    * All checkbox interactions go through this single onClick handler.
    *
@@ -243,7 +264,8 @@ export function DocumentTable({
     setSelected((prev) => {
       const next = new Set(prev)
       for (let i = lo; i <= hi; i++) {
-        const docId = indices[i]!
+        const docId = indices[i]
+        if (!docId) continue
         if (targetSelected) next.add(docId)
         else next.delete(docId)
       }
@@ -293,17 +315,19 @@ export function DocumentTable({
     // No modifier: leave selection alone (user is just reading a cell).
   }
 
-  const allVisibleSelected = documents.length > 0 && documents.every((d) => selected.has(d.id))
-  const someVisibleSelected = !allVisibleSelected && documents.some((d) => selected.has(d.id))
+  const selectableIds = rowsWritable ? documents.filter(hasId).map((d) => d.id) : []
+  const allVisibleSelected =
+    selectableIds.length > 0 && selectableIds.every((id) => selected.has(id))
+  const someVisibleSelected = !allVisibleSelected && selectableIds.some((id) => selected.has(id))
   const toggleSelectAllVisible = () => {
     setSelected((prev) => {
       if (allVisibleSelected) {
         const next = new Set(prev)
-        for (const d of documents) next.delete(d.id)
+        for (const id of selectableIds) next.delete(id)
         return next
       }
       const next = new Set(prev)
-      for (const d of documents) next.add(d.id)
+      for (const id of selectableIds) next.add(id)
       return next
     })
     lastClickedIdRef.current = null
@@ -314,27 +338,14 @@ export function DocumentTable({
     lastClickedIdRef.current = null
   }
 
-  if (documents.length === 0) {
-    return (
-      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
-        {loading ? (
-          <span className="flex items-center gap-2">
-            <Loader2 className="h-4 w-4 animate-spin" />
-            Loading…
-          </span>
-        ) : (
-          'No documents match the current filter.'
-        )}
-      </div>
-    )
-  }
+  if (documents.length === 0) return <Notice>{emptyMessage}</Notice>
 
   const selectionCount = selected.size
 
   return (
     <>
       <div className="flex h-full flex-col">
-        {selectionCount > 0 && (
+        {rowsWritable && selectionCount > 0 && (
           <SelectionBar
             count={selectionCount}
             onClear={clearSelection}
@@ -348,21 +359,25 @@ export function DocumentTable({
             style={{ tableLayout: 'fixed' }}
           >
             <colgroup>
-              <col style={{ width: CHECKBOX_COL_WIDTH }} />
+              {rowsWritable && <col style={{ width: CHECKBOX_COL_WIDTH }} />}
               {columns.map((col) => (
                 <col key={col} style={{ width: getColWidth(col) }} />
               ))}
             </colgroup>
             <thead className="sticky top-0 z-10 bg-card/80 backdrop-blur">
               <tr>
-                <th className="border-b border-r border-border/60 px-2 py-2 text-center">
-                  <Checkbox
-                    checked={allVisibleSelected}
-                    indeterminate={someVisibleSelected}
-                    onClick={() => toggleSelectAllVisible()}
-                    aria-label={allVisibleSelected ? 'Deselect all visible' : 'Select all visible'}
-                  />
-                </th>
+                {rowsWritable && (
+                  <th className="border-b border-r border-border/60 px-2 py-2 text-center">
+                    <Checkbox
+                      checked={allVisibleSelected}
+                      indeterminate={someVisibleSelected}
+                      onClick={() => toggleSelectAllVisible()}
+                      aria-label={
+                        allVisibleSelected ? 'Deselect all visible' : 'Select all visible'
+                      }
+                    />
+                  </th>
+                )}
                 {columns.map((col) => (
                   <th
                     key={col}
@@ -393,19 +408,22 @@ export function DocumentTable({
               </tr>
             </thead>
             <tbody>
-              {documents.map((doc) => {
-                const isSelected = selected.has(doc.id)
-                const lookupRef = activeLookup?.docId === doc.id ? activeLookup.ref : null
+              {documents.map((doc, index) => {
+                // Derived rows may repeat an _id or have none, so the index keeps keys unique.
+                const rowKey = `${index}:${doc.id ?? ''}`
+                const stored = rowsWritable && hasId(doc) ? doc : null
+                const isSelected = stored !== null && selected.has(stored.id)
+                const lookupRef = activeLookup?.rowKey === rowKey ? activeLookup.ref : null
                 return (
                   <ContextMenu
-                    key={doc.id}
+                    key={rowKey}
                     onOpenChange={(open) => {
-                      if (!open && activeLookup?.docId === doc.id) setActiveLookup(null)
+                      if (!open && activeLookup?.rowKey === rowKey) setActiveLookup(null)
                     }}
                   >
                     <ContextMenuTrigger asChild>
                       <tr
-                        onClick={(e) => handleRowClick(doc.id, e)}
+                        onClick={stored ? (e) => handleRowClick(stored.id, e) : undefined}
                         onMouseDown={(e) => {
                           // Prevent native text-selection range expansion when the
                           // user shift-clicks across rows.
@@ -416,17 +434,21 @@ export function DocumentTable({
                           isSelected ? 'bg-primary/10 hover:bg-primary/15' : 'hover:bg-accent/30'
                         )}
                       >
-                        <td
-                          className="w-9 border-b border-r border-border/30 px-2 py-1.5 text-center align-middle"
-                          onClick={(e) => e.stopPropagation()}
-                          onContextMenu={(e) => e.stopPropagation()}
-                        >
-                          <Checkbox
-                            checked={isSelected}
-                            onClick={(e) => handleRowCheckboxClick(doc.id, e)}
-                            aria-label={isSelected ? 'Deselect document' : 'Select document'}
-                          />
-                        </td>
+                        {rowsWritable && (
+                          <td
+                            className="w-9 border-b border-r border-border/30 px-2 py-1.5 text-center align-middle"
+                            onClick={(e) => e.stopPropagation()}
+                            onContextMenu={(e) => e.stopPropagation()}
+                          >
+                            {stored && (
+                              <Checkbox
+                                checked={isSelected}
+                                onClick={(e) => handleRowCheckboxClick(stored.id, e)}
+                                aria-label={isSelected ? 'Deselect document' : 'Select document'}
+                              />
+                            )}
+                          </td>
+                        )}
                         {columns.map((col) => (
                           <Cell
                             key={col}
@@ -435,8 +457,10 @@ export function DocumentTable({
                             uuidEncoding={uuidEncoding}
                             timezone={timezone}
                             onContextMenu={() => {
-                              const ref = col === '_id' ? null : extractRef(doc.data[col])
-                              if (ref) setActiveLookup({ docId: doc.id, ref })
+                              // A stored document's own _id only points back at itself.
+                              const ref =
+                                col === '_id' && rowsWritable ? null : extractRef(doc.data[col])
+                              if (ref) setActiveLookup({ rowKey, ref })
                               else setActiveLookup(null)
                             }}
                           />
@@ -448,12 +472,10 @@ export function DocumentTable({
                         <>
                           <ContextMenuItem
                             onSelect={() =>
-                              openTab({
-                                connectionId,
-                                db: lookupRef.db ?? db,
-                                coll: lookupRef.ref,
-                                filter: `{ _id: ObjectId("${lookupRef.oid}") }`
-                              })
+                              openWithFilter(
+                                { connectionId, db: lookupRef.db ?? db, coll: lookupRef.ref },
+                                `{ _id: ObjectId("${lookupRef.oid}") }`
+                              )
                             }
                           >
                             <Link2 className="h-4 w-4" />
@@ -502,12 +524,10 @@ export function DocumentTable({
                                   <ContextMenuItem
                                     key={c.name}
                                     onSelect={() =>
-                                      openTab({
-                                        connectionId,
-                                        db,
-                                        coll: c.name,
-                                        filter: `{ _id: ObjectId("${lookupRef.oid}") }`
-                                      })
+                                      openWithFilter(
+                                        { connectionId, db, coll: c.name },
+                                        `{ _id: ObjectId("${lookupRef.oid}") }`
+                                      )
                                     }
                                   >
                                     <span className="truncate font-mono text-xs">{c.name}</span>
@@ -525,31 +545,51 @@ export function DocumentTable({
                         <Eye className="h-4 w-4" />
                         View
                       </ContextMenuItem>
-                      <ContextMenuItem
-                        onSelect={() => setEditorState({ mode: 'edit', envelope: doc })}
-                      >
-                        <Pencil className="h-4 w-4" />
-                        Edit
-                      </ContextMenuItem>
-                      <ContextMenuItem
-                        onSelect={() => setEditorState({ mode: 'duplicate', envelope: doc })}
-                      >
-                        <FilePlus2 className="h-4 w-4" />
-                        Duplicate
-                      </ContextMenuItem>
+                      {stored && (
+                        <>
+                          <ContextMenuItem
+                            onSelect={() =>
+                              withStoredDocument(stored, (envelope) =>
+                                setEditorState({ mode: 'edit', envelope })
+                              )
+                            }
+                          >
+                            <Pencil className="h-4 w-4" />
+                            Edit
+                          </ContextMenuItem>
+                          <ContextMenuItem
+                            onSelect={() =>
+                              withStoredDocument(stored, (envelope) =>
+                                setEditorState({ mode: 'duplicate', envelope })
+                              )
+                            }
+                          >
+                            <FilePlus2 className="h-4 w-4" />
+                            Duplicate
+                          </ContextMenuItem>
+                        </>
+                      )}
                       <ContextMenuSeparator />
                       <ContextMenuItem onSelect={() => void onCopy(doc)}>
                         <Copy className="h-4 w-4" />
                         Copy
                       </ContextMenuItem>
-                      <ContextMenuSeparator />
-                      <ContextMenuItem
-                        className="text-destructive focus:bg-destructive/10 focus:text-destructive"
-                        onSelect={() => setPendingDelete({ kind: 'one', envelope: doc })}
-                      >
-                        <Trash2 className="h-4 w-4" />
-                        Delete
-                      </ContextMenuItem>
+                      {stored && (
+                        <>
+                          <ContextMenuSeparator />
+                          <ContextMenuItem
+                            className="text-destructive focus:bg-destructive/10 focus:text-destructive"
+                            onSelect={() =>
+                              withStoredDocument(stored, (envelope) =>
+                                setPendingDelete({ kind: 'one', envelope })
+                              )
+                            }
+                          >
+                            <Trash2 className="h-4 w-4" />
+                            Delete
+                          </ContextMenuItem>
+                        </>
+                      )}
                     </ContextMenuContent>
                   </ContextMenu>
                 )
diff --git a/src/renderer/src/features/collection/IndexesDialog.tsx b/src/renderer/src/features/collection/IndexesDialog.tsx
index 916d737..eb3d44e 100644
--- a/src/renderer/src/features/collection/IndexesDialog.tsx
+++ b/src/renderer/src/features/collection/IndexesDialog.tsx
@@ -1,16 +1,22 @@
-import { type FormEvent, type KeyboardEvent, useEffect, useMemo, useState } from 'react'
+import { type FormEvent, useEffect, useMemo, useState } from 'react'
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import { toast } from 'sonner'
 import {
+  ArrowDown,
   ArrowLeft,
+  ArrowUp,
+  ArrowUpDown,
   ChevronDown,
   ChevronRight,
+  CircleOff,
   EyeOff,
   Hash,
+  Info,
   Key,
   Loader2,
   Lock,
   Plus,
+  RefreshCw,
   ServerCrash,
   Sparkles,
   Timer,
@@ -25,6 +31,7 @@ import {
   DialogHeader,
   DialogTitle
 } from '@/components/ui/dialog'
+import { AutocompleteInput } from '@/components/ui/autocomplete-input'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
@@ -46,16 +53,36 @@ import {
   AlertDialogHeader,
   AlertDialogTitle
 } from '@/components/ui/alert-dialog'
+import { Tooltip } from '@/components/ui/tooltip'
 import { api, ApiError } from '@/lib/api'
+import { collectionSchemaQuery } from '@/lib/completion/useCompletionEnv'
+import { formatDateInZone } from '@/lib/dateZone'
+import {
+  buildIndexRows,
+  formatAge,
+  formatCount,
+  formatRate,
+  nextSort,
+  sortIndexRows,
+  unavailableText,
+  usageAvailable,
+  usageNotes,
+  usageSources,
+  type IndexRow,
+  type IndexSort,
+  type IndexSortKey
+} from '@/lib/indexUsage'
 import { queryKeys } from '@/lib/queryClient'
 import { cn } from '@/lib/utils'
-import type { IndexCreateOptions, IndexInfo } from '@shared/types'
+import { schemaFieldPaths } from '@shared/collectionSchema'
+import type { IndexCreateOptions, IndexInfo, IndexStatsReport } from '@shared/types'
 
 type Props = {
   open: boolean
   connectionId: string
   db: string
   coll: string
+  timezone: string
   onClose: () => void
 }
 
@@ -70,13 +97,17 @@ const KEY_TYPE_OPTIONS: Array<{ value: string; label: string }> = [
   { value: 'hashed', label: 'Hashed' }
 ]
 
-export function IndexesDialog({ open, connectionId, db, coll, onClose }: Props) {
+export function IndexesDialog({ open, connectionId, db, coll, timezone, onClose }: Props) {
   const [view, setView] = useState<View>({ kind: 'list' })
   const [pendingDrop, setPendingDrop] = useState<IndexInfo | null>(null)
+  const [sort, setSort] = useState<IndexSort>(null)
   const queryClient = useQueryClient()
 
   useEffect(() => {
-    if (open) setView({ kind: 'list' })
+    if (open) {
+      setView({ kind: 'list' })
+      setSort(null)
+    }
   }, [open])
 
   const indexesQuery = useQuery({
@@ -85,6 +116,13 @@ export function IndexesDialog({ open, connectionId, db, coll, onClose }: Props)
     enabled: open
   })
 
+  // No polling: on mongos $indexStats fans out to every shard, so refresh stays manual.
+  const statsQuery = useQuery({
+    queryKey: queryKeys.indexStats(connectionId, db, coll),
+    queryFn: () => api.indexes.stats({ connectionId, db, coll }),
+    enabled: open
+  })
+
   const dropMutation = useMutation({
     mutationFn: (name: string) => api.indexes.drop({ connectionId, db, coll, name }),
     onSuccess: (_, name) => {
@@ -104,7 +142,7 @@ export function IndexesDialog({ open, connectionId, db, coll, onClose }: Props)
 
   return (
     <Dialog open={open} onOpenChange={(o) => !o && onClose()}>
-      <DialogContent className="max-w-3xl">
+      <DialogContent className="max-w-4xl">
         <DialogHeader>
           <DialogTitle className="flex items-center gap-2">
             {view.kind !== 'list' && (
@@ -131,6 +169,20 @@ export function IndexesDialog({ open, connectionId, db, coll, onClose }: Props)
             isLoading={indexesQuery.isLoading}
             error={indexesQuery.error}
             indexes={indexesQuery.data ?? []}
+            // A failed refresh keeps the previous data; showing it beside the error would mislead.
+            report={statsQuery.isError ? undefined : statsQuery.data}
+            statsLoading={statsQuery.isLoading}
+            statsError={statsQuery.error}
+            now={statsQuery.dataUpdatedAt}
+            timezone={timezone}
+            sort={sort}
+            onSort={(key) => setSort((s) => nextSort(s, key))}
+            refreshing={indexesQuery.isFetching || statsQuery.isFetching}
+            onRefresh={() =>
+              void queryClient.invalidateQueries({
+                queryKey: queryKeys.indexes(connectionId, db, coll)
+              })
+            }
             onCreate={() => setView({ kind: 'create' })}
             onDrop={(idx) => setPendingDrop(idx)}
           />
@@ -185,15 +237,38 @@ function IndexesList({
   isLoading,
   error,
   indexes,
+  report,
+  statsLoading,
+  statsError,
+  now,
+  timezone,
+  sort,
+  onSort,
+  refreshing,
+  onRefresh,
   onCreate,
   onDrop
 }: {
   isLoading: boolean
   error: unknown
   indexes: IndexInfo[]
+  report: IndexStatsReport | undefined
+  statsLoading: boolean
+  statsError: Error | null
+  now: number
+  timezone: string
+  sort: IndexSort
+  onSort: (key: IndexSortKey) => void
+  refreshing: boolean
+  onRefresh: () => void
   onCreate: () => void
   onDrop: (idx: IndexInfo) => void
 }) {
+  const rows = useMemo(
+    () => sortIndexRows(buildIndexRows(indexes, report, now), sort),
+    [indexes, report, now, sort]
+  )
+
   if (isLoading) {
     return (
       <div className="flex items-center gap-2 py-6 text-sm text-muted-foreground">
@@ -214,34 +289,92 @@ function IndexesList({
     )
   }
 
+  const usageUnavailable = report?.usageUnavailable ?? null
+  const storageUnavailable = report?.storageUnavailable ?? null
+  const hasUsage = usageAvailable(report)
+  const sizes = rows.flatMap((r) => (r.size === undefined ? [] : [r.size]))
+  const sources = report && hasUsage ? usageSources(report) : null
+
   return (
     <div className="grid gap-3">
       <div className="flex items-center justify-between">
         <div className="text-xs text-muted-foreground">
           {indexes.length} index{indexes.length === 1 ? '' : 'es'}
+          {sizes.length > 0 && ` · ${formatBytes(sizes.reduce((sum, size) => sum + size, 0))}`}
+        </div>
+        <div className="flex items-center gap-2">
+          <Button size="sm" variant="ghost" onClick={onRefresh} disabled={refreshing}>
+            {refreshing ? (
+              <Loader2 className="animate-spin" />
+            ) : (
+              <RefreshCw className="h-3.5 w-3.5" />
+            )}
+            Refresh
+          </Button>
+          <Button size="sm" onClick={onCreate}>
+            <Plus className="h-4 w-4" /> New index
+          </Button>
         </div>
-        <Button size="sm" onClick={onCreate}>
-          <Plus className="h-4 w-4" /> New index
-        </Button>
       </div>
+      {(statsError !== null || usageUnavailable !== null || storageUnavailable !== null) && (
+        <div className="flex items-start gap-2 rounded-md border bg-muted/20 px-3 py-2 text-[11px] text-muted-foreground">
+          <Info className="mt-px h-3.5 w-3.5 shrink-0" />
+          <div className="grid gap-0.5">
+            {statsError !== null && (
+              <div>
+                Could not read index statistics: {statsError.message}{' '}
+                <button type="button" onClick={onRefresh} className="underline hover:no-underline">
+                  Retry
+                </button>
+              </div>
+            )}
+            {usageUnavailable !== null && (
+              <Tooltip content={usageUnavailable.message}>
+                <div className="w-fit">{unavailableText('usage', usageUnavailable)}</div>
+              </Tooltip>
+            )}
+            {storageUnavailable !== null && (
+              <Tooltip content={storageUnavailable.message}>
+                <div className="w-fit">{unavailableText('storage', storageUnavailable)}</div>
+              </Tooltip>
+            )}
+          </div>
+        </div>
+      )}
       <div className="max-h-[60vh] overflow-auto rounded-md border">
         <table className="w-full text-xs">
-          <thead className="sticky top-0 bg-muted/40 text-left text-[10px] uppercase tracking-wider text-muted-foreground">
-            <tr>
-              <th className="px-3 py-2 font-medium">Name</th>
+          {/* z-10: spinning badges are transformed and would otherwise paint over the sticky header. */}
+          <thead className="sticky top-0 z-10 bg-background text-left text-[10px] uppercase tracking-wider text-muted-foreground">
+            <tr className="bg-muted/40">
+              <SortableHeader label="Name" sortKey="name" sort={sort} onSort={onSort} />
               <th className="px-3 py-2 font-medium">Key</th>
               <th className="px-3 py-2 font-medium">Properties</th>
-              <th className="px-3 py-2 font-medium">Size</th>
+              <SortableHeader
+                label="Size"
+                sortKey="size"
+                sort={sort}
+                onSort={onSort}
+                disabled={report === undefined || storageUnavailable !== null}
+                alignRight
+              />
+              <SortableHeader
+                label="Usage"
+                sortKey="ops"
+                sort={sort}
+                onSort={onSort}
+                disabled={!hasUsage}
+                alignRight
+              />
               <th className="w-px px-3 py-2"></th>
             </tr>
           </thead>
           <tbody>
-            {indexes.map((idx) => (
-              <tr key={idx.name} className="border-t hover:bg-accent/30">
-                <td className="px-3 py-2 align-top font-mono">{idx.name}</td>
+            {rows.map((row) => (
+              <tr key={row.index.name} className="border-t hover:bg-accent/30">
+                <td className="px-3 py-2 align-top font-mono">{row.index.name}</td>
                 <td className="px-3 py-2 align-top">
                   <div className="flex flex-wrap gap-1 font-mono">
-                    {Object.entries(idx.key).map(([field, dir]) => (
+                    {Object.entries(row.index.key).map(([field, dir]) => (
                       <span
                         key={field}
                         className="rounded-sm border bg-background px-1.5 py-0.5 text-[10px]"
@@ -253,7 +386,7 @@ function IndexesList({
                 </td>
                 <td className="px-3 py-2 align-top">
                   <div className="flex flex-wrap gap-1">
-                    {indexBadges(idx).map((b) => (
+                    {indexBadges(row.index, row.building).map((b) => (
                       <span
                         key={b.label}
                         className="flex items-center gap-1 rounded-sm border bg-background px-1.5 py-0.5 text-[10px]"
@@ -265,19 +398,30 @@ function IndexesList({
                     ))}
                   </div>
                 </td>
-                <td className="px-3 py-2 align-top font-mono text-[10px] text-muted-foreground">
-                  {idx.size !== undefined ? formatBytes(idx.size) : '—'}
+                <td className="whitespace-nowrap px-3 py-2 text-right align-top font-mono text-[10px] tabular-nums text-muted-foreground">
+                  {statsLoading ? '…' : row.size !== undefined ? formatBytes(row.size) : '—'}
+                </td>
+                <td className="whitespace-nowrap px-3 py-2 text-right align-top tabular-nums">
+                  <UsageCell
+                    row={row}
+                    statsLoading={statsLoading}
+                    hasUsage={hasUsage}
+                    now={now}
+                    timezone={timezone}
+                  />
                 </td>
                 <td className="px-3 py-2 align-top">
                   <Button
                     size="icon"
                     variant="ghost"
                     className="h-7 w-7 text-destructive hover:bg-destructive/10 hover:text-destructive disabled:text-muted-foreground"
-                    disabled={idx.name === '_id_'}
-                    onClick={() => onDrop(idx)}
+                    disabled={row.index.name === '_id_'}
+                    onClick={() => onDrop(row.index)}
                     aria-label="Drop"
                     title={
-                      idx.name === '_id_' ? 'The default _id_ index cannot be dropped' : 'Drop'
+                      row.index.name === '_id_'
+                        ? 'The default _id_ index cannot be dropped'
+                        : 'Drop'
                     }
                   >
                     <Trash2 className="h-3.5 w-3.5" />
@@ -288,15 +432,154 @@ function IndexesList({
           </tbody>
         </table>
       </div>
+      {sources !== null && sources.hosts.length > 0 && (
+        <p className="text-[10px] text-muted-foreground">
+          {sources.hosts.length === 1
+            ? `Usage counted on ${sources.hosts[0]} only; counters reset when it restarts or the index changes.`
+            : `Usage summed over ${sources.hosts.length} mongods${
+                sources.shards.length > 0
+                  ? ` across ${sources.shards.length} shard${sources.shards.length === 1 ? '' : 's'}`
+                  : ''
+              }; counters reset when a mongod restarts.`}
+        </p>
+      )}
     </div>
   )
 }
 
-function indexBadges(idx: IndexInfo): Array<{ label: string; icon: JSX.Element; title?: string }> {
+function SortableHeader({
+  label,
+  sortKey,
+  sort,
+  onSort,
+  disabled,
+  alignRight
+}: {
+  label: string
+  sortKey: IndexSortKey
+  sort: IndexSort
+  onSort: (key: IndexSortKey) => void
+  disabled?: boolean
+  alignRight?: boolean
+}) {
+  const dir = sort?.key === sortKey ? sort.dir : null
+  const Icon = dir === 'asc' ? ArrowUp : dir === 'desc' ? ArrowDown : ArrowUpDown
+  return (
+    <th
+      className={cn('px-3 py-2 font-medium', alignRight && 'text-right')}
+      aria-sort={dir === 'asc' ? 'ascending' : dir === 'desc' ? 'descending' : undefined}
+    >
+      <button
+        type="button"
+        onClick={() => onSort(sortKey)}
+        disabled={disabled}
+        className={cn(
+          'inline-flex items-center gap-1 uppercase hover:text-foreground disabled:pointer-events-none disabled:opacity-50',
+          // The icon leads in right-aligned columns so the label lines up with the values.
+          alignRight && 'flex-row-reverse'
+        )}
+      >
+        {label}
+        <Icon className={cn('h-3 w-3', dir === null && 'opacity-40')} />
+      </button>
+    </th>
+  )
+}
+
+function UsageCell({
+  row,
+  statsLoading,
+  hasUsage,
+  now,
+  timezone
+}: {
+  row: IndexRow
+  statsLoading: boolean
+  hasUsage: boolean
+  now: number
+  timezone: string
+}) {
+  if (statsLoading) return <span className="text-muted-foreground">…</span>
+  if (row.building) return <span className="text-[10px] text-muted-foreground">building</span>
+  if (!hasUsage) return <span className="text-muted-foreground">—</span>
+  const { usage } = row
+  if (usage === null) {
+    return (
+      <Tooltip content="No usage reported for this index.">
+        <span className="text-muted-foreground">—</span>
+      </Tooltip>
+    )
+  }
+
+  const notes = usageNotes(row, now)
+  return (
+    <Tooltip
+      content={
+        <div className="grid gap-0.5">
+          <div>
+            {usage.ops.toLocaleString('en-US')} ops since {formatDateInZone(usage.since, timezone)}
+          </div>
+          {usage.hosts.length > 1 &&
+            usage.hosts.map((h, i) => (
+              <div key={i} className="font-mono text-[10px]">
+                {h.shard !== undefined && `${h.shard} · `}
+                {h.host} — {h.ops.toLocaleString('en-US')} since{' '}
+                {formatDateInZone(h.since, timezone)}
+              </div>
+            ))}
+          {notes.map((note) => (
+            <div key={note}>{note}</div>
+          ))}
+        </div>
+      }
+    >
+      <div>
+        <div
+          className={cn(
+            'font-mono',
+            row.unused ? 'text-amber-400' : usage.ops === 0 && 'text-muted-foreground'
+          )}
+        >
+          {formatCount(usage.ops)}
+        </div>
+        {row.unused ? (
+          <div className="flex items-center justify-end gap-1 text-[10px] text-amber-400">
+            <CircleOff className="h-3 w-3" />
+            unused for {formatAge(now - usage.coveredSince)}
+          </div>
+        ) : (
+          <div className="text-[10px] text-muted-foreground">
+            {usage.ops > 0 && usage.opsPerDay !== null
+              ? `${formatRate(usage.opsPerDay)} over ${formatAge(now - usage.since)}`
+              : `over ${formatAge(now - usage.since)}`}
+          </div>
+        )}
+      </div>
+    </Tooltip>
+  )
+}
+
+function indexBadges(
+  idx: IndexInfo,
+  building: boolean
+): Array<{ label: string; icon: JSX.Element; title?: string }> {
   const badges: Array<{ label: string; icon: JSX.Element; title?: string }> = []
+  if (building) {
+    badges.push({
+      label: 'building',
+      icon: <Loader2 className="h-3 w-3 animate-spin" />,
+      title: 'Index build in progress'
+    })
+  }
   if (idx.unique) badges.push({ label: 'unique', icon: <Lock className="h-3 w-3" /> })
   if (idx.sparse) badges.push({ label: 'sparse', icon: <Sparkles className="h-3 w-3" /> })
-  if (idx.hidden) badges.push({ label: 'hidden', icon: <EyeOff className="h-3 w-3" /> })
+  if (idx.hidden) {
+    badges.push({
+      label: 'hidden',
+      icon: <EyeOff className="h-3 w-3" />,
+      title: 'Hidden from the query planner'
+    })
+  }
   if (idx.expireAfterSeconds !== undefined) {
     badges.push({
       label: `TTL ${idx.expireAfterSeconds}s`,
@@ -395,12 +678,10 @@ function CreateIndexForm({
   const [showAdvanced, setShowAdvanced] = useState(false)
   const queryClient = useQueryClient()
 
-  // Sample a handful of documents to offer their field paths as completions.
   // Best-effort: an empty or failed sample just means no suggestions.
   const fieldPathsQuery = useQuery({
-    queryKey: queryKeys.fieldPaths(connectionId, db, coll),
-    queryFn: () => api.query.find({ connectionId, db, coll, skip: 0, limit: 50 }),
-    select: (res) => collectFieldPaths(res.documents.map((d) => d.data))
+    ...collectionSchemaQuery(connectionId, db, coll),
+    select: schemaFieldPaths
   })
   const fieldSuggestions = fieldPathsQuery.data ?? []
 
@@ -508,11 +789,14 @@ function CreateIndexForm({
         <div className="grid gap-2">
           {state.rows.map((row, i) => (
             <div key={i} className="flex items-center gap-2">
-              <FieldPathInput
+              <AutocompleteInput
+                wrapperClassName="flex-1"
                 value={row.field}
-                onChange={(field) => updateRow(i, { field })}
+                onValueChange={(field) => updateRow(i, { field })}
                 suggestions={fieldSuggestions}
                 autoFocus={i === 0}
+                placeholder="field.path  (use foo.$**  for wildcard)"
+                spellCheck={false}
               />
               <div className="w-44">
                 <Select value={row.type} onValueChange={(v) => updateRow(i, { type: v })}>
@@ -860,145 +1144,6 @@ function EjsonField({
   )
 }
 
-/**
- * Field-path input with completion from sampled documents. Tab or Enter
- * accepts the highlighted suggestion, arrow keys navigate, Escape closes
- * the list (without closing the surrounding dialog).
- */
-function FieldPathInput({
-  value,
-  onChange,
-  suggestions,
-  autoFocus
-}: {
-  value: string
-  onChange: (v: string) => void
-  suggestions: string[]
-  autoFocus?: boolean
-}) {
-  const [open, setOpen] = useState(false)
-  const [active, setActive] = useState(0)
-
-  const matches = useMemo(() => {
-    const needle = value.trim().toLowerCase()
-    const pool = needle ? suggestions.filter((s) => s.toLowerCase().includes(needle)) : suggestions
-    const sorted = needle
-      ? [...pool].sort((a, b) => {
-          const aPrefix = a.toLowerCase().startsWith(needle) ? 0 : 1
-          const bPrefix = b.toLowerCase().startsWith(needle) ? 0 : 1
-          return aPrefix - bPrefix || a.localeCompare(b)
-        })
-      : pool
-    // Nothing left to complete once the value matches the only candidate.
-    if (sorted.length === 1 && sorted[0] === value.trim()) return []
-    return sorted.slice(0, 50)
-  }, [value, suggestions])
-
-  useEffect(() => {
-    setActive(0)
-  }, [value])
-
-  const accept = (s: string) => {
-    onChange(s)
-    setOpen(false)
-  }
-
-  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
-    if (!open || matches.length === 0) return
-    if (e.key === 'ArrowDown') {
-      e.preventDefault()
-      setActive((i) => (i + 1) % matches.length)
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault()
-      setActive((i) => (i - 1 + matches.length) % matches.length)
-    } else if (e.key === 'Tab' || e.key === 'Enter') {
-      e.preventDefault()
-      accept(matches[active] ?? matches[0]!)
-    } else if (e.key === 'Escape') {
-      e.preventDefault()
-      e.stopPropagation()
-      setOpen(false)
-    }
-  }
-
-  return (
-    <div className="relative flex-1">
-      <Input
-        value={value}
-        onChange={(e) => {
-          onChange(e.target.value)
-          setOpen(true)
-        }}
-        onFocus={() => setOpen(true)}
-        onBlur={() => setOpen(false)}
-        onKeyDown={onKeyDown}
-        placeholder="field.path  (use foo.$**  for wildcard)"
-        spellCheck={false}
-        className="w-full font-mono"
-        autoFocus={autoFocus}
-        role="combobox"
-        aria-expanded={open && matches.length > 0}
-        aria-autocomplete="list"
-      />
-      {open && matches.length > 0 && (
-        <ul
-          className="absolute left-0 right-0 top-full z-50 mt-1 max-h-40 overflow-auto rounded-md border bg-popover p-1 text-popover-foreground shadow-md"
-          role="listbox"
-          // Keep focus in the input so onBlur doesn't close the list
-          // before an option click registers.
-          onMouseDown={(e) => e.preventDefault()}
-        >
-          {matches.map((s, i) => (
-            <li
-              key={s}
-              role="option"
-              aria-selected={i === active}
-              onMouseEnter={() => setActive(i)}
-              onClick={() => accept(s)}
-              className={cn(
-                'cursor-pointer rounded-sm px-2 py-1 font-mono text-xs',
-                i === active ? 'bg-accent text-accent-foreground' : 'text-foreground'
-              )}
-            >
-              {s}
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  )
-}
-
-const MAX_FIELD_PATH_DEPTH = 4
-
-/**
- * Distinct dot-notation field paths across the sampled documents, sorted.
- * `data` is relaxed EJSON, so objects whose keys all start with `$`
- * (e.g. { $oid }, { $date }) are type wrappers, not subdocuments. Array
- * elements share their parent path, matching how indexes address them.
- */
-function collectFieldPaths(docs: Array<Record<string, unknown>>): string[] {
-  const paths = new Set<string>()
-  const visit = (value: unknown, prefix: string, depth: number): void => {
-    if (depth > MAX_FIELD_PATH_DEPTH || value === null || typeof value !== 'object') return
-    if (Array.isArray(value)) {
-      for (const item of value) visit(item, prefix, depth)
-      return
-    }
-    const obj = value as Record<string, unknown>
-    const keys = Object.keys(obj)
-    if (prefix && keys.length > 0 && keys.every((k) => k.startsWith('$'))) return
-    for (const key of keys) {
-      if (key.startsWith('$')) continue
-      const path = prefix ? `${prefix}.${key}` : key
-      paths.add(path)
-      visit(obj[key], path, depth + 1)
-    }
-  }
-  for (const doc of docs) visit(doc, '', 0)
-  return Array.from(paths).sort((a, b) => a.localeCompare(b))
-}
-
 function validateForm(state: FormState, ttlEligible: boolean): string | null {
   const filledRows = state.rows.filter((r) => r.field.trim())
   if (filledRows.length === 0) return 'At least one key field is required'
diff --git a/src/renderer/src/features/collection/QueryEditor.test.tsx b/src/renderer/src/features/collection/QueryEditor.test.tsx
new file mode 100644
index 0000000..1307199
--- /dev/null
+++ b/src/renderer/src/features/collection/QueryEditor.test.tsx
@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { OnMount } from '@monaco-editor/react'
+import type { CompletionEnv } from '@/lib/completion/useCompletionEnv'
+import { QueryEditor } from './QueryEditor'
+
+const editorProps = vi.hoisted(() => ({ onMount: null as unknown }))
+
+vi.mock('monaco-editor', () => ({}))
+vi.mock('@monaco-editor/react', () => ({
+  default: (props: { onMount: unknown }) => {
+    editorProps.onMount = props.onMount
+    return null
+  }
+}))
+vi.mock('@/lib/completion/monacoAdapter', () => ({
+  attachCompletion: () => ({ dispose: () => undefined })
+}))
+// The real module boots Monaco's workers and languages as a side effect.
+vi.mock('@/lib/monacoSetup', () => ({ BASE_EDITOR_OPTIONS: {} }))
+
+const KeyMod = { CtrlCmd: 2048, Shift: 1024, Alt: 512 }
+const KeyCode = { Enter: 3, KeyF: 36 }
+const CTRL_ENTER = KeyMod.CtrlCmd | KeyCode.Enter
+
+type KeyEvent = {
+  browserEvent: { repeat: boolean }
+  equals: (keybinding: number) => boolean
+  preventDefault: () => void
+  stopPropagation: () => void
+}
+
+/** Mounts the editor on a fake Monaco; the returned `press` reports whether the editor stopped the key. */
+function mountEditor(onSubmit: () => void): (keybinding: number, repeat: boolean) => boolean {
+  renderToStaticMarkup(
+    <QueryEditor
+      modelPath="mongobench://query/t1/shell"
+      completion={{ kind: 'shell', env: {} as CompletionEnv }}
+      value=""
+      onChange={() => undefined}
+      onSubmit={onSubmit}
+    />
+  )
+  const disposable = { dispose: () => undefined }
+  const keyListeners: ((event: KeyEvent) => void)[] = []
+  const actions = new Map<number, () => void>()
+  const editor = {
+    addAction: ({ keybindings, run }: { keybindings: number[]; run: () => void }) => {
+      for (const keybinding of keybindings) actions.set(keybinding, run)
+      return disposable
+    },
+    onKeyDown: (listener: (event: KeyEvent) => void) => {
+      keyListeners.push(listener)
+      return disposable
+    },
+    getModel: () => null,
+    onDidChangeModel: () => disposable,
+    onDidContentSizeChange: () => disposable,
+    getContentHeight: () => 18
+  }
+  ;(editorProps.onMount as OnMount)(editor as never, { KeyMod, KeyCode } as never)
+  return (keybinding, repeat) => {
+    let stopped = false
+    const event: KeyEvent = {
+      browserEvent: { repeat },
+      equals: (other) => other === keybinding,
+      preventDefault: () => undefined,
+      stopPropagation: () => (stopped = true)
+    }
+    for (const listener of keyListeners) listener(event)
+    // Monaco dispatches keybindings from the editor's container, which a stopped event never reaches.
+    if (!stopped) actions.get(keybinding)?.()
+    return stopped
+  }
+}
+
+describe('QueryEditor Run keybinding', () => {
+  it('runs once per press of Ctrl/Cmd+Enter, not on the key repeats of holding it', () => {
+    const onSubmit = vi.fn()
+    const press = mountEditor(onSubmit)
+    press(CTRL_ENTER, false)
+    press(CTRL_ENTER, true)
+    press(CTRL_ENTER, true)
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+    press(CTRL_ENTER, false)
+    expect(onSubmit).toHaveBeenCalledTimes(2)
+  })
+
+  it('leaves the key repeats of other keys to the editor', () => {
+    const press = mountEditor(vi.fn())
+    expect(press(KeyCode.Enter, true)).toBe(false)
+    expect(press(KeyMod.Shift | KeyCode.Enter, true)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/features/collection/QueryEditor.tsx b/src/renderer/src/features/collection/QueryEditor.tsx
index c5357ac..a79326c 100644
--- a/src/renderer/src/features/collection/QueryEditor.tsx
+++ b/src/renderer/src/features/collection/QueryEditor.tsx
@@ -1,9 +1,39 @@
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import Editor, { type OnMount } from '@monaco-editor/react'
 import * as monaco from 'monaco-editor'
 import { cn } from '@/lib/utils'
+import type { CompletionBinding } from '@/lib/completion/monacoAdapter'
+import { useCompletionAttachment } from '@/lib/completion/useCompletionAttachment'
+import { BASE_EDITOR_OPTIONS } from '@/lib/monacoSetup'
+import { queryModelTabId } from '@/lib/queryModelUri'
+import { useTabsStore } from '@/store/tabs'
+
+// @monaco-editor/react keys its unmount save by the editor's first path, wrong once path changes.
+const viewStates = new Map<string, monaco.editor.ICodeEditorViewState>()
+
+function storeViewState(editor: monaco.editor.IStandaloneCodeEditor | null): void {
+  const model = editor?.getModel()
+  const state = editor?.saveViewState()
+  if (model && state) viewStates.set(model.uri.toString(), state)
+}
+
+// Query models outlive editor instances (keepCurrentModel) and end with their tab.
+useTabsStore.subscribe((state, prev) => {
+  if (state.tabs === prev.tabs) return
+  const openIds = new Set(state.tabs.map((t) => t.id))
+  for (const model of monaco.editor.getModels()) {
+    const tabId = queryModelTabId(model.uri)
+    if (tabId === null || openIds.has(tabId)) continue
+    viewStates.delete(model.uri.toString())
+    model.dispose()
+  }
+})
 
 type Props = {
+  /** Monaco model path (see queryModelUri); one model per tab and slot, disposed with the tab. */
+  modelPath: string
+  /** Editor kind and environment for completion; read on every request. */
+  completion: CompletionBinding
   value: string
   onChange: (next: string) => void
   onSubmit: () => void
@@ -30,14 +60,16 @@ type Props = {
 }
 
 /**
- * MongoDB filter editor.
+ * MongoDB query editor.
  *
- * Wraps Monaco with: JSON syntax highlighting, bracket auto-pairing,
- * format-on-paste, MongoDB operator IntelliSense (registered once via
- * `ensureProviderRegistered`), and a destructive-coloured border when
- * the value isn't valid JSON.
+ * Wraps Monaco with: mongo-shell syntax highlighting, bracket auto-pairing,
+ * format-on-paste, schema-aware MongoDB completion (bound per editor via
+ * `attachCompletion`), and a destructive-coloured border when
+ * the value doesn't parse.
  */
 export function QueryEditor({
+  modelPath,
+  completion,
   value,
   onChange,
   onSubmit,
@@ -51,6 +83,8 @@ export function QueryEditor({
   onContentHeightChange
 }: Props) {
   const editorRef = useRef<monaco.editor.IStandaloneCodeEditor | null>(null)
+  const actionsRef = useRef<monaco.IDisposable[]>([])
+  const bindCompletion = useCompletionAttachment(completion)
   const submitRef = useRef(onSubmit)
   const formatRef = useRef(onFormat)
   const minHeightRef = useRef(minHeight)
@@ -77,15 +111,31 @@ export function QueryEditor({
     const ch = editor.getContentHeight()
     setContentHeight(Math.min(Math.max(ch, minHeight), maxHeight))
   }, [minHeight, maxHeight])
+  // Editor disposal does not release addAction registrations.
+  useEffect(() => () => actionsRef.current.forEach((d) => d.dispose()), [])
+  // Layout cleanup runs before the library's passive effects swap the model or dispose the editor.
+  useLayoutEffect(() => () => storeViewState(editorRef.current), [modelPath])
 
   const handleMount: OnMount = (editor, m) => {
     editorRef.current = editor
-    ensureProviderRegistered()
 
-    editor.addCommand(m.KeyMod.CtrlCmd | m.KeyCode.Enter, () => submitRef.current())
-    editor.addAction({
+    const runKeybinding = m.KeyMod.CtrlCmd | m.KeyCode.Enter
+    // addAction scopes the keybinding to this editor; addCommand binds it globally to the last one.
+    const runAction = editor.addAction({
+      id: 'mongobench.run',
+      label: 'Run query',
+      keybindings: [runKeybinding],
+      run: () => submitRef.current()
+    })
+    // Keybindings dispatch from the container after this listener; a held key must not run again.
+    editor.onKeyDown((e) => {
+      if (!e.browserEvent.repeat || !e.equals(runKeybinding)) return
+      e.preventDefault()
+      e.stopPropagation()
+    })
+    const formatAction = editor.addAction({
       id: 'mongobench.format',
-      label: 'Format JSON',
+      label: 'Format',
       keybindings: [m.KeyMod.Shift | m.KeyMod.Alt | m.KeyCode.KeyF],
       run: () => {
         if (formatRef.current) {
@@ -95,6 +145,16 @@ export function QueryEditor({
         }
       }
     })
+    actionsRef.current = [runAction, formatAction]
+    bindCompletion(editor)
+
+    const restoreViewState = () => {
+      const model = editor.getModel()
+      const state = model ? viewStates.get(model.uri.toString()) : undefined
+      if (state) editor.restoreViewState(state)
+    }
+    editor.onDidChangeModel(restoreViewState)
+    restoreViewState()
 
     const sync = () => {
       const ch = editor.getContentHeight()
@@ -124,11 +184,15 @@ export function QueryEditor({
         width="100%"
         language="mongo-shell"
         theme="mongobench-dark"
+        path={modelPath}
+        keepCurrentModel
+        saveViewState={false}
         value={value}
         onMount={handleMount}
         onChange={(v) => onChange(v ?? '')}
         loading={<div className="px-3 py-1.5 text-xs text-muted-foreground">Loading editor…</div>}
         options={{
+          ...BASE_EDITOR_OPTIONS,
           minimap: { enabled: false },
           lineNumbers: 'off',
           fontFamily: 'JetBrains Mono, ui-monospace, monospace',
@@ -156,9 +220,8 @@ export function QueryEditor({
             alwaysConsumeMouseWheel: false
           },
           quickSuggestions: { other: true, comments: false, strings: true },
-          suggestOnTriggerCharacters: true,
-          acceptSuggestionOnEnter: 'smart',
           tabCompletion: 'on',
+          suggest: { ...BASE_EDITOR_OPTIONS.suggest, snippetsPreventQuickSuggestions: false },
           autoClosingBrackets: 'always',
           autoClosingQuotes: 'always',
           autoSurround: 'languageDefined',
@@ -179,389 +242,3 @@ export function QueryEditor({
     </div>
   )
 }
-
-let providerRegistered = false
-
-// Distinct top-level keys from the most recently fetched documents. The
-// completion provider reads this directly so it doesn't have to be
-// re-registered on every fetch — refreshing the cache is enough.
-let documentFieldNames: string[] = []
-
-export function setDocumentFieldNames(names: Iterable<string>): void {
-  documentFieldNames = Array.from(new Set(names)).sort((a, b) => a.localeCompare(b))
-}
-
-function ensureProviderRegistered(): void {
-  if (providerRegistered) return
-  providerRegistered = true
-
-  monaco.languages.registerCompletionItemProvider('mongo-shell', {
-    triggerCharacters: ['$', '"', 'I', 'O', 'N', 'U', 'D', 'B', 'T', 'M', '{', ',', ' '],
-    provideCompletionItems(model, position) {
-      const lineUpToCursor = model.getValueInRange({
-        startLineNumber: position.lineNumber,
-        startColumn: 1,
-        endLineNumber: position.lineNumber,
-        endColumn: position.column
-      })
-
-      // Three trigger contexts:
-      //  - `$foo` (optionally with leading `"`) → MongoDB query operator
-      //  - bare identifier prefix → mongo shell helper (ObjectId, ISODate, …)
-      //  - after `{` or `,` (object key position) → cached document field names
-      const opMatch = /"?\$[A-Za-z]*$/.exec(lineUpToCursor)
-      const helperMatch = /(?:^|[\s:,[(])([A-Za-z][A-Za-z0-9]*)$/.exec(lineUpToCursor)
-      const helperPrefix = helperMatch ? helperMatch[1]! : null
-      const keyMatch = /(?:^|[{,])\s*("?)([A-Za-z_$][\w.]*)?$/.exec(lineUpToCursor)
-
-      if (opMatch) {
-        const range = new monaco.Range(
-          position.lineNumber,
-          position.column - opMatch[0].length,
-          position.lineNumber,
-          position.column
-        )
-        const suggestions = buildMongoCompletions().map((c): monaco.languages.CompletionItem => ({
-          label: c.label,
-          kind: c.kind ?? monaco.languages.CompletionItemKind.Keyword,
-          insertText: c.insertText,
-          insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
-          documentation: { value: c.doc },
-          detail: c.detail,
-          range,
-          sortText: c.sortText ?? c.label
-        }))
-        return { suggestions }
-      }
-
-      const suggestions: monaco.languages.CompletionItem[] = []
-
-      if (keyMatch && documentFieldNames.length > 0) {
-        const hasQuote = keyMatch[1] === '"'
-        const partial = keyMatch[2] ?? ''
-        const startCol = position.column - partial.length - (hasQuote ? 1 : 0)
-        const range = new monaco.Range(
-          position.lineNumber,
-          startCol,
-          position.lineNumber,
-          position.column
-        )
-        for (const name of documentFieldNames) {
-          suggestions.push({
-            label: name,
-            kind: monaco.languages.CompletionItemKind.Field,
-            insertText: `"${name}"`,
-            filterText: name,
-            detail: 'Document field',
-            range,
-            // Prefix '0' so field names sort above operators / helpers when
-            // both contexts overlap (e.g. user typed a bare letter).
-            sortText: `0_${name}`
-          })
-        }
-      }
-
-      if (helperPrefix) {
-        const range = new monaco.Range(
-          position.lineNumber,
-          position.column - helperPrefix.length,
-          position.lineNumber,
-          position.column
-        )
-        for (const c of buildShellHelpers()) {
-          suggestions.push({
-            label: c.label,
-            kind: c.kind ?? monaco.languages.CompletionItemKind.Keyword,
-            insertText: c.insertText,
-            insertTextRules: monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
-            documentation: { value: c.doc },
-            detail: c.detail,
-            range,
-            sortText: c.sortText ?? c.label
-          })
-        }
-      }
-
-      return { suggestions }
-    }
-  })
-}
-
-type CompletionDef = {
-  label: string
-  insertText: string
-  doc: string
-  detail: string
-  kind?: monaco.languages.CompletionItemKind
-  sortText?: string
-}
-
-// Always wraps in `"…"` to produce valid JSON keys regardless of whether
-// the user already typed an opening quote (range covers the leading `"`).
-const op = (
-  label: string,
-  insertText: string,
-  doc: string,
-  detail = 'MongoDB query operator'
-): CompletionDef => ({
-  label,
-  insertText: `"${insertText}"`.replace(/^""/, '"'),
-  doc,
-  detail,
-  kind: monaco.languages.CompletionItemKind.Function
-})
-
-// Comparison
-const COMPARISON: CompletionDef[] = [
-  op('$eq', '$eq": ${1:value}', 'Matches values equal to a specified value.'),
-  op('$ne', '$ne": ${1:value}', 'Matches values not equal to a specified value.'),
-  op('$gt', '$gt": ${1:value}', 'Matches values greater than a specified value.'),
-  op('$gte', '$gte": ${1:value}', 'Matches values greater than or equal to a specified value.'),
-  op('$lt', '$lt": ${1:value}', 'Matches values less than a specified value.'),
-  op('$lte', '$lte": ${1:value}', 'Matches values less than or equal to a specified value.'),
-  op('$in', '$in": [${1:values}]', 'Matches any of the values in the array.'),
-  op('$nin', '$nin": [${1:values}]', 'Matches none of the values in the array.')
-]
-
-// Logical
-const LOGICAL: CompletionDef[] = [
-  op('$and', '$and": [\n\t{ $0 }\n]', 'Joins clauses with logical AND.'),
-  op('$or', '$or": [\n\t{ $0 }\n]', 'Joins clauses with logical OR.'),
-  op('$nor', '$nor": [\n\t{ $0 }\n]', 'Joins clauses with logical NOR.'),
-  op('$not', '$not": { $0 }', 'Inverts the effect of an expression.')
-]
-
-// Element
-const ELEMENT: CompletionDef[] = [
-  op('$exists', '$exists": ${1|true,false|}', 'Matches documents that have or lack the field.'),
-  op(
-    '$type',
-    '$type": "${1|double,string,object,array,binData,objectId,bool,date,null,regex,int,timestamp,long,decimal,minKey,maxKey|}"',
-    'Matches documents whose field is one of the BSON types.'
-  )
-]
-
-// Evaluation
-const EVALUATION: CompletionDef[] = [
-  op('$expr', '$expr": { $0 }', 'Allows the use of aggregation expressions inside the query.'),
-  op('$jsonSchema', '$jsonSchema": { $0 }', 'Validates documents against a JSON Schema.'),
-  op('$mod', '$mod": [${1:divisor}, ${2:remainder}]', 'Performs a modulo operation.'),
-  op('$regex', '$regex": "${1:pattern}", "$options": "${2:i}"', 'Pattern match against a regex.'),
-  op('$options', '$options": "${1:i}"', 'Regex options: i (case-insensitive), m, x, s.'),
-  op('$text', '$text": { "$search": "${1:query}" }', 'Performs a text search.'),
-  op('$search', '$search": "${1:query}"', 'Search string for a $text query.'),
-  op('$language', '$language": "${1:english}"', 'Language to use for the text search.'),
-  op('$caseSensitive', '$caseSensitive": ${1|true,false|}', 'Case-sensitive text search.'),
-  op(
-    '$diacriticSensitive',
-    '$diacriticSensitive": ${1|true,false|}',
-    'Diacritic-sensitive text search.'
-  ),
-  op(
-    '$where',
-    '$where": "${1:function() { return true; }}"',
-    'Server-side JavaScript predicate (slow!).'
-  )
-]
-
-// Array
-const ARRAY_OPS: CompletionDef[] = [
-  op('$all', '$all": [${1:values}]', 'Matches arrays containing all the specified elements.'),
-  op(
-    '$elemMatch',
-    '$elemMatch": { $0 }',
-    'Matches arrays with at least one element matching all criteria.'
-  ),
-  op('$size', '$size": ${1:n}', 'Matches arrays of the given length.')
-]
-
-// Bitwise
-const BITWISE: CompletionDef[] = [
-  op('$bitsAllClear', '$bitsAllClear": ${1:mask}', 'All bits in the mask are clear (0).'),
-  op('$bitsAllSet', '$bitsAllSet": ${1:mask}', 'All bits in the mask are set (1).'),
-  op('$bitsAnyClear', '$bitsAnyClear": ${1:mask}', 'Any bit in the mask is clear.'),
-  op('$bitsAnySet', '$bitsAnySet": ${1:mask}', 'Any bit in the mask is set.')
-]
-
-// Geospatial
-const GEO: CompletionDef[] = [
-  op(
-    '$geoIntersects',
-    '$geoIntersects": { "$geometry": { "type": "${1:Point}", "coordinates": [${2:0}, ${3:0}] } }',
-    'Selects geometries that intersect with a GeoJSON geometry.'
-  ),
-  op(
-    '$geoWithin',
-    '$geoWithin": { "$geometry": { "type": "${1:Polygon}", "coordinates": $2 } }',
-    'Selects geometries within a bounding GeoJSON geometry.'
-  ),
-  op(
-    '$near',
-    '$near": { "$geometry": { "type": "Point", "coordinates": [${1:lng}, ${2:lat}] }, "$maxDistance": ${3:meters} }',
-    'Returns docs ordered by proximity to a point.'
-  ),
-  op(
-    '$nearSphere',
-    '$nearSphere": { "$geometry": { "type": "Point", "coordinates": [${1:lng}, ${2:lat}] }, "$maxDistance": ${3:meters} }',
-    'Like $near but uses spherical geometry.'
-  ),
-  op(
-    '$geometry',
-    '$geometry": { "type": "${1:Point}", "coordinates": ${2} }',
-    'GeoJSON geometry helper.'
-  ),
-  op('$maxDistance', '$maxDistance": ${1:meters}', 'Max distance (meters) from $near point.'),
-  op('$minDistance', '$minDistance": ${1:meters}', 'Min distance (meters) from $near point.'),
-  op(
-    '$box',
-    '$box": [[${1:lngLow}, ${2:latLow}], [${3:lngHigh}, ${4:latHigh}]]',
-    'Legacy bounding box for $geoWithin.'
-  ),
-  op(
-    '$center',
-    '$center": [[${1:lng}, ${2:lat}], ${3:radius}]',
-    'Legacy circle (flat) for $geoWithin.'
-  ),
-  op(
-    '$centerSphere',
-    '$centerSphere": [[${1:lng}, ${2:lat}], ${3:radians}]',
-    'Spherical circle for $geoWithin.'
-  ),
-  op(
-    '$polygon',
-    '$polygon": [[${1:lng1}, ${2:lat1}], [${3:lng2}, ${4:lat2}], [${5:lng3}, ${6:lat3}]]',
-    'Legacy polygon for $geoWithin.'
-  )
-]
-
-// Projection / cursor modifiers (used in projection field, but also valid in find spec)
-const PROJECTION: CompletionDef[] = [
-  op('$slice', '$slice": ${1:n}', 'Limit array elements in projection.', 'Projection operator'),
-  op('$meta', '$meta": "${1|textScore,indexKey|}"', 'Project metadata.', 'Projection operator')
-]
-
-// EJSON wrappers — for value position (BSON types)
-function buildEjsonWrappers(): CompletionDef[] {
-  const nowIso = new Date().toISOString()
-  const nowSec = Math.floor(Date.now() / 1000)
-  return [
-    op(
-      '$oid',
-      '$oid": "${1:507f1f77bcf86cd799439011}"',
-      'EJSON: ObjectId wrapper.',
-      'EJSON / BSON type'
-    ),
-    op(
-      '$date',
-      `$date": "\${1:${nowIso}}"`,
-      'EJSON: Date wrapper (ISO-8601 string or { "$numberLong": "ms" }).',
-      'EJSON / BSON type'
-    ),
-    op('$numberLong', '$numberLong": "${1:0}"', 'EJSON: 64-bit integer.', 'EJSON / BSON type'),
-    op('$numberInt', '$numberInt": "${1:0}"', 'EJSON: 32-bit integer.', 'EJSON / BSON type'),
-    op('$numberDouble', '$numberDouble": "${1:0.0}"', 'EJSON: 64-bit float.', 'EJSON / BSON type'),
-    op(
-      '$numberDecimal',
-      '$numberDecimal": "${1:0}"',
-      'EJSON: 128-bit decimal.',
-      'EJSON / BSON type'
-    ),
-    op(
-      '$binary',
-      '$binary": { "base64": "${1:}", "subType": "${2:00}" }',
-      'EJSON: BSON binary.',
-      'EJSON / BSON type'
-    ),
-    op(
-      '$timestamp',
-      `$timestamp": { "t": \${1:${nowSec}}, "i": \${2:0} }`,
-      'EJSON: BSON timestamp (replication).',
-      'EJSON / BSON type'
-    ),
-    op(
-      '$uuid',
-      '$uuid": "${1:00000000-0000-0000-0000-000000000000}"',
-      'EJSON: UUID (BSON binary subType 4).',
-      'EJSON / BSON type'
-    ),
-    op(
-      '$regularExpression',
-      '$regularExpression": { "pattern": "${1:}", "options": "${2:i}" }',
-      'EJSON: BSON regex (canonical).',
-      'EJSON / BSON type'
-    ),
-    op('$symbol', '$symbol": "${1:}"', 'EJSON: deprecated BSON symbol.', 'EJSON / BSON type'),
-    op('$code', '$code": "${1:function() {}}"', 'EJSON: BSON Code.', 'EJSON / BSON type'),
-    op('$minKey', '$minKey": 1', 'EJSON: BSON MinKey marker.', 'EJSON / BSON type'),
-    op('$maxKey', '$maxKey": 1', 'EJSON: BSON MaxKey marker.', 'EJSON / BSON type'),
-    op('$undefined', '$undefined": true', 'EJSON: deprecated BSON Undefined.', 'EJSON / BSON type')
-  ]
-}
-
-function buildMongoCompletions(): CompletionDef[] {
-  return [
-    ...COMPARISON,
-    ...LOGICAL,
-    ...ELEMENT,
-    ...EVALUATION,
-    ...ARRAY_OPS,
-    ...BITWISE,
-    ...GEO,
-    ...PROJECTION,
-    ...buildEjsonWrappers()
-  ]
-}
-
-// Shell helpers — bare identifiers the user types in value position.
-// The mongoQueryLang parser rewrites these into EJSON wrappers before the
-// query is sent to the backend, so suggesting them as snippets is safe.
-const helper = (
-  label: string,
-  insertText: string,
-  doc: string,
-  detail = 'mongo shell helper'
-): CompletionDef => ({
-  label,
-  insertText,
-  doc,
-  detail,
-  kind: monaco.languages.CompletionItemKind.Constructor
-})
-
-function buildShellHelpers(): CompletionDef[] {
-  const nowIso = new Date().toISOString()
-  const nowSec = Math.floor(Date.now() / 1000)
-  return [
-    helper('ObjectId', 'ObjectId("${1:507f1f77bcf86cd799439011}")', 'ObjectId hex literal.'),
-    helper('ISODate', `ISODate("\${1:${nowIso}}")`, 'ISO-8601 date — defaults to now.'),
-    helper('Date', `Date("\${1:${nowIso}}")`, 'Same as ISODate — defaults to now.'),
-    helper('NumberLong', 'NumberLong("${1:0}")', 'BSON 64-bit integer.'),
-    helper('NumberInt', 'NumberInt(${1:0})', 'BSON 32-bit integer.'),
-    helper('NumberDecimal', 'NumberDecimal("${1:0}")', 'BSON 128-bit decimal.'),
-    helper(
-      'UUID',
-      'UUID("${1:00000000-0000-0000-0000-000000000000}")',
-      'UUID literal (BSON subType 04).'
-    ),
-    helper(
-      'JUUID',
-      'JUUID("${1:00000000-0000-0000-0000-000000000000}")',
-      'Legacy Java-driver UUID (BSON subType 03, Java byte order).'
-    ),
-    helper('BinData', 'BinData(${1:0}, "${2:base64==}")', 'Binary data with subType.'),
-    helper('Timestamp', `Timestamp(\${1:${nowSec}}, \${2:0})`, 'BSON timestamp (replication).'),
-    helper('MinKey', 'MinKey', 'Sorts before any other BSON value.'),
-    helper('MaxKey', 'MaxKey', 'Sorts after any other BSON value.'),
-    helper('DBRef', 'DBRef("${1:coll}", ${2:id})', 'Document reference.'),
-    helper('Code', 'Code("${1:function() {}}")', 'BSON Code value.'),
-    helper(
-      'RegExp',
-      'RegExp("${1:pattern}", "${2:i}")',
-      'Regex; equivalent to a /pattern/flags literal.'
-    ),
-    helper('true', 'true', 'Boolean true.', 'literal'),
-    helper('false', 'false', 'Boolean false.', 'literal'),
-    helper('null', 'null', 'Null value.', 'literal'),
-    helper('undefined', 'undefined', 'BSON Undefined (deprecated).', 'literal')
-  ]
-}
diff --git a/src/renderer/src/features/collection/QueryToolbar.tsx b/src/renderer/src/features/collection/QueryToolbar.tsx
index 9e534b6..161a8c6 100644
--- a/src/renderer/src/features/collection/QueryToolbar.tsx
+++ b/src/renderer/src/features/collection/QueryToolbar.tsx
@@ -1,19 +1,26 @@
-import { type FormEvent, useEffect, useMemo, useState } from 'react'
-import { ArrowDownUp, Eye, Play, Wand2, X, XCircle } from 'lucide-react'
+import { type FormEvent, useMemo, useState } from 'react'
+import { ArrowDownUp, Eye, Loader2, PenLine, Play, Wand2, X, XCircle } from 'lucide-react'
 import { Button } from '@/components/ui/button'
 import { Tooltip } from '@/components/ui/tooltip'
 import { cn } from '@/lib/utils'
+import { compilePipelineSource } from '@/lib/aggregationPipeline'
+import type { CompletionBinding } from '@/lib/completion/monacoAdapter'
+import type { CompletionEnv } from '@/lib/completion/useCompletionEnv'
+import { formatMongoSource } from '@/lib/mongoFormat'
 import { parseMongoQuery } from '@/lib/mongoQueryLang'
-import { parseShellCommand, type ShellParseResult } from '@/lib/shellParser'
-import type { CollectionTab, QueryMode, QueryPatch } from '@/store/tabs'
-import type { DocumentEnvelope, UuidEncoding } from '@shared/types'
+import type { SerializeOptions } from '@/lib/mongoQuerySerialize'
+import { queryModelUri } from '@/lib/queryModelUri'
+import type { CompiledFind, ShellWriteCommand } from '@/lib/queryRun'
+import {
+  formatShellCommand,
+  parseShellCommand,
+  shellCollectionAccessor,
+  writeTargetName
+} from '@/lib/shellParser'
+import { useTabsStore, type CollectionTab, type QueryDraft, type QueryMode } from '@/store/tabs'
+import type { UuidEncoding } from '@shared/types'
 import { ExportButton } from './ExportButton'
-import { QueryEditor, setDocumentFieldNames } from './QueryEditor'
-
-const EMPTY_OBJECT = '{}'
-const EMPTY_ARRAY = '[]'
-const objOrDefault = (s: string): string => (s.trim().length === 0 ? EMPTY_OBJECT : s)
-const arrOrDefault = (s: string): string => (s.trim().length === 0 ? EMPTY_ARRAY : s)
+import { QueryEditor } from './QueryEditor'
 
 const MODES: ReadonlyArray<{ id: QueryMode; label: string }> = [
   { id: 'simple', label: 'Simple' },
@@ -21,119 +28,115 @@ const MODES: ReadonlyArray<{ id: QueryMode; label: string }> = [
   { id: 'shell', label: 'Shell' }
 ]
 
-export function QueryToolbar({
-  tab,
-  onApply,
-  onCancel,
-  loading,
-  documents,
-  uuidEncoding,
-  timezone,
-  compiledFilter,
-  compiledProjection,
-  compiledSort
-}: {
+type ToolbarProps = {
   tab: CollectionTab
-  onApply: (patch: QueryPatch) => void
   onCancel: () => void
+  /** Runs a shell draft that writes; reads run through the store's `run`. */
+  onRunWrite: (command: ShellWriteCommand) => void
   loading: boolean
-  documents: DocumentEnvelope[]
+  /** The shown shell write is running; it can't be cancelled. */
+  writing: boolean
+  completionEnv: CompletionEnv
   uuidEncoding: UuidEncoding
   timezone: string
-  compiledFilter: string | null
-  compiledProjection: string | null
-  compiledSort: string | null
-}) {
-  const [filter, setFilter] = useState(() => objOrDefault(tab.filter))
-  const [projection, setProjection] = useState(() => objOrDefault(tab.projection))
-  const [sort, setSort] = useState(() => objOrDefault(tab.sort))
-  const [pipeline, setPipeline] = useState(() => arrOrDefault(tab.pipeline))
-  const [shell, setShell] = useState(() => tab.shell)
-  const [limit, setLimit] = useState(tab.limit > 0 ? String(tab.limit) : '')
+  /** The applied Simple query, exported as is; null when it doesn't compile. */
+  exportFind: CompiledFind | null
+  /** Rows of the visible Simple page; seeds the export's document count. */
+  exportDocCount: number
+}
 
-  useEffect(() => {
-    setFilter(objOrDefault(tab.filter))
-    setProjection(objOrDefault(tab.projection))
-    setSort(objOrDefault(tab.sort))
-    setPipeline(arrOrDefault(tab.pipeline))
-    setShell(tab.shell)
-    setLimit(tab.limit > 0 ? String(tab.limit) : '')
-  }, [tab.id, tab.filter, tab.projection, tab.sort, tab.pipeline, tab.shell, tab.limit])
+export function QueryToolbar(props: ToolbarProps) {
+  const draft = useTabsStore((s) => s.drafts[props.tab.id])
+  // Tabs and drafts are created and removed in one store update.
+  if (!draft) return null
+  return <QueryForm {...props} draft={draft} />
+}
 
-  // Cache distinct top-level field names from the most recent fetch so
-  // the editor can offer them as completions in any input.
-  useEffect(() => {
-    const names = new Set<string>()
-    for (const env of documents) {
-      for (const key of Object.keys(env.data)) names.add(key)
-    }
-    setDocumentFieldNames(names)
-  }, [documents])
+function QueryForm({
+  tab,
+  draft,
+  onCancel,
+  onRunWrite,
+  loading,
+  writing,
+  completionEnv,
+  uuidEncoding,
+  timezone,
+  exportFind,
+  exportDocCount
+}: ToolbarProps & { draft: QueryDraft }) {
+  const setDraft = useTabsStore((s) => s.setDraft)
+  const run = useTabsStore((s) => s.run)
+  const setFilter = (filter: string) => setDraft(tab.id, { filter })
+  const setProjection = (projection: string) => setDraft(tab.id, { projection })
+  const setSort = (sort: string) => setDraft(tab.id, { sort })
+  const setPipeline = (pipeline: string) => setDraft(tab.id, { pipeline })
+  const setShell = (shell: string) => setDraft(tab.id, { shell })
+  const setLimit = (limit: string) => setDraft(tab.id, { limit })
 
-  const filterStatus = useMemo(() => parseObjectStatus(filter), [filter])
-  const projectionStatus = useMemo(() => parseObjectStatus(projection), [projection])
-  const sortStatus = useMemo(() => parseObjectStatus(sort), [sort])
-  const pipelineStatus = useMemo(() => parsePipelineStatus(pipeline), [pipeline])
-  const shellStatus = useMemo(() => parseShellStatus(shell, tab.coll), [shell, tab.coll])
+  const filterStatus = useMemo(() => parseObjectStatus(draft.filter), [draft.filter])
+  const projectionStatus = useMemo(() => parseObjectStatus(draft.projection), [draft.projection])
+  const sortStatus = useMemo(() => parseObjectStatus(draft.sort), [draft.sort])
+  const pipelineStatus = useMemo(() => parsePipelineStatus(draft.pipeline), [draft.pipeline])
+  const { status: shellStatus, write: shellWrite } = useMemo(
+    () => parseShellDraft(draft.shell),
+    [draft.shell]
+  )
+  const write = draft.mode === 'shell' ? shellWrite : null
 
-  const simpleInvalid =
-    filterStatus.kind === 'invalid' ||
-    projectionStatus.kind === 'invalid' ||
-    sortStatus.kind === 'invalid'
-  const modeInvalid =
-    tab.mode === 'simple'
-      ? simpleInvalid
-      : tab.mode === 'aggregation'
-        ? pipelineStatus.kind !== 'ok'
-        : shellStatus.kind !== 'ok'
+  const blockedReason =
+    draft.mode === 'simple'
+      ? (invalidReason('Filter', filterStatus) ??
+        invalidReason('Projection', projectionStatus) ??
+        invalidReason('Sort', sortStatus))
+      : draft.mode === 'aggregation'
+        ? pipelineStatus.kind === 'empty'
+          ? 'Add a pipeline, e.g. [{ $match: { … } }]'
+          : invalidReason(null, pipelineStatus)
+        : shellStatus.kind === 'empty'
+          ? `Type a command, e.g. ${shellCollectionAccessor(tab.coll)}.find({})`
+          : invalidReason(null, shellStatus)
 
   const apply = (e?: FormEvent) => {
     e?.preventDefault()
-    if (modeInvalid || loading) return
-    // Bumping runEpoch guarantees a fresh fetch even when none of the
-    // mode-specific params changed (e.g. the user pressed Run twice on
-    // the same filter). Tab switches don't go through here.
-    const runEpoch = tab.runEpoch + 1
-    if (tab.mode === 'simple') {
-      const limitNum = Number.parseInt(limit, 10)
-      const nextLimit = Number.isFinite(limitNum) && limitNum > 0 ? limitNum : 0
-      onApply({ filter, projection, sort, skip: 0, limit: nextLimit, runEpoch })
-    } else if (tab.mode === 'aggregation') {
-      onApply({ pipeline, skip: 0, runEpoch })
-    } else {
-      onApply({ shell, skip: 0, runEpoch })
-    }
+    if (blockedReason !== null || loading || writing) return
+    if (write) onRunWrite(write)
+    else run(tab.id)
   }
 
   const setMode = (mode: QueryMode) => {
-    if (mode === tab.mode) return
-    onApply({ mode })
+    if (mode !== draft.mode) setDraft(tab.id, { mode })
   }
 
-  const formatObject = (status: ObjectStatus, setter: (next: string) => void): void => {
-    if (status.kind !== 'ok') return
-    try {
-      setter(JSON.stringify(JSON.parse(status.ejson), null, 2))
-    } catch {
-      // ok-status guarantees parseable EJSON.
-    }
+  const formatOptions: SerializeOptions = { timezone, uuidEncoding, indent: 2, printWidth: 80 }
+  const formatSource = (value: string, setter: (next: string) => void): void => {
+    const formatted = formatMongoSource(value, formatOptions)
+    if (formatted !== null) setter(formatted)
   }
-  const formatPipeline = () => {
-    if (pipelineStatus.kind !== 'ok') return
-    try {
-      setPipeline(JSON.stringify(JSON.parse(pipelineStatus.ejson), null, 2))
-    } catch {
-      // unreachable
-    }
+  const formatShell = (): void => {
+    const formatted = formatShellCommand(draft.shell, formatOptions)
+    if (formatted !== null) setShell(formatted)
   }
 
   return (
     <form onSubmit={apply} className="border-b bg-card/30">
       <div className="flex h-12 items-stretch justify-between border-b pr-4">
-        <ModeTabs current={tab.mode} onChange={setMode} />
+        <ModeTabs current={draft.mode} onChange={setMode} />
         <div className="flex items-center gap-2">
-          {tab.mode === 'simple' && <LimitInput value={limit} onChange={setLimit} />}
-          {loading ? (
+          {draft.mode === 'simple' && <LimitInput value={draft.limit} onChange={setLimit} />}
+          {writing ? (
+            <Tooltip content="A write can't be cancelled; the server finishes it">
+              <Button
+                type="button"
+                size="sm"
+                aria-disabled
+                className="h-8 shrink-0 cursor-not-allowed bg-amber-400/60 px-3 text-amber-950 hover:bg-amber-400/60"
+              >
+                <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                Writing…
+              </Button>
+            </Tooltip>
+          ) : loading ? (
             <Tooltip content="Cancel">
               <Button
                 type="button"
@@ -147,64 +150,99 @@ export function QueryToolbar({
               </Button>
             </Tooltip>
           ) : (
-            <Tooltip content="Run · ⌘/Ctrl-Enter">
-              <Button type="submit" size="sm" className="h-8 shrink-0 px-3">
-                <Play className="h-3.5 w-3.5" />
-                Run
+            <Tooltip
+              content={
+                blockedReason ??
+                (write
+                  ? `Writes to ${writeTargetName(write.op.writes, tab.db)} · ⌘/Ctrl-Enter`
+                  : 'Run · ⌘/Ctrl-Enter')
+              }
+            >
+              <Button
+                type="submit"
+                size="sm"
+                // A double-click's second click would run again once a fast run has finished.
+                onClick={(e) => {
+                  if (e.detail > 1) e.preventDefault()
+                }}
+                // Stays focusable and hoverable so the tooltip can say why Run is blocked.
+                aria-disabled={blockedReason !== null}
+                className={cn(
+                  'h-8 shrink-0 px-3',
+                  write && 'bg-amber-400 text-amber-950 hover:bg-amber-400/90',
+                  blockedReason !== null && 'cursor-not-allowed opacity-50'
+                )}
+              >
+                {write ? <PenLine className="h-3.5 w-3.5" /> : <Play className="h-3.5 w-3.5" />}
+                {write ? 'Run write' : 'Run'}
               </Button>
             </Tooltip>
           )}
-          {tab.mode === 'simple' && (
+          {draft.mode === 'simple' && (
             <ExportButton
               connectionId={tab.connectionId}
               db={tab.db}
               coll={tab.coll}
-              filter={compiledFilter}
-              projection={compiledProjection}
-              sort={compiledSort}
-              currentDocCount={documents.length}
+              filter={exportFind?.filter ?? null}
+              projection={exportFind?.projection ?? null}
+              sort={exportFind?.sort ?? null}
+              currentDocCount={exportDocCount}
               uuidEncoding={uuidEncoding}
               timezone={timezone}
-              disabled={simpleInvalid}
+              disabled={exportFind === null}
             />
           )}
         </div>
       </div>
 
       <div className="grid gap-1.5 px-4 py-2">
-        {tab.mode === 'simple' && (
+        {draft.mode === 'simple' && (
           <SimpleBody
-            filter={filter}
+            tabId={tab.id}
+            completionEnv={completionEnv}
+            filter={draft.filter}
             setFilter={setFilter}
             filterStatus={filterStatus}
-            sort={sort}
+            sort={draft.sort}
             setSort={setSort}
             sortStatus={sortStatus}
-            projection={projection}
+            projection={draft.projection}
             setProjection={setProjection}
             projectionStatus={projectionStatus}
             onSubmit={() => apply()}
-            formatObject={formatObject}
+            formatSource={formatSource}
           />
         )}
 
-        {tab.mode === 'aggregation' && (
-          <AggregationBody
-            pipeline={pipeline}
-            setPipeline={setPipeline}
+        {draft.mode === 'aggregation' && (
+          <SourceEditor
+            modelPath={queryModelUri(tab.id, 'pipeline')}
+            completion={{ kind: 'pipeline', env: completionEnv }}
+            value={draft.pipeline}
+            onChange={setPipeline}
             status={pipelineStatus}
             onSubmit={() => apply()}
-            onFormat={formatPipeline}
+            onFormat={() => formatSource(draft.pipeline, setPipeline)}
+            minHeight={120}
+            maxHeight={400}
+            placeholder={
+              '[\n  { $match: { … } },\n  { $group: { _id: "$type", n: { $sum: 1 } } }\n]'
+            }
           />
         )}
 
-        {tab.mode === 'shell' && (
-          <ShellBody
-            coll={tab.coll}
-            shell={shell}
-            setShell={setShell}
+        {draft.mode === 'shell' && (
+          <SourceEditor
+            modelPath={queryModelUri(tab.id, 'shell')}
+            completion={{ kind: 'shell', env: completionEnv }}
+            value={draft.shell}
+            onChange={setShell}
             status={shellStatus}
             onSubmit={() => apply()}
+            onFormat={formatShell}
+            minHeight={60}
+            maxHeight={240}
+            placeholder={`${shellCollectionAccessor(tab.coll)}.find({ … }).sort({ … }).limit(50)`}
           />
         )}
       </div>
@@ -241,6 +279,8 @@ function ModeTabs({ current, onChange }: { current: QueryMode; onChange: (m: Que
 }
 
 function SimpleBody({
+  tabId,
+  completionEnv,
   filter,
   setFilter,
   filterStatus,
@@ -251,19 +291,21 @@ function SimpleBody({
   setProjection,
   projectionStatus,
   onSubmit,
-  formatObject
+  formatSource
 }: {
+  tabId: string
+  completionEnv: CompletionEnv
   filter: string
   setFilter: (next: string) => void
-  filterStatus: ObjectStatus
+  filterStatus: SourceStatus
   sort: string
   setSort: (next: string) => void
-  sortStatus: ObjectStatus
+  sortStatus: SourceStatus
   projection: string
   setProjection: (next: string) => void
-  projectionStatus: ObjectStatus
+  projectionStatus: SourceStatus
   onSubmit: () => void
-  formatObject: (status: ObjectStatus, setter: (next: string) => void) => void
+  formatSource: (value: string, setter: (next: string) => void) => void
 }) {
   // Sort and Projection share their height: whichever editor's content is
   // taller pushes the shorter one to match. Each reports its natural
@@ -274,122 +316,53 @@ function SimpleBody({
 
   return (
     <>
-      <div className="min-w-0 flex-1">
-        <QueryEditor
-          value={filter}
-          onChange={(next) => setFilter(objOrDefault(next))}
-          onSubmit={onSubmit}
-          onFormat={() => formatObject(filterStatus, setFilter)}
-          hasError={filterStatus.kind === 'invalid'}
-          minHeight={32}
-          maxHeight={180}
-          placeholder='filter ·  { _id: ObjectId("…"), createdAt: { $gt: ISODate("2024-01-01") } }     ⌘/Ctrl-Enter to run'
-          actions={
-            <>
-              {filterStatus.kind === 'invalid' && <ErrorTag title={filterStatus.error} />}
-              <FormatButton
-                disabled={filterStatus.kind !== 'ok'}
-                onClick={() => formatObject(filterStatus, setFilter)}
-              />
-            </>
-          }
-        />
-      </div>
+      <SourceEditor
+        modelPath={queryModelUri(tabId, 'filter')}
+        completion={{ kind: 'filter', env: completionEnv }}
+        value={filter}
+        onChange={setFilter}
+        status={filterStatus}
+        onSubmit={onSubmit}
+        onFormat={() => formatSource(filter, setFilter)}
+        minHeight={32}
+        maxHeight={180}
+        placeholder='filter ·  { _id: ObjectId("…"), createdAt: { $gt: ISODate("2024-01-01") } }     ⌘/Ctrl-Enter to run'
+      />
 
       <div className="flex flex-wrap items-stretch gap-1.5">
         <OptionRow
+          modelPath={queryModelUri(tabId, 'sort')}
+          completion={{ kind: 'sort', env: completionEnv }}
           icon={<ArrowDownUp className="h-3 w-3" />}
           label="Sort"
           placeholder="{ createdAt: -1 }"
           value={sort}
           onChange={setSort}
           onSubmit={onSubmit}
-          onFormat={() => formatObject(sortStatus, setSort)}
+          onFormat={() => formatSource(sort, setSort)}
           status={sortStatus}
           minHeight={sharedRowH}
-          onContentHeight={setSortContentH}
+          onContentHeightChange={setSortContentH}
         />
         <OptionRow
+          modelPath={queryModelUri(tabId, 'projection')}
+          completion={{ kind: 'projection', env: completionEnv }}
           icon={<Eye className="h-3 w-3" />}
           label="Projection"
           placeholder="{ name: 1, _id: 0 }"
           value={projection}
           onChange={setProjection}
           onSubmit={onSubmit}
-          onFormat={() => formatObject(projectionStatus, setProjection)}
+          onFormat={() => formatSource(projection, setProjection)}
           status={projectionStatus}
           minHeight={sharedRowH}
-          onContentHeight={setProjContentH}
+          onContentHeightChange={setProjContentH}
         />
       </div>
     </>
   )
 }
 
-function AggregationBody({
-  pipeline,
-  setPipeline,
-  status,
-  onSubmit,
-  onFormat
-}: {
-  pipeline: string
-  setPipeline: (next: string) => void
-  status: PipelineStatus
-  onSubmit: () => void
-  onFormat: () => void
-}) {
-  return (
-    <div className="min-w-0 flex-1">
-      <QueryEditor
-        value={pipeline}
-        onChange={(next) => setPipeline(arrOrDefault(next))}
-        onSubmit={onSubmit}
-        onFormat={onFormat}
-        hasError={status.kind === 'invalid'}
-        minHeight={120}
-        maxHeight={400}
-        placeholder={'[\n  { $match: { … } },\n  { $group: { _id: "$type", n: { $sum: 1 } } }\n]'}
-        actions={
-          <>
-            {status.kind === 'invalid' && <ErrorTag title={status.error} />}
-            <FormatButton disabled={status.kind !== 'ok'} onClick={onFormat} />
-          </>
-        }
-      />
-    </div>
-  )
-}
-
-function ShellBody({
-  coll,
-  shell,
-  setShell,
-  status,
-  onSubmit
-}: {
-  coll: string
-  shell: string
-  setShell: (next: string) => void
-  status: ShellStatus
-  onSubmit: () => void
-}) {
-  return (
-    <div className="min-w-0 flex-1">
-      <QueryEditor
-        value={shell}
-        onChange={setShell}
-        onSubmit={onSubmit}
-        hasError={status.kind === 'invalid'}
-        minHeight={60}
-        maxHeight={240}
-        placeholder={`db.${coll}.find({ … }).sort({ … }).limit(50)`}
-        actions={<>{status.kind === 'invalid' && <ErrorTag title={status.error} />}</>}
-      />
-    </div>
-  )
-}
-
 function LimitInput({ value, onChange }: { value: string; onChange: (next: string) => void }) {
   return (
     <Tooltip content="Empty or 0 = fetch all matching documents">
@@ -413,58 +386,54 @@ function LimitInput({ value, onChange }: { value: string; onChange: (next: strin
 function OptionRow({
   icon,
   label,
-  placeholder,
-  value,
-  onChange,
-  onSubmit,
-  onFormat,
-  status,
-  minHeight,
-  onContentHeight
-}: {
-  icon: React.ReactNode
-  label: string
-  placeholder: string
-  value: string
-  onChange: (next: string) => void
-  onSubmit: () => void
-  onFormat: () => void
-  status: ObjectStatus
-  minHeight: number
-  onContentHeight: (px: number) => void
-}) {
+  ...editor
+}: Omit<SourceEditorProps, 'maxHeight'> & { icon: React.ReactNode; label: string }) {
   return (
     <div className="flex min-w-0 flex-1 basis-[280px] items-stretch gap-1.5">
       <div className="flex shrink-0 items-center gap-1 rounded-md border border-input bg-muted/30 px-2 text-[10px] uppercase tracking-wider text-muted-foreground">
         {icon}
         {label}
       </div>
-      <div className="min-w-0 flex-1">
-        <QueryEditor
-          value={value}
-          onChange={(next) => onChange(objOrDefault(next))}
-          onSubmit={onSubmit}
-          onFormat={onFormat}
-          hasError={status.kind === 'invalid'}
-          minHeight={minHeight}
-          maxHeight={120}
-          placeholder={placeholder}
-          onContentHeightChange={onContentHeight}
-          actions={
-            <>
-              {status.kind === 'invalid' && <ErrorTag title={status.error} />}
-              <FormatButton disabled={status.kind !== 'ok'} onClick={onFormat} />
-            </>
-          }
-        />
-      </div>
+      <SourceEditor {...editor} maxHeight={120} />
+    </div>
+  )
+}
+
+type SourceEditorProps = {
+  modelPath: string
+  completion: CompletionBinding
+  value: string
+  onChange: (next: string) => void
+  status: SourceStatus
+  onSubmit: () => void
+  onFormat: () => void
+  minHeight: number
+  maxHeight: number
+  placeholder: string
+  onContentHeightChange?: (px: number) => void
+}
+
+function SourceEditor({ status, onFormat, ...editor }: SourceEditorProps) {
+  return (
+    <div className="min-w-0 flex-1">
+      <QueryEditor
+        {...editor}
+        onFormat={onFormat}
+        hasError={status.kind === 'invalid'}
+        actions={
+          <>
+            {status.kind === 'invalid' && <ErrorTag title={status.error} />}
+            <FormatButton disabled={status.kind !== 'ok'} onClick={onFormat} />
+          </>
+        }
+      />
     </div>
   )
 }
 
 function FormatButton({ disabled, onClick }: { disabled: boolean; onClick: () => void }) {
   return (
-    <Tooltip content="Format · Shift+Alt+F">
+    <Tooltip content="Format · Shift+Alt+F · removes comments">
       <button
         type="button"
         onClick={onClick}
@@ -494,10 +463,14 @@ function ErrorTag({ title }: { title: string }) {
   )
 }
 
-type ObjectStatus =
-  { kind: 'empty' } | { kind: 'ok'; ejson: string } | { kind: 'invalid'; error: string }
+type SourceStatus = { kind: 'empty' } | { kind: 'ok' } | { kind: 'invalid'; error: string }
+
+function invalidReason(label: string | null, status: SourceStatus): string | null {
+  if (status.kind !== 'invalid') return null
+  return label === null ? status.error : `${label}: ${status.error}`
+}
 
-function parseObjectStatus(value: string): ObjectStatus {
+function parseObjectStatus(value: string): SourceStatus {
   const trimmed = value.trim()
   if (trimmed.length === 0) return { kind: 'empty' }
   const result = parseMongoQuery(trimmed)
@@ -505,43 +478,19 @@ function parseObjectStatus(value: string): ObjectStatus {
   if (result.value === null || typeof result.value !== 'object' || Array.isArray(result.value)) {
     return { kind: 'invalid', error: 'Must be an object' }
   }
-  return { kind: 'ok', ejson: result.ejson }
+  return { kind: 'ok' }
 }
 
-type PipelineStatus =
-  { kind: 'empty' } | { kind: 'ok'; ejson: string } | { kind: 'invalid'; error: string }
-
-function parsePipelineStatus(value: string): PipelineStatus {
-  const trimmed = value.trim()
-  if (trimmed.length === 0) return { kind: 'empty' }
-  const result = parseMongoQuery(trimmed)
-  if (!result.ok) return { kind: 'invalid', error: result.error }
-  if (!Array.isArray(result.value)) {
-    return { kind: 'invalid', error: 'Must be an array of stage objects' }
-  }
-  for (const stage of result.value) {
-    if (typeof stage !== 'object' || stage === null || Array.isArray(stage)) {
-      return { kind: 'invalid', error: 'Each stage must be an object' }
-    }
-  }
-  return { kind: 'ok', ejson: result.ejson }
+function parsePipelineStatus(value: string): SourceStatus {
+  if (value.trim().length === 0) return { kind: 'empty' }
+  const result = compilePipelineSource(value)
+  return result.ok ? { kind: 'ok' } : { kind: 'invalid', error: result.error }
 }
 
-type ShellStatus =
-  | { kind: 'empty' }
-  | { kind: 'ok'; parsed: ShellParseResult & { ok: true } }
-  | { kind: 'invalid'; error: string }
-
-function parseShellStatus(value: string, expectedColl: string): ShellStatus {
-  const trimmed = value.trim()
-  if (trimmed.length === 0) return { kind: 'empty' }
-  const parsed = parseShellCommand(trimmed)
-  if (!parsed.ok) return { kind: 'invalid', error: parsed.error }
-  if (parsed.coll !== expectedColl) {
-    return {
-      kind: 'invalid',
-      error: `Collection mismatch: this tab is "${expectedColl}", command targets "${parsed.coll}"`
-    }
-  }
-  return { kind: 'ok', parsed }
+function parseShellDraft(value: string): { status: SourceStatus; write: ShellWriteCommand | null } {
+  if (value.trim().length === 0) return { status: { kind: 'empty' }, write: null }
+  const result = parseShellCommand(value)
+  if (!result.ok) return { status: { kind: 'invalid', error: result.error }, write: null }
+  const { coll, op } = result.command
+  return { status: { kind: 'ok' }, write: op.kind === 'write' ? { coll, op } : null }
 }
diff --git a/src/renderer/src/features/collection/RenameCollectionDialog.tsx b/src/renderer/src/features/collection/RenameCollectionDialog.tsx
index c1f8c8a..febb91a 100644
--- a/src/renderer/src/features/collection/RenameCollectionDialog.tsx
+++ b/src/renderer/src/features/collection/RenameCollectionDialog.tsx
@@ -14,7 +14,7 @@ import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
+import { queryKeys, removeNamespaceQueries } from '@/lib/queryClient'
 import { useTabsStore } from '@/store/tabs'
 
 type Props = {
@@ -54,6 +54,7 @@ export function RenameCollectionDialog({ open, connectionId, db, coll, onClose }
     mutationFn: () => api.collections.rename({ connectionId, db, coll, newName: name.trim() }),
     onSuccess: () => {
       renameTab(connectionId, db, coll, name.trim())
+      removeNamespaceQueries(queryClient, connectionId, db, coll)
       void queryClient.invalidateQueries({ queryKey: queryKeys.collections(connectionId, db) })
       toast.success(`Renamed to ${name.trim()}`)
       onClose()
diff --git a/src/renderer/src/features/collection/ResultStates.tsx b/src/renderer/src/features/collection/ResultStates.tsx
new file mode 100644
index 0000000..f242339
--- /dev/null
+++ b/src/renderer/src/features/collection/ResultStates.tsx
@@ -0,0 +1,270 @@
+import { CircleCheck, CircleSlash, Loader2, ServerCrash } from 'lucide-react'
+import { serializeMongoValue } from '@/lib/mongoQuerySerialize'
+import type { ShellWriteResult } from '@/lib/queryRun'
+import {
+  SHELL_READ_METHODS,
+  shellCollectionAccessor,
+  writeTargetName,
+  type ShellCountMethod
+} from '@/lib/shellParser'
+import { RESULT_CAP, WRITE_METHODS, type UuidEncoding } from '@shared/types'
+
+const CAP_TEXT = RESULT_CAP.toLocaleString()
+
+/** Shown before the visible mode was ever run in this tab. */
+export function IdleState({
+  mode,
+  coll,
+  db
+}: {
+  mode: 'aggregation' | 'shell'
+  coll: string
+  db: string
+}) {
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <div className="grid max-w-xl gap-2 text-sm text-muted-foreground">
+        {mode === 'aggregation' ? (
+          <>
+            <p className="text-foreground">Write a pipeline above and press Run (⌘/Ctrl-Enter).</p>
+            <Example>{'[{ $match: { status: "active" } }, { $sortByCount: "$type" }]'}</Example>
+            <p className="text-xs">
+              Returns at most {CAP_TEXT} rows. Only read pipelines run here; run $out and $merge in
+              Shell mode.
+            </p>
+          </>
+        ) : (
+          <>
+            <p className="text-foreground">Type a command above and press Run (⌘/Ctrl-Enter).</p>
+            <Example>{`${shellCollectionAccessor(coll)}.find({ … }).sort({ … }).limit(50)`}</Example>
+            <p className="text-xs">
+              Reads: <span className="font-mono">{SHELL_READ_METHODS.join(', ')}</span>. They return
+              at most {CAP_TEXT} rows.
+            </p>
+            <p className="text-xs">
+              Writes: <span className="font-mono">{WRITE_METHODS.join(', ')}</span>, and aggregate
+              ending in <span className="font-mono">$out</span> /{' '}
+              <span className="font-mono">$merge</span>. A write runs once per Run and can&apos;t be
+              cancelled; one that changes every document or replaces a collection asks first.
+            </p>
+            <p className="text-xs">
+              Any collection of <span className="font-mono text-foreground">{db}</span>:{' '}
+              <span className="font-mono">db.&lt;name&gt;, db.getCollection(&quot;name&quot;)</span>
+              .
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function Example({ children }: { children: string }) {
+  return (
+    <code className="block rounded-md border bg-card/40 px-3 py-2 font-mono text-xs text-foreground/90">
+      {children}
+    </code>
+  )
+}
+
+/** A one-line note centred in the result area. */
+export function Notice({ icon, children }: { icon?: React.ReactNode; children: React.ReactNode }) {
+  return (
+    <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
+      <span className="flex items-center gap-2">
+        {icon}
+        {children}
+      </span>
+    </div>
+  )
+}
+
+export function LoadingState({ label = 'Loading…' }: { label?: string }) {
+  return <Notice icon={<Loader2 className="h-4 w-4 animate-spin" />}>{label}</Notice>
+}
+
+export function CancelledState() {
+  return (
+    <Notice icon={<CircleSlash className="h-4 w-4" />}>
+      Run cancelled. Press Run to start it again.
+    </Notice>
+  )
+}
+
+export function ErrorState({
+  message,
+  title = 'Query failed'
+}: {
+  message: string
+  title?: string
+}) {
+  return (
+    <div className="m-6 flex items-start gap-3 rounded-md border border-destructive/30 bg-destructive/5 p-4 text-sm text-destructive">
+      <ServerCrash className="mt-0.5 h-4 w-4" />
+      <div>
+        <div className="font-medium">{title}</div>
+        <div className="text-xs opacity-80">{message}</div>
+      </div>
+    </div>
+  )
+}
+
+/** Result of a shell count method; `estimated` comes from collection metadata. */
+export function CountResult({
+  count,
+  estimated,
+  method,
+  coll
+}: {
+  count: number
+  estimated: boolean
+  method: ShellCountMethod
+  coll: string
+}) {
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <div className="grid justify-items-center gap-1 text-center">
+        <div className="font-mono text-4xl font-semibold tabular-nums tracking-tight text-foreground">
+          {estimated && '~'}
+          {count.toLocaleString()}
+        </div>
+        <div className="text-sm text-muted-foreground">
+          {estimated ? (
+            <>
+              documents in <span className="font-mono text-foreground">{coll}</span> · estimated
+              from collection metadata
+            </>
+          ) : (
+            <>
+              documents match in <span className="font-mono text-foreground">{coll}</span>
+            </>
+          )}
+        </div>
+        <div className="font-mono text-[11px] text-muted-foreground/70">{method}()</div>
+      </div>
+    </div>
+  )
+}
+
+const COUNT_ORDER = ['inserted', 'matched', 'modified', 'upserted', 'deleted'] as const
+
+/** Outcome of a shell write: the counters that apply and the written ids. */
+export function WriteResult({
+  result,
+  db,
+  uuidEncoding,
+  timezone,
+  children
+}: {
+  result: ShellWriteResult
+  /** The tab's database; a target elsewhere is named with its database. */
+  db: string
+  uuidEncoding: UuidEncoding
+  timezone: string
+  /** The document a findOneAnd* method returned, shown below the outcome. */
+  children?: React.ReactNode
+}) {
+  const target = writeTargetName(result.writes, db)
+  const counts = COUNT_ORDER.flatMap((name) => {
+    const value = result.counts[name]
+    return value === undefined ? [] : [{ name, value }]
+  })
+  const outcome =
+    result.method === 'aggregate' ? (
+      <>
+        Output written to <span className="font-mono text-foreground">{target}</span>
+      </>
+    ) : (
+      <>
+        <span className="font-mono">{result.method}()</span> on{' '}
+        <span className="font-mono text-foreground">{target}</span>
+      </>
+    )
+  const ids = <WrittenIds result={result} uuidEncoding={uuidEncoding} timezone={timezone} />
+
+  if (result.returned !== null) {
+    return (
+      <div className="flex h-full flex-col">
+        <div className="grid shrink-0 gap-2 border-b bg-card/30 px-4 py-2 text-xs text-muted-foreground">
+          <div className="flex flex-wrap items-center gap-x-4 gap-y-1">
+            <span className="flex items-center gap-1.5">
+              <CircleCheck className="h-3.5 w-3.5 text-success" />
+              {outcome}
+            </span>
+            {counts.map(({ name, value }) => (
+              <span key={name}>
+                <span className="font-mono tabular-nums text-foreground">
+                  {value.toLocaleString()}
+                </span>{' '}
+                {name}
+              </span>
+            ))}
+          </div>
+          {ids}
+        </div>
+        <div className="min-h-0 flex-1">{children}</div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <div className="grid w-full max-w-xl justify-items-center gap-3 text-center">
+        {counts.length > 0 && (
+          <dl className="flex flex-wrap justify-center gap-x-10 gap-y-3">
+            {counts.map(({ name, value }) => (
+              <div key={name} className="grid justify-items-center">
+                <dt className="order-last text-[11px] uppercase tracking-wider text-muted-foreground">
+                  {name}
+                </dt>
+                <dd className="font-mono text-4xl font-semibold tabular-nums tracking-tight text-foreground">
+                  {value.toLocaleString()}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        )}
+        <div className="flex items-center gap-1.5 text-sm text-muted-foreground">
+          <CircleCheck className="h-4 w-4 text-success" />
+          {outcome}
+        </div>
+        {ids}
+      </div>
+    </div>
+  )
+}
+
+function WrittenIds({
+  result,
+  uuidEncoding,
+  timezone
+}: {
+  result: ShellWriteResult
+  uuidEncoding: UuidEncoding
+  timezone: string
+}) {
+  const { ids, counts } = result
+  if (ids.length === 0) return null
+  const inserted = counts.inserted ?? 0
+  const upserted = counts.upserted ?? 0
+  const kind =
+    inserted > 0 && upserted > 0 ? 'Inserted and upserted' : upserted > 0 ? 'Upserted' : 'Inserted'
+  const more = inserted + upserted - ids.length
+  return (
+    <div className="grid w-full gap-1 text-left">
+      <div className="text-[11px] uppercase tracking-wider text-muted-foreground">
+        {kind} _id{ids.length === 1 ? '' : 's'}
+      </div>
+      <ul className="max-h-40 overflow-auto rounded-md border bg-card/40 px-3 py-2 font-mono text-xs text-foreground/90">
+        {ids.map((id, index) => (
+          <li key={index} className="truncate">
+            {serializeMongoValue(JSON.parse(id), { indent: 0, uuidEncoding, timezone })}
+          </li>
+        ))}
+        {result.idsTruncated && more > 0 && (
+          <li className="text-muted-foreground">+{more.toLocaleString()} more</li>
+        )}
+      </ul>
+    </div>
+  )
+}
diff --git a/src/renderer/src/features/collection/StatusBar.test.tsx b/src/renderer/src/features/collection/StatusBar.test.tsx
new file mode 100644
index 0000000..2abd0fa
--- /dev/null
+++ b/src/renderer/src/features/collection/StatusBar.test.tsx
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { StatusBar, type StatusSummary } from './StatusBar'
+
+type Paged = Extract<StatusSummary, { kind: 'paged' }>
+
+const paged = (extra: Partial<Paged> = {}): Paged => ({
+  kind: 'paged',
+  count: 1000,
+  countError: null,
+  estimated: false,
+  pageSize: 100,
+  skip: 100,
+  pageDocs: 100,
+  busy: false,
+  onJump: () => undefined,
+  ...extra
+})
+
+const render = (summary: StatusSummary, loading = false): string =>
+  renderToStaticMarkup(<StatusBar loading={loading} tookMs={12} summary={summary} />)
+
+const disabledPagerButtons = (html: string): string[] =>
+  [...html.matchAll(/<button[^>]*>/g)]
+    .filter((tag) => tag[0].includes('disabled=""'))
+    .map((tag) => /aria-label="(\w+)"/.exec(tag[0])?.[1] ?? '?')
+
+describe('StatusBar pager', () => {
+  it('can page both ways from a middle page', () => {
+    expect(disabledPagerButtons(render(paged()))).toEqual([])
+  })
+
+  it('locks every pager button while a page is loading', () => {
+    expect(disabledPagerButtons(render(paged({ busy: true }), true))).toEqual([
+      'First',
+      'Prev',
+      'Next',
+      'Last'
+    ])
+  })
+})
+
+describe('StatusBar count', () => {
+  it('names the count as unavailable once it failed', () => {
+    const html = render(paged({ count: undefined, countError: '$where is not allowed' }))
+    expect(html).toContain('count unavailable')
+  })
+
+  it('shows no count note while the count is still pending', () => {
+    const html = render(paged({ count: undefined }), true)
+    expect(html).not.toContain('count unavailable')
+    expect(html).toContain('running…')
+  })
+
+  it('shows the total when the count is known', () => {
+    expect(render(paged({ count: 999 }))).toContain('999 docs')
+  })
+})
diff --git a/src/renderer/src/features/collection/StatusBar.tsx b/src/renderer/src/features/collection/StatusBar.tsx
index b61367e..95aa29e 100644
--- a/src/renderer/src/features/collection/StatusBar.tsx
+++ b/src/renderer/src/features/collection/StatusBar.tsx
@@ -1,94 +1,173 @@
 import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight, Loader2 } from 'lucide-react'
 import { Button } from '@/components/ui/button'
+import { Tooltip } from '@/components/ui/tooltip'
 import { cn } from '@/lib/utils'
+import { RESULT_CAP } from '@shared/types'
+
+/** What the status bar describes: a paged Simple find, a capped result, or nothing countable. */
+export type StatusSummary =
+  | {
+      kind: 'paged'
+      count: number | undefined
+      /** Why the count failed; null while it is pending, cancelled or known. */
+      countError: string | null
+      estimated: boolean
+      /** 0 = no limit. */
+      pageSize: number
+      skip: number
+      pageDocs: number
+      /** A page is loading; paging waits for it. */
+      busy: boolean
+      onJump: (skip: number) => void
+    }
+  | {
+      kind: 'rows'
+      rows: number
+      truncated: boolean
+      /** How to reach the rows past the cap. */
+      truncationHint: string
+      /** Why rows can't be edited or deleted; null when they can. */
+      readOnlyReason: string | null
+      /** The rows' collection when it isn't the tab's. */
+      foreignColl: string | null
+    }
+  | { kind: 'none' }
 
 export function StatusBar({
   loading,
-  count,
-  estimated,
-  pageSize,
-  skip,
-  pageDocs,
   tookMs,
-  onJump
+  summary
 }: {
   loading: boolean
-  count: number | undefined
-  estimated: boolean
-  /** 0 = no limit. */
-  pageSize: number
-  skip: number
-  pageDocs: number
   tookMs: number | undefined
-  onJump: (skip: number) => void
+  summary: StatusSummary
 }) {
-  const hasLimit = pageSize > 0
-  const totalPages =
-    hasLimit && count !== undefined ? Math.max(1, Math.ceil(count / pageSize)) : undefined
-  const currentPage = hasLimit ? Math.floor(skip / pageSize) + 1 : 1
-
-  const canPrev = hasLimit && skip > 0
-  const canNext = hasLimit
-    ? count !== undefined
-      ? skip + pageSize < count
-      : pageDocs === pageSize
-    : false
-
   return (
     <div className="flex h-9 items-center justify-between border-b bg-card/40 px-4 text-[11px] text-muted-foreground">
       <div className="flex items-center gap-3 font-mono">
-        {loading ? (
-          <span className="flex items-center gap-1.5">
-            <Loader2 className="h-3 w-3 animate-spin" />
-            running…
-          </span>
-        ) : count !== undefined ? (
-          <span>
-            {estimated && '~'}
-            {count.toLocaleString()} docs
-          </span>
-        ) : null}
-        {totalPages !== undefined && (
-          <span>
-            page {currentPage}/{totalPages}
-          </span>
+        {summary.kind === 'paged' ? (
+          <PagedInfo summary={summary} loading={loading} />
+        ) : loading ? (
+          <Running />
+        ) : (
+          summary.kind === 'rows' && <RowsInfo summary={summary} />
         )}
-        {!hasLimit && pageDocs > 0 && <span>showing all</span>}
         {tookMs !== undefined && <span>{tookMs} ms</span>}
       </div>
+      {summary.kind === 'paged' && summary.pageSize > 0 && <Pager summary={summary} />}
+    </div>
+  )
+}
+
+type PagedSummary = Extract<StatusSummary, { kind: 'paged' }>
+
+const pageCount = ({ count, pageSize }: PagedSummary): number | undefined =>
+  pageSize > 0 && count !== undefined ? Math.max(1, Math.ceil(count / pageSize)) : undefined
+
+function Running() {
+  return (
+    <span className="flex items-center gap-1.5">
+      <Loader2 className="h-3 w-3 animate-spin" />
+      running…
+    </span>
+  )
+}
 
-      {hasLimit && (
-        <div className="flex items-center gap-0.5">
-          <PageBtn onClick={() => onJump(0)} disabled={!canPrev} label="First">
-            <ChevronsLeft className="h-3.5 w-3.5" />
-          </PageBtn>
-          <PageBtn
-            onClick={() => onJump(Math.max(0, skip - pageSize))}
-            disabled={!canPrev}
-            label="Prev"
-          >
-            <ChevronLeft className="h-3.5 w-3.5" />
-          </PageBtn>
-          <PageBtn onClick={() => onJump(skip + pageSize)} disabled={!canNext} label="Next">
-            <ChevronRight className="h-3.5 w-3.5" />
-          </PageBtn>
-          <PageBtn
-            onClick={() => {
-              if (count === undefined || totalPages === undefined) return
-              const last = (totalPages - 1) * pageSize
-              onJump(last)
-            }}
-            disabled={!canNext || count === undefined}
-            label="Last"
-          >
-            <ChevronsRight className="h-3.5 w-3.5" />
-          </PageBtn>
-        </div>
+function PagedInfo({ summary, loading }: { summary: PagedSummary; loading: boolean }) {
+  const { count, countError, estimated, pageSize, skip, pageDocs } = summary
+  const totalPages = pageCount(summary)
+  return (
+    <>
+      {loading ? (
+        <Running />
+      ) : count !== undefined ? (
+        <span>
+          {estimated && '~'}
+          {count.toLocaleString()} docs
+        </span>
+      ) : (
+        countError && (
+          <Tooltip content={countError}>
+            <span className="rounded-sm bg-amber-400/15 px-1.5 py-0.5 text-amber-300">
+              count unavailable
+            </span>
+          </Tooltip>
+        )
+      )}
+      {totalPages !== undefined && (
+        <span>
+          page {Math.floor(skip / pageSize) + 1}/{totalPages}
+        </span>
       )}
+      {pageSize === 0 && pageDocs > 0 && <span>showing all</span>}
+    </>
+  )
+}
+
+function Pager({ summary }: { summary: PagedSummary }) {
+  const { count, pageSize, skip, pageDocs, busy, onJump } = summary
+  const totalPages = pageCount(summary)
+  // Paging past a loading page would leave its server op running for nothing.
+  const canPrev = !busy && skip > 0
+  const canNext = !busy && (count !== undefined ? skip + pageSize < count : pageDocs === pageSize)
+  return (
+    <div className="flex items-center gap-0.5">
+      <PageBtn onClick={() => onJump(0)} disabled={!canPrev} label="First">
+        <ChevronsLeft className="h-3.5 w-3.5" />
+      </PageBtn>
+      <PageBtn
+        onClick={() => onJump(Math.max(0, skip - pageSize))}
+        disabled={!canPrev}
+        label="Prev"
+      >
+        <ChevronLeft className="h-3.5 w-3.5" />
+      </PageBtn>
+      <PageBtn onClick={() => onJump(skip + pageSize)} disabled={!canNext} label="Next">
+        <ChevronRight className="h-3.5 w-3.5" />
+      </PageBtn>
+      <PageBtn
+        onClick={() => {
+          if (totalPages !== undefined) onJump((totalPages - 1) * pageSize)
+        }}
+        disabled={!canNext || totalPages === undefined}
+        label="Last"
+      >
+        <ChevronsRight className="h-3.5 w-3.5" />
+      </PageBtn>
     </div>
   )
 }
 
+function RowsInfo({ summary }: { summary: Extract<StatusSummary, { kind: 'rows' }> }) {
+  const cap = RESULT_CAP.toLocaleString()
+  return (
+    <>
+      <span>
+        {summary.rows.toLocaleString()} result{summary.rows === 1 ? '' : 's'}
+      </span>
+      {summary.truncated && (
+        <Tooltip content={`Only the first ${cap} results are shown. ${summary.truncationHint}`}>
+          <span className="rounded-sm bg-amber-400/15 px-1.5 py-0.5 text-amber-300">
+            first {cap}
+          </span>
+        </Tooltip>
+      )}
+      {summary.readOnlyReason !== null && (
+        <Tooltip content={summary.readOnlyReason}>
+          <span className="rounded-sm bg-muted/60 px-1.5 py-0.5">read-only</span>
+        </Tooltip>
+      )}
+      {summary.foreignColl !== null && (
+        <Tooltip content="Rows come from this collection; edits and deletes target it.">
+          <span className="rounded-sm bg-primary/15 px-1.5 py-0.5 text-primary">
+            {summary.foreignColl}
+          </span>
+        </Tooltip>
+      )}
+    </>
+  )
+}
+
 function PageBtn({
   onClick,
   disabled,
diff --git a/src/renderer/src/features/connections/ConnectionFormDialog.tsx b/src/renderer/src/features/connections/ConnectionFormDialog.tsx
index 78cec17..b9807c1 100644
--- a/src/renderer/src/features/connections/ConnectionFormDialog.tsx
+++ b/src/renderer/src/features/connections/ConnectionFormDialog.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from 'react'
-import { useMutation, useQueryClient } from '@tanstack/react-query'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
 import { toast } from 'sonner'
 import {
   CheckCircle2,
@@ -33,9 +33,17 @@ import { TimezoneSelect } from './TimezoneSelect'
 import { api, ApiError } from '@/lib/api'
 import { queryKeys } from '@/lib/queryClient'
 import { cn } from '@/lib/utils'
+import {
+  canReuseServiceTokenSecret,
+  cloudflaredTunnelProblems,
+  INVALID_CLOUDFLARED_PATH_MESSAGE,
+  isCloudflaredExecutable
+} from '@shared/cloudflared'
 import {
   DEFAULT_SSH_PORT,
   type AuthMechanism,
+  type CloudflaredAuthMethod,
+  type CloudflaredTunnelInput,
   type ConnectionConfig,
   type ConnectionInput,
   type ConnectionTestResult,
@@ -45,8 +53,16 @@ import {
   type UuidEncoding
 } from '@shared/types'
 
+type TunnelKind = 'none' | 'ssh' | 'cloudflared'
+
+const TUNNEL_HINTS: Record<TunnelKind, string> = {
+  none: 'Connect to the hosts in the connection string directly.',
+  ssh: 'Reach hosts that are only routable from an SSH server — including every member of a replica set.',
+  cloudflared:
+    'MongoBench runs cloudflared access tcp on a free local port and connects through it — no host or port to enter.'
+}
+
 type SshFormState = {
-  enabled: boolean
   host: string
   /** Text, like the other numeric inputs in this form. */
   port: string
@@ -57,6 +73,17 @@ type SshFormState = {
   passphrase: string
 }
 
+type CloudflaredFormState = {
+  hostname: string
+  authMethod: CloudflaredAuthMethod
+  serviceTokenId: string
+  serviceTokenSecret: string
+  /** Blank = cloudflared from PATH. */
+  binaryPath: string
+  /** binaryPath as of the last blur or Browse: every version check starts a cloudflared process. */
+  checkedPath: string
+}
+
 type FormState = {
   name: string
   uri: string
@@ -79,11 +106,13 @@ type FormState = {
   socketTimeoutMS: string
   retryWrites: 'default' | 'on' | 'off'
   retryReads: 'default' | 'on' | 'off'
+  /** The one tunnel in use; the other section keeps its settings, switched off. */
+  tunnel: TunnelKind
   ssh: SshFormState
+  cloudflared: CloudflaredFormState
 }
 
 const emptySsh = (): SshFormState => ({
-  enabled: false,
   host: '',
   port: String(DEFAULT_SSH_PORT),
   username: '',
@@ -93,6 +122,15 @@ const emptySsh = (): SshFormState => ({
   passphrase: ''
 })
 
+const emptyCloudflared = (): CloudflaredFormState => ({
+  hostname: '',
+  authMethod: 'browser',
+  serviceTokenId: '',
+  serviceTokenSecret: '',
+  binaryPath: '',
+  checkedPath: ''
+})
+
 const emptyForm = (): FormState => ({
   name: '',
   uri: 'mongodb://localhost:27017',
@@ -115,7 +153,9 @@ const emptyForm = (): FormState => ({
   socketTimeoutMS: '',
   retryWrites: 'default',
   retryReads: 'default',
-  ssh: emptySsh()
+  tunnel: 'none',
+  ssh: emptySsh(),
+  cloudflared: emptyCloudflared()
 })
 
 const fromConnection = (conn: ConnectionConfig): FormState => ({
@@ -140,11 +180,11 @@ const fromConnection = (conn: ConnectionConfig): FormState => ({
   socketTimeoutMS: conn.socketTimeoutMS !== undefined ? String(conn.socketTimeoutMS) : '',
   retryWrites: conn.retryWrites === undefined ? 'default' : conn.retryWrites ? 'on' : 'off',
   retryReads: conn.retryReads === undefined ? 'default' : conn.retryReads ? 'on' : 'off',
+  tunnel: conn.ssh?.enabled ? 'ssh' : conn.cloudflared?.enabled ? 'cloudflared' : 'none',
   ssh:
     conn.ssh === undefined
       ? emptySsh()
       : {
-          enabled: conn.ssh.enabled,
           host: conn.ssh.host,
           port: String(conn.ssh.port ?? DEFAULT_SSH_PORT),
           username: conn.ssh.username,
@@ -153,6 +193,17 @@ const fromConnection = (conn: ConnectionConfig): FormState => ({
           // Secrets never come back from main; blank means "keep".
           password: '',
           passphrase: ''
+        },
+  cloudflared:
+    conn.cloudflared === undefined
+      ? emptyCloudflared()
+      : {
+          hostname: conn.cloudflared.hostname,
+          authMethod: conn.cloudflared.authMethod,
+          serviceTokenId: conn.cloudflared.serviceTokenId ?? '',
+          serviceTokenSecret: '',
+          binaryPath: conn.cloudflared.binaryPath ?? '',
+          checkedPath: (conn.cloudflared.binaryPath ?? '').trim()
         }
 })
 
@@ -168,16 +219,16 @@ const parseInt = (raw: string): number | undefined => {
  * section is still sent, so switching the tunnel off keeps its settings for
  * the next time it is switched on.
  */
-function buildSshInput(ssh: SshFormState): SshTunnelInput | undefined {
+function buildSshInput(ssh: SshFormState, enabled: boolean): SshTunnelInput | undefined {
   const host = ssh.host.trim()
   const username = ssh.username.trim()
   const privateKeyPath = ssh.privateKeyPath.trim()
   const touched = host.length > 0 || username.length > 0 || privateKeyPath.length > 0
-  if (!ssh.enabled && !touched) return undefined
+  if (!enabled && !touched) return undefined
 
   const port = parseInt(ssh.port)
   return {
-    enabled: ssh.enabled,
+    enabled,
     host,
     ...(port !== undefined ? { port } : {}),
     username,
@@ -188,6 +239,29 @@ function buildSshInput(ssh: SshFormState): SshTunnelInput | undefined {
   }
 }
 
+/** Same contract as buildSshInput: undefined only while switched off and untouched. */
+function buildCloudflaredInput(
+  cf: CloudflaredFormState,
+  enabled: boolean
+): CloudflaredTunnelInput | undefined {
+  const hostname = cf.hostname.trim()
+  const serviceTokenId = cf.serviceTokenId.trim()
+  const binaryPath = cf.binaryPath.trim()
+  const touched = hostname.length > 0 || serviceTokenId.length > 0 || binaryPath.length > 0
+  if (!enabled && !touched) return undefined
+
+  // Main keeps a secret only for the service token method, so another method never sends one.
+  const secret = cf.authMethod === 'serviceToken' ? cf.serviceTokenSecret : ''
+  return {
+    enabled,
+    hostname,
+    authMethod: cf.authMethod,
+    ...(serviceTokenId.length > 0 ? { serviceTokenId } : {}),
+    ...(secret.length > 0 ? { serviceTokenSecret: secret } : {}),
+    ...(binaryPath.length > 0 ? { binaryPath } : {})
+  }
+}
+
 function buildInput(form: FormState): ConnectionInput {
   const input: ConnectionInput = {
     name: form.name.trim(),
@@ -219,8 +293,10 @@ function buildInput(form: FormState): ConnectionInput {
   if (st !== undefined) input.socketTimeoutMS = st
   if (form.retryWrites !== 'default') input.retryWrites = form.retryWrites === 'on'
   if (form.retryReads !== 'default') input.retryReads = form.retryReads === 'on'
-  const ssh = buildSshInput(form.ssh)
+  const ssh = buildSshInput(form.ssh, form.tunnel === 'ssh')
   if (ssh !== undefined) input.ssh = ssh
+  const cloudflared = buildCloudflaredInput(form.cloudflared, form.tunnel === 'cloudflared')
+  if (cloudflared !== undefined) input.cloudflared = cloudflared
   return input
 }
 
@@ -237,6 +313,8 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
   const [testResult, setTestResult] = useState<ConnectionTestResult | null>(null)
   const [testError, setTestError] = useState<string | null>(null)
   const queryClient = useQueryClient()
+  const viaCloudflare = form.tunnel === 'cloudflared'
+  const hasStoredServiceTokenSecret = connection?.cloudflared?.hasStoredServiceTokenSecret ?? false
 
   useEffect(() => {
     if (!open) return
@@ -247,6 +325,11 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
   }, [open, connection])
 
   const input = useMemo(() => buildInput(form), [form])
+  // Main reuses the saved secret only for the hostname and client ID it was saved for.
+  const savedSecretApplies =
+    hasStoredServiceTokenSecret &&
+    input.cloudflared !== undefined &&
+    canReuseServiceTokenSecret(connection?.cloudflared, input.cloudflared)
 
   const validation = useMemo(() => {
     if (input.name.length === 0) return 'Name is required'
@@ -261,8 +344,21 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
         return 'Private key file is required'
       }
     }
+    const tunnelProblem = cloudflaredTunnelProblems(input)[0]
+    if (tunnelProblem !== undefined) return tunnelProblem.message
+    const cf = input.cloudflared
+    if (
+      cf?.enabled === true &&
+      cf.authMethod === 'serviceToken' &&
+      cf.serviceTokenSecret === undefined &&
+      !savedSecretApplies
+    ) {
+      return hasStoredServiceTokenSecret
+        ? 'Enter the client secret again — the saved one only applies to the saved hostname and client ID'
+        : 'Service token client secret is required'
+    }
     return null
-  }, [input])
+  }, [input, hasStoredServiceTokenSecret, savedSecretApplies])
 
   const testMutation = useMutation({
     mutationFn: () => api.connections.test(input, connection?.id),
@@ -300,6 +396,19 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
   const updateSsh = (patch: Partial<SshFormState>) =>
     setForm((prev) => ({ ...prev, ssh: { ...prev.ssh, ...patch } }))
 
+  const updateCloudflared = (patch: Partial<CloudflaredFormState>) =>
+    setForm((prev) => ({ ...prev, cloudflared: { ...prev.cloudflared, ...patch } }))
+
+  const setTunnel = (tunnel: TunnelKind) =>
+    setForm((prev) => ({
+      ...prev,
+      tunnel,
+      // The tunnel never dials this host; a placeholder leaves only the Access hostname and credentials to fill in.
+      ...(tunnel === 'cloudflared' && prev.uri.trim().length === 0
+        ? { uri: 'mongodb://localhost' }
+        : {})
+    }))
+
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="flex max-h-[85vh] max-w-2xl flex-col gap-4">
@@ -325,11 +434,19 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
           <Field
             label="Connection string"
             htmlFor="conn-uri"
-            hint="mongodb:// or mongodb+srv:// — credentials may be embedded or filled below."
+            hint={
+              viaCloudflare
+                ? 'Credentials, database and options apply as written. The host is never dialled — with TLS on, it is the name the server certificate is checked against.'
+                : 'mongodb:// or mongodb+srv:// — credentials may be embedded or filled below.'
+            }
           >
             <Input
               id="conn-uri"
-              placeholder="mongodb://user:password@host:27017/db"
+              placeholder={
+                viaCloudflare
+                  ? 'mongodb://user:password@localhost/db?authSource=admin'
+                  : 'mongodb://user:password@host:27017/db'
+              }
               value={form.uri}
               onChange={(e) => update('uri', e.target.value)}
               spellCheck={false}
@@ -367,14 +484,19 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
           </div>
 
           <div className="grid gap-3">
-            <ToggleRow
-              id="conn-ssh"
-              label="Connect through an SSH tunnel"
-              hint="Reach hosts that are only routable from an SSH server — including every member of a replica set."
-              checked={form.ssh.enabled}
-              onCheckedChange={(v) => updateSsh({ enabled: v })}
-            />
-            {form.ssh.enabled && (
+            <Field label="Tunnel" htmlFor="conn-tunnel" hint={TUNNEL_HINTS[form.tunnel]}>
+              <Select value={form.tunnel} onValueChange={(v) => setTunnel(v as TunnelKind)}>
+                <SelectTrigger id="conn-tunnel">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="none">None</SelectItem>
+                  <SelectItem value="ssh">SSH tunnel</SelectItem>
+                  <SelectItem value="cloudflared">Cloudflare Access (cloudflared)</SelectItem>
+                </SelectContent>
+              </Select>
+            </Field>
+            {form.tunnel === 'ssh' && (
               <SshTunnelFields
                 value={form.ssh}
                 onChange={updateSsh}
@@ -382,6 +504,13 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
                 hasStoredPassphrase={connection?.ssh?.hasStoredPassphrase ?? false}
               />
             )}
+            {viaCloudflare && (
+              <CloudflaredTunnelFields
+                value={form.cloudflared}
+                onChange={updateCloudflared}
+                savedSecretApplies={savedSecretApplies}
+              />
+            )}
           </div>
 
           <button
@@ -465,8 +594,13 @@ export function ConnectionFormDialog({ open, onOpenChange, connection }: Props)
                 <ToggleRow
                   id="conn-direct"
                   label="Direct connection"
-                  hint="Skip topology discovery, talk to one node only."
-                  checked={form.directConnection}
+                  hint={
+                    viaCloudflare
+                      ? 'Always on through a Cloudflare tunnel — it reaches exactly one server.'
+                      : 'Skip topology discovery, talk to one node only.'
+                  }
+                  checked={form.directConnection || viaCloudflare}
+                  disabled={viaCloudflare}
                   onCheckedChange={(v) => update('directConnection', v)}
                 />
               </Section>
@@ -806,6 +940,190 @@ function SshTunnelFields({
   )
 }
 
+function CloudflaredTunnelFields({
+  value,
+  onChange,
+  savedSecretApplies
+}: {
+  value: CloudflaredFormState
+  onChange: (patch: Partial<CloudflaredFormState>) => void
+  savedSecretApplies: boolean
+}) {
+  const [picking, setPicking] = useState(false)
+
+  const pickBinary = async () => {
+    setPicking(true)
+    try {
+      const path = await api.dialog.pickCloudflared()
+      if (path !== null) onChange({ binaryPath: path, checkedPath: path.trim() })
+    } catch (error: unknown) {
+      toast.error(error instanceof ApiError ? error.message : String(error))
+    } finally {
+      setPicking(false)
+    }
+  }
+
+  return (
+    <div className="grid gap-3 rounded-md border bg-card/40 p-4">
+      <div className="grid grid-cols-[2fr_1fr] gap-3">
+        <Field
+          label="Access hostname"
+          htmlFor="cf-hostname"
+          hint="The public hostname of the Access application in front of MongoDB — what you would pass to --hostname."
+        >
+          <Input
+            id="cf-hostname"
+            placeholder="mongo.example.com"
+            value={value.hostname}
+            onChange={(e) => onChange({ hostname: e.target.value })}
+            spellCheck={false}
+          />
+        </Field>
+        <Field label="Authentication" htmlFor="cf-auth">
+          <Select
+            value={value.authMethod}
+            onValueChange={(v) => onChange({ authMethod: v as CloudflaredAuthMethod })}
+          >
+            <SelectTrigger id="cf-auth">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="browser">Browser sign-in</SelectItem>
+              <SelectItem value="serviceToken">Service token</SelectItem>
+            </SelectContent>
+          </Select>
+        </Field>
+      </div>
+
+      {value.authMethod === 'browser' && (
+        <p className="text-[10px] leading-snug text-muted-foreground">
+          cloudflared opens your browser when it has no valid Access session for this hostname, and
+          reuses the session until it expires.
+        </p>
+      )}
+
+      {value.authMethod === 'serviceToken' && (
+        <>
+          <div className="grid grid-cols-2 gap-3">
+            <Field label="Client ID" htmlFor="cf-token-id">
+              <Input
+                id="cf-token-id"
+                placeholder="….access"
+                value={value.serviceTokenId}
+                onChange={(e) => onChange({ serviceTokenId: e.target.value })}
+                autoComplete="off"
+                spellCheck={false}
+                className="font-mono text-xs"
+              />
+            </Field>
+            <Field
+              label={savedSecretApplies ? 'Client secret (saved)' : 'Client secret'}
+              htmlFor="cf-token-secret"
+              hint={savedSecretApplies ? 'Leave blank to keep the saved secret.' : undefined}
+            >
+              <Input
+                id="cf-token-secret"
+                type="password"
+                value={value.serviceTokenSecret}
+                onChange={(e) => onChange({ serviceTokenSecret: e.target.value })}
+                autoComplete="new-password"
+                placeholder={savedSecretApplies ? '••••••••' : ''}
+              />
+            </Field>
+          </div>
+          <p className="text-[10px] leading-snug text-muted-foreground">
+            The Access application needs a Service Auth policy for this token.
+          </p>
+        </>
+      )}
+
+      <div className="grid gap-1.5">
+        <Field
+          label="cloudflared executable"
+          htmlFor="cf-binary"
+          hint="Leave blank to use cloudflared from PATH."
+        >
+          <div className="flex gap-2">
+            <Input
+              id="cf-binary"
+              placeholder="From PATH"
+              value={value.binaryPath}
+              onChange={(e) => onChange({ binaryPath: e.target.value })}
+              onBlur={() => onChange({ checkedPath: value.binaryPath.trim() })}
+              spellCheck={false}
+              className="font-mono text-xs"
+            />
+            <Button type="button" variant="outline" onClick={() => void pickBinary()}>
+              {picking ? <Loader2 className="animate-spin" /> : <FolderOpen />}
+              Browse
+            </Button>
+          </div>
+        </Field>
+        <CloudflaredVersionStatus binaryPath={value.checkedPath} />
+      </div>
+
+      <p className="rounded-md border border-border/60 bg-background/40 px-3 py-2 text-[10px] leading-relaxed text-muted-foreground">
+        MongoBench starts cloudflared when you connect and stops it when you disconnect. The driver
+        talks only to the server behind the tunnel, so replica-set discovery is off;{' '}
+        <code>mongodb+srv://</code> is not supported.
+      </p>
+    </div>
+  )
+}
+
+/** Which cloudflared would run for `binaryPath` (blank = PATH), or why none can. */
+function CloudflaredVersionStatus({ binaryPath }: { binaryPath: string }) {
+  const runnable = binaryPath === '' || isCloudflaredExecutable(binaryPath)
+  const version = useQuery({
+    queryKey: queryKeys.cloudflaredVersion(binaryPath),
+    queryFn: () => api.cloudflared.version(binaryPath === '' ? undefined : binaryPath),
+    enabled: runnable,
+    staleTime: 60_000
+  })
+
+  if (!runnable) return <StatusLine tone="error">{INVALID_CLOUDFLARED_PATH_MESSAGE}</StatusLine>
+  if (version.isPending) return <StatusLine tone="pending">Looking for cloudflared…</StatusLine>
+  if (version.isError) {
+    const error = version.error
+    return (
+      <StatusLine tone="error">
+        {error instanceof ApiError ? error.message : String(error)}
+      </StatusLine>
+    )
+  }
+  return (
+    <StatusLine tone="ok">
+      {binaryPath === ''
+        ? `cloudflared ${version.data} found on PATH`
+        : `cloudflared ${version.data}`}
+    </StatusLine>
+  )
+}
+
+function StatusLine({
+  tone,
+  children
+}: {
+  tone: 'pending' | 'ok' | 'error'
+  children: React.ReactNode
+}) {
+  return (
+    <p
+      className={cn(
+        'flex items-start gap-1.5 text-[10px] leading-snug',
+        tone === 'pending' && 'text-muted-foreground',
+        tone === 'ok' && 'text-success',
+        tone === 'error' && 'text-destructive'
+      )}
+    >
+      {tone === 'pending' && <Loader2 className="mt-px h-3 w-3 shrink-0 animate-spin" />}
+      {tone === 'ok' && <CheckCircle2 className="mt-px h-3 w-3 shrink-0" />}
+      {tone === 'error' && <XCircle className="mt-px h-3 w-3 shrink-0" />}
+      <span className="min-w-0 break-words">{children}</span>
+    </p>
+  )
+}
+
 function Field({
   label,
   htmlFor,
@@ -847,23 +1165,25 @@ function ToggleRow({
   label,
   hint,
   checked,
+  disabled,
   onCheckedChange
 }: {
   id: string
   label: string
   hint?: string
   checked: boolean
+  disabled?: boolean
   onCheckedChange: (v: boolean) => void
 }) {
   return (
     <div className="flex items-center justify-between gap-3 rounded-md border border-border/60 bg-background/40 px-3 py-2">
       <div className="grid min-w-0 gap-0.5">
-        <Label htmlFor={id} className="cursor-pointer text-xs font-medium">
+        <Label htmlFor={id} className={cn('text-xs font-medium', !disabled && 'cursor-pointer')}>
           {label}
         </Label>
         {hint && <span className="text-[10px] leading-snug text-muted-foreground">{hint}</span>}
       </div>
-      <Switch id={id} checked={checked} onCheckedChange={onCheckedChange} />
+      <Switch id={id} checked={checked} disabled={disabled} onCheckedChange={onCheckedChange} />
     </div>
   )
 }
diff --git a/src/renderer/src/features/connections/TimezoneSelect.tsx b/src/renderer/src/features/connections/TimezoneSelect.tsx
index 8e93a7d..946796f 100644
--- a/src/renderer/src/features/connections/TimezoneSelect.tsx
+++ b/src/renderer/src/features/connections/TimezoneSelect.tsx
@@ -51,7 +51,7 @@ export function TimezoneSelect({ value, onChange, id }: Props) {
   }, [open])
 
   return (
-    <div ref={rootRef} className="relative">
+    <div ref={rootRef} className="relative" data-consumes-escape={open ? '' : undefined}>
       <button
         id={id}
         type="button"
diff --git a/src/renderer/src/features/connections/cloudflaredLoginToast.test.ts b/src/renderer/src/features/connections/cloudflaredLoginToast.test.ts
new file mode 100644
index 0000000..09740b7
--- /dev/null
+++ b/src/renderer/src/features/connections/cloudflaredLoginToast.test.ts
@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Action, ExternalToast } from 'sonner'
+import { showCloudflaredLogin } from './cloudflaredLoginToast'
+
+const { toast } = vi.hoisted(() => ({
+  toast: {
+    info: vi.fn((_title: string, _options: ExternalToast) => 'toast'),
+    dismiss: vi.fn((_id: string) => 'toast')
+  }
+}))
+vi.mock('sonner', () => ({ toast }))
+
+const open = vi.fn()
+const URL_A = 'https://mongo.example.com/cdn-cgi/access/cli?aud=a&token=1'
+
+function lastToast(): { title: string; options: ExternalToast; action: Action } {
+  const call = toast.info.mock.lastCall
+  if (call === undefined) throw new Error('no toast was shown')
+  const [title, options] = call
+  return { title, options, action: options.action as Action }
+}
+
+const shownIds = () => toast.info.mock.calls.map(([, options]) => options.id)
+
+function click(action: Action): { defaultPrevented: boolean } {
+  const event = {
+    defaultPrevented: false,
+    preventDefault() {
+      event.defaultPrevented = true
+    }
+  }
+  action.onClick(event as unknown as Parameters<Action['onClick']>[0])
+  return event
+}
+
+beforeEach(() => {
+  toast.info.mockClear()
+  toast.dismiss.mockClear()
+  open.mockClear()
+  vi.stubGlobal('window', { open })
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('showCloudflaredLogin', () => {
+  it('shows one toast per hostname that lasts as long as cloudflared waits', () => {
+    showCloudflaredLogin({ hostname: 'mongo.example.com', state: 'waiting', url: URL_A })
+
+    expect(toast.info).toHaveBeenCalledTimes(1)
+    const { title, options, action } = lastToast()
+    expect(title).toBe('Sign in to Cloudflare Access')
+    expect(options).toMatchObject({
+      id: 'cloudflared-login:mongo.example.com',
+      duration: 10 * 60_000
+    })
+    expect(options.description).toContain('mongo.example.com')
+    expect(action.label).toBe('Open again')
+  })
+
+  it('reopens the sign-in page without closing the toast', () => {
+    showCloudflaredLogin({ hostname: 'mongo.example.com', state: 'waiting', url: URL_A })
+
+    const event = click(lastToast().action)
+
+    expect(open).toHaveBeenCalledWith(URL_A, '_blank')
+    expect(event.defaultPrevented).toBe(true)
+  })
+
+  it('points the same toast at the newest sign-in URL', () => {
+    const urlB = 'https://mongo.example.com/cdn-cgi/access/cli?aud=a&token=2'
+    showCloudflaredLogin({ hostname: 'mongo.example.com', state: 'waiting', url: URL_A })
+    showCloudflaredLogin({ hostname: 'mongo.example.com', state: 'waiting', url: urlB })
+
+    expect(new Set(shownIds()).size).toBe(1)
+    click(lastToast().action)
+    expect(open).toHaveBeenCalledWith(urlB, '_blank')
+  })
+
+  it('keeps toasts of different hostnames apart', () => {
+    showCloudflaredLogin({ hostname: 'a.example.com', state: 'waiting', url: URL_A })
+    showCloudflaredLogin({ hostname: 'b.example.com', state: 'waiting', url: URL_A })
+
+    expect(shownIds()).toEqual([
+      'cloudflared-login:a.example.com',
+      'cloudflared-login:b.example.com'
+    ])
+  })
+
+  it('dismisses the toast of that hostname once the sign-in ends', () => {
+    showCloudflaredLogin({ hostname: 'mongo.example.com', state: 'finished' })
+
+    expect(toast.dismiss).toHaveBeenCalledWith('cloudflared-login:mongo.example.com')
+    expect(toast.info).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/renderer/src/features/connections/cloudflaredLoginToast.ts b/src/renderer/src/features/connections/cloudflaredLoginToast.ts
new file mode 100644
index 0000000..a6a5bd6
--- /dev/null
+++ b/src/renderer/src/features/connections/cloudflaredLoginToast.ts
@@ -0,0 +1,28 @@
+import { toast } from 'sonner'
+import type { CloudflaredLoginPrompt } from '@shared/events'
+
+// cloudflared gives up on a sign-in after ten long polls of up to 60 s each.
+const SIGN_IN_WINDOW_MS = 10 * 60_000
+
+/** Explains why a browser window opened while connecting, with a way back to the sign-in page. */
+export function showCloudflaredLogin(prompt: CloudflaredLoginPrompt): void {
+  const id = `cloudflared-login:${prompt.hostname}`
+  if (prompt.state === 'finished') {
+    toast.dismiss(id)
+    return
+  }
+  // Sign-ins that access tcp starts mid-session never report 'finished'; the duration bounds them.
+  toast.info('Sign in to Cloudflare Access', {
+    id,
+    description: `cloudflared opened your browser to sign in to ${prompt.hostname}. MongoBench continues once you are done.`,
+    duration: SIGN_IN_WINDOW_MS,
+    action: {
+      label: 'Open again',
+      onClick: (event) => {
+        // Keeps the toast: the sign-in is still pending and may need the page once more.
+        event.preventDefault()
+        window.open(prompt.url, '_blank')
+      }
+    }
+  })
+}
diff --git a/src/renderer/src/features/document/DocumentEditorDialog.tsx b/src/renderer/src/features/document/DocumentEditorDialog.tsx
index 057f074..8c7d22a 100644
--- a/src/renderer/src/features/document/DocumentEditorDialog.tsx
+++ b/src/renderer/src/features/document/DocumentEditorDialog.tsx
@@ -13,9 +13,13 @@ import {
 } from '@/components/ui/dialog'
 import { Button } from '@/components/ui/button'
 import { api, ApiError } from '@/lib/api'
+import { useCompletionAttachment } from '@/lib/completion/useCompletionAttachment'
+import { useCompletionEnv } from '@/lib/completion/useCompletionEnv'
+import { BASE_EDITOR_OPTIONS } from '@/lib/monacoSetup'
+import { invalidateWrittenCollection } from '@/lib/queryClient'
 import { parseMongoDocuments, parseMongoQuery } from '@/lib/mongoQueryLang'
 import { serializeMongoValue } from '@/lib/mongoQuerySerialize'
-import type { DocumentEnvelope, UuidEncoding } from '@shared/types'
+import { MAX_INSERT_DOCUMENTS, type DocumentEnvelope, type UuidEncoding } from '@shared/types'
 
 export type EditorMode = 'view' | 'edit' | 'duplicate' | 'insert'
 
@@ -99,6 +103,19 @@ export function DocumentEditorDialog({
   const [value, setValue] = useState('')
   const [serverError, setServerError] = useState<string | null>(null)
   const queryClient = useQueryClient()
+  const isReadOnly = mode === 'view'
+  const completionEnv = useCompletionEnv({
+    connectionId,
+    db,
+    coll,
+    uuidEncoding,
+    timezone,
+    enabled: open && !isReadOnly
+  })
+  // The editor remounts per mode (its key), so read-only never changes for one instance.
+  const bindCompletion = useCompletionAttachment(
+    isReadOnly ? null : { kind: 'document', env: completionEnv }
+  )
 
   useEffect(() => {
     if (!mode) return
@@ -120,6 +137,12 @@ export function DocumentEditorDialog({
       const parsed = parseMongoDocuments(value)
       if (!parsed.ok) return { ok: false, error: parsed.error }
       if (parsed.documents.length === 0) return { ok: false, error: 'Enter at least one document' }
+      if (parsed.documents.length > MAX_INSERT_DOCUMENTS) {
+        return {
+          ok: false,
+          error: `At most ${MAX_INSERT_DOCUMENTS.toLocaleString('en-US')} documents per insert`
+        }
+      }
       return { ok: true, ejson: '', documents: parsed.documents }
     }
     const parsed = parseMongoQuery(value)
@@ -138,6 +161,7 @@ export function DocumentEditorDialog({
       if (!compiled.ok) throw new Error(compiled.error)
       if (mode === 'edit') {
         if (!envelope) throw new Error('No document loaded')
+        if (envelope.id === null) throw new Error('Document has no _id')
         return api.query.replaceOne({
           connectionId,
           db,
@@ -156,8 +180,7 @@ export function DocumentEditorDialog({
       throw new Error('Cannot save in view mode')
     },
     onSuccess: () => {
-      void queryClient.invalidateQueries({ queryKey: ['find'] })
-      void queryClient.invalidateQueries({ queryKey: ['count'] })
+      void invalidateWrittenCollection(queryClient, { connectionId, db, coll })
       const successMessage =
         mode === 'edit'
           ? 'Document updated'
@@ -168,6 +191,10 @@ export function DocumentEditorDialog({
       onClose()
     },
     onError: (e: unknown) => {
+      // An ordered insertMany keeps the documents written before the failing one.
+      if (mode === 'insert') {
+        void invalidateWrittenCollection(queryClient, { connectionId, db, coll })
+      }
       const message = e instanceof ApiError ? e.message : String(e)
       setServerError(message)
     }
@@ -183,7 +210,6 @@ export function DocumentEditorDialog({
   if (mode !== 'insert' && !envelope) return null
 
   const parseError = compiled.ok ? null : compiled.error
-  const isReadOnly = mode === 'view'
   const ctaLabel =
     mode === 'edit'
       ? 'Save changes'
@@ -223,7 +249,7 @@ export function DocumentEditorDialog({
           }
         >
           <Editor
-            key={mode === 'insert' ? 'insert' : `${envelope?.id}::${mode}`}
+            key={mode === 'insert' ? 'insert' : `${envelope?.id ?? 'noid'}::${mode}`}
             height="100%"
             width="100%"
             value={value}
@@ -234,8 +260,10 @@ export function DocumentEditorDialog({
                 Loading editor…
               </div>
             }
+            onMount={bindCompletion}
             onChange={(v) => setValue(v ?? '')}
             options={{
+              ...BASE_EDITOR_OPTIONS,
               readOnly: isReadOnly,
               domReadOnly: isReadOnly,
               minimap: { enabled: false },
@@ -250,7 +278,9 @@ export function DocumentEditorDialog({
               padding: { top: 8, bottom: 8 },
               autoClosingBrackets: 'always',
               autoClosingQuotes: 'always',
-              bracketPairColorization: { enabled: true }
+              bracketPairColorization: { enabled: true },
+              // Typing values must not pop up suggestions that Enter would accept.
+              quickSuggestions: false
             }}
           />
         </div>
diff --git a/src/renderer/src/features/explorer/CollectionLeaf.tsx b/src/renderer/src/features/explorer/CollectionLeaf.tsx
index f66a00e..945c7dc 100644
--- a/src/renderer/src/features/explorer/CollectionLeaf.tsx
+++ b/src/renderer/src/features/explorer/CollectionLeaf.tsx
@@ -9,14 +9,15 @@ import {
   KeyRound,
   Loader2,
   Pencil,
+  SquarePlus,
   Table,
   Trash2
 } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { useExplorerStore } from '@/store/explorer'
-import { useTabsStore } from '@/store/tabs'
+import { activeCollectionKey, collectionKey, useTabsStore } from '@/store/tabs'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
+import { queryKeys, removeNamespaceQueries } from '@/lib/queryClient'
 import {
   ContextMenu,
   ContextMenuContent,
@@ -53,11 +54,12 @@ export function CollectionLeaf({
   name: string
   type: 'collection' | 'view'
 }) {
+  const target = { connectionId, db, coll: name }
   const open = useTabsStore((s) => s.open)
+  const openNew = useTabsStore((s) => s.openNew)
   const closeForCollection = useTabsStore((s) => s.closeForCollection)
-  const activeTabId = useTabsStore((s) => s.activeTabId)
-  const tabId = `${connectionId}::${db}::${name}`
-  const isActive = activeTabId === tabId
+  const key = collectionKey(target)
+  const isActive = useTabsStore((s) => activeCollectionKey(s) === key)
   const [dialog, setDialog] = useState<DialogState>(null)
   const queryClient = useQueryClient()
   const buttonRef = useRef<HTMLButtonElement>(null)
@@ -87,6 +89,7 @@ export function CollectionLeaf({
     mutationFn: () => api.collections.drop({ connectionId, db, coll: name }),
     onSuccess: () => {
       closeForCollection(connectionId, db, name)
+      removeNamespaceQueries(queryClient, connectionId, db, name)
       void queryClient.invalidateQueries({ queryKey: queryKeys.collections(connectionId, db) })
       toast.success(`Dropped ${db}.${name}`)
       setDialog(null)
@@ -116,7 +119,14 @@ export function CollectionLeaf({
           <button
             ref={buttonRef}
             type="button"
-            onClick={() => open({ connectionId, db, coll: name })}
+            onClick={(e) => (e.ctrlKey || e.metaKey ? openNew(target) : open(target))}
+            onMouseDown={(e) => {
+              // Middle-click opens a new tab; preventDefault suppresses Windows' autoscroll cursor.
+              if (e.button === 1) {
+                e.preventDefault()
+                openNew(target)
+              }
+            }}
             className={cn(
               'flex w-full items-center gap-1.5 rounded-md px-2 py-1 text-left text-xs transition-colors',
               isActive
@@ -129,10 +139,14 @@ export function CollectionLeaf({
           </button>
         </ContextMenuTrigger>
         <ContextMenuContent>
-          <ContextMenuItem onSelect={() => open({ connectionId, db, coll: name })}>
+          <ContextMenuItem onSelect={() => open(target)}>
             <Eye className="h-4 w-4" />
             Open
           </ContextMenuItem>
+          <ContextMenuItem onSelect={() => openNew(target)}>
+            <SquarePlus className="h-4 w-4" />
+            Open in new tab
+          </ContextMenuItem>
           <ContextMenuItem onSelect={() => setDialog('info')}>
             <Info className="h-4 w-4" />
             Info
@@ -178,6 +192,7 @@ export function CollectionLeaf({
         connectionId={connectionId}
         db={db}
         coll={name}
+        timezone={timezone}
         onClose={() => setDialog(null)}
       />
 
diff --git a/src/renderer/src/features/explorer/ConnectionGroup.tsx b/src/renderer/src/features/explorer/ConnectionGroup.tsx
index e042ae4..6cde4fa 100644
--- a/src/renderer/src/features/explorer/ConnectionGroup.tsx
+++ b/src/renderer/src/features/explorer/ConnectionGroup.tsx
@@ -16,9 +16,8 @@ import {
 import { cn } from '@/lib/utils'
 import { useAppStore } from '@/store'
 import { useExplorerStore } from '@/store/explorer'
-import { useTabsStore } from '@/store/tabs'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
+import { queryKeys, releaseConnection } from '@/lib/queryClient'
 import { formatHostShort } from '@/lib/displayUri'
 import {
   ContextMenu,
@@ -57,8 +56,6 @@ export function ConnectionGroup({
 }: Props) {
   const isActive = useAppStore((s) => s.activeConnectionIds.has(connection.id))
   const markConnected = useAppStore((s) => s.markConnected)
-  const markDisconnected = useAppStore((s) => s.markDisconnected)
-  const closeTabsForConnection = useTabsStore((s) => s.closeForConnection)
   const expanded = useExplorerStore((s) => s.expandedConnections.has(connection.id))
   const expandConnection = useExplorerStore((s) => s.expandConnection)
   const collapseConnection = useExplorerStore((s) => s.collapseConnection)
@@ -91,10 +88,7 @@ export function ConnectionGroup({
 
   const disconnectMutation = useMutation({
     mutationFn: () => api.connections.disconnect(connection.id),
-    onSuccess: () => {
-      markDisconnected(connection.id)
-      closeTabsForConnection(connection.id)
-    }
+    onSuccess: () => releaseConnection(queryClient, connection.id)
   })
 
   const busy = connectMutation.isPending || disconnectMutation.isPending
diff --git a/src/renderer/src/features/explorer/ConnectionsExplorer.tsx b/src/renderer/src/features/explorer/ConnectionsExplorer.tsx
index fc5d513..f8029ca 100644
--- a/src/renderer/src/features/explorer/ConnectionsExplorer.tsx
+++ b/src/renderer/src/features/explorer/ConnectionsExplorer.tsx
@@ -17,9 +17,8 @@ import {
 import { ConnectionFormDialog } from '@/features/connections/ConnectionFormDialog'
 import { ConnectionGroup, type DragHandlers } from './ConnectionGroup'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
-import { useAppStore } from '@/store'
-import { useTabsStore } from '@/store/tabs'
+import { queryKeys, releaseConnection } from '@/lib/queryClient'
+import { reorderIds } from '@/lib/reorder'
 import type { ConnectionConfig } from '@shared/types'
 
 export function ConnectionsExplorer() {
@@ -30,8 +29,6 @@ export function ConnectionsExplorer() {
   const [dragOverIdx, setDragOverIdx] = useState<{ id: string; pos: 'before' | 'after' } | null>(
     null
   )
-  const markDisconnected = useAppStore((s) => s.markDisconnected)
-  const closeTabsForConnection = useTabsStore((s) => s.closeForConnection)
   const queryClient = useQueryClient()
 
   const {
@@ -46,8 +43,7 @@ export function ConnectionsExplorer() {
   const deleteMutation = useMutation({
     mutationFn: (id: string) => api.connections.delete(id),
     onSuccess: (_, id) => {
-      markDisconnected(id)
-      closeTabsForConnection(id)
+      releaseConnection(queryClient, id)
       void queryClient.invalidateQueries({ queryKey: queryKeys.connections })
       toast.success(`${pendingDelete?.name ?? 'Connection'} deleted`)
       setPendingDelete(null)
@@ -104,19 +100,13 @@ export function ConnectionsExplorer() {
     onDrop: (e) => {
       e.preventDefault()
       if (!dragId || !connections) return
-      const fromIdx = connections.findIndex((c) => c.id === dragId)
-      const overIdx = connections.findIndex((c) => c.id === id)
-      if (fromIdx < 0 || overIdx < 0 || fromIdx === overIdx) {
-        setDragId(null)
-        setDragOverIdx(null)
-        return
-      }
-      const ids = connections.map((c) => c.id)
-      ids.splice(fromIdx, 1)
-      const insertAt =
-        dragOverIdx?.pos === 'after' ? (fromIdx < overIdx ? overIdx : overIdx + 1) : overIdx
-      ids.splice(insertAt, 0, dragId)
-      reorderMutation.mutate(ids)
+      const ids = reorderIds(
+        connections.map((c) => c.id),
+        dragId,
+        id,
+        dragOverIdx?.pos ?? 'before'
+      )
+      if (ids) reorderMutation.mutate(ids)
       setDragId(null)
       setDragOverIdx(null)
     }
diff --git a/src/renderer/src/features/explorer/DatabaseGroup.tsx b/src/renderer/src/features/explorer/DatabaseGroup.tsx
index 91db393..c46f705 100644
--- a/src/renderer/src/features/explorer/DatabaseGroup.tsx
+++ b/src/renderer/src/features/explorer/DatabaseGroup.tsx
@@ -12,7 +12,7 @@ import {
   Users
 } from 'lucide-react'
 import { api, ApiError } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
+import { queryKeys, removeNamespaceQueries } from '@/lib/queryClient'
 import { useExplorerStore } from '@/store/explorer'
 import { useTabsStore } from '@/store/tabs'
 import { Button } from '@/components/ui/button'
@@ -83,6 +83,7 @@ function DatabaseRow({ connectionId, db }: { connectionId: string; db: DatabaseI
     mutationFn: () => api.databases.drop({ connectionId, db: db.name }),
     onSuccess: () => {
       closeForDatabase(connectionId, db.name)
+      removeNamespaceQueries(queryClient, connectionId, db.name)
       void queryClient.invalidateQueries({ queryKey: queryKeys.databases(connectionId) })
       toast.success(`Dropped ${db.name}`)
       setDialog(null)
diff --git a/src/renderer/src/features/palette/CommandPalette.tsx b/src/renderer/src/features/palette/CommandPalette.tsx
index 7da0ad9..f85874c 100644
--- a/src/renderer/src/features/palette/CommandPalette.tsx
+++ b/src/renderer/src/features/palette/CommandPalette.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
+import { toast } from 'sonner'
 import { Database, Eye, Plug, Power, Server, Table } from 'lucide-react'
 import { Dialog, DialogContent } from '@/components/ui/dialog'
 import {
@@ -11,8 +12,9 @@ import {
   CommandList
 } from '@/components/ui/command'
 import { notifyPinnedHostKey } from '@/features/connections/pinnedHostKeyToast'
-import { api } from '@/lib/api'
-import { queryKeys } from '@/lib/queryClient'
+import { api, ApiError } from '@/lib/api'
+import { formatConnectionAddress } from '@/lib/displayUri'
+import { queryKeys, releaseConnection } from '@/lib/queryClient'
 import { useAppStore } from '@/store'
 import { useExplorerStore } from '@/store/explorer'
 import { useTabsStore } from '@/store/tabs'
@@ -59,8 +61,6 @@ export function CommandPalette({ open, onOpenChange }: Props) {
   const queryClient = useQueryClient()
   const activeIds = useAppStore((s) => s.activeConnectionIds)
   const markConnected = useAppStore((s) => s.markConnected)
-  const markDisconnected = useAppStore((s) => s.markDisconnected)
-  const closeForConnection = useTabsStore((s) => s.closeForConnection)
   const openTab = useTabsStore((s) => s.open)
   const revealInExplorer = useExplorerStore((s) => s.reveal)
 
@@ -166,7 +166,7 @@ export function CommandPalette({ open, onOpenChange }: Props) {
     if (!q) return list
     const scored: Array<{ c: ConnectionConfig; score: number }> = []
     for (const c of list) {
-      const fields = [c.name, c.username ?? '', c.uri]
+      const fields = [c.name, c.username ?? '', formatConnectionAddress(c)]
       let best: number | null = null
       for (const f of fields) {
         const s = fuzzyScore(q, f.toLowerCase())
@@ -204,14 +204,14 @@ export function CommandPalette({ open, onOpenChange }: Props) {
                       onOpenChange(false)
                       if (activeIds.has(c.id)) {
                         await api.connections.disconnect(c.id).catch(() => undefined)
-                        markDisconnected(c.id)
-                        closeForConnection(c.id)
+                        releaseConnection(queryClient, c.id)
                       } else {
                         try {
                           notifyPinnedHostKey(await api.connections.connect(c.id))
                           markConnected(c.id)
-                        } catch {
-                          // toast handled at row level on the sidebar
+                        } catch (e: unknown) {
+                          const message = e instanceof ApiError ? e.message : String(e)
+                          toast.error(`Connect failed: ${message}`)
                         }
                       }
                     }}
@@ -277,7 +277,9 @@ function ConnectionRow({
       <Server className="h-4 w-4 text-muted-foreground" />
       <div className="min-w-0 flex-1">
         <div className="truncate text-sm">{conn.name}</div>
-        <div className="truncate font-mono text-[10px] text-muted-foreground">{conn.uri}</div>
+        <div className="truncate font-mono text-[10px] text-muted-foreground">
+          {formatConnectionAddress(conn)}
+        </div>
       </div>
       <span
         className={
diff --git a/src/renderer/src/features/tabs/TabBar.tsx b/src/renderer/src/features/tabs/TabBar.tsx
index b3b58d2..9078300 100644
--- a/src/renderer/src/features/tabs/TabBar.tsx
+++ b/src/renderer/src/features/tabs/TabBar.tsx
@@ -1,12 +1,20 @@
-import { X } from 'lucide-react'
+import { CopyPlus, X } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import { useTabsStore, type CollectionTab } from '@/store/tabs'
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuTrigger
+} from '@/components/ui/context-menu'
+import { isDraftDirty, ordinalLabel, useTabsStore, type CollectionTab } from '@/store/tabs'
 
 export function TabBar() {
   const tabs = useTabsStore((s) => s.tabs)
   const activeTabId = useTabsStore((s) => s.activeTabId)
   const activate = useTabsStore((s) => s.activate)
   const close = useTabsStore((s) => s.close)
+  const duplicate = useTabsStore((s) => s.duplicate)
 
   if (tabs.length === 0) return null
 
@@ -17,9 +25,11 @@ export function TabBar() {
           <TabPill
             key={tab.id}
             tab={tab}
+            ordinal={ordinalLabel(tabs, tab)}
             active={tab.id === activeTabId}
             onSelect={() => activate(tab.id)}
             onClose={() => close(tab.id)}
+            onDuplicate={() => duplicate(tab.id)}
           />
         ))}
       </div>
@@ -29,51 +39,83 @@ export function TabBar() {
 
 function TabPill({
   tab,
+  ordinal,
   active,
   onSelect,
-  onClose
+  onClose,
+  onDuplicate
 }: {
   tab: CollectionTab
+  ordinal: number | null
   active: boolean
   onSelect: () => void
   onClose: () => void
+  onDuplicate: () => void
 }) {
+  // Drafts change on every keystroke; this selector re-renders only the pill whose dot flips.
+  const dirty = useTabsStore((s) => {
+    const draft = s.drafts[tab.id]
+    return draft !== undefined && isDraftDirty(draft, tab.applied)
+  })
   return (
-    <div
-      role="tab"
-      aria-selected={active}
-      onClick={onSelect}
-      onMouseDown={(e) => {
-        // Middle-click closes the tab. Prevent the default to suppress
-        // Windows' autoscroll cursor.
-        if (e.button === 1) {
-          e.preventDefault()
-          onClose()
-        }
-      }}
-      className={cn(
-        'group relative flex shrink-0 cursor-pointer items-center gap-2 border-r px-3 text-xs',
-        active
-          ? 'border-b-0 bg-background font-medium text-foreground'
-          : 'text-muted-foreground hover:bg-accent/40 hover:text-foreground'
-      )}
-    >
-      {active && <span className="absolute inset-x-0 top-0 h-[2px] bg-primary" />}
-      <span className="font-mono">
-        <span className={active ? 'text-primary/70' : 'text-muted-foreground'}>{tab.db}.</span>
-        <span>{tab.coll}</span>
-      </span>
-      <button
-        type="button"
-        onClick={(e) => {
-          e.stopPropagation()
-          onClose()
-        }}
-        className="rounded-sm p-0.5 text-muted-foreground opacity-0 hover:bg-muted hover:text-foreground group-hover:opacity-100"
-        aria-label="Close tab"
-      >
-        <X className="h-3 w-3" />
-      </button>
-    </div>
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div
+          role="tab"
+          aria-selected={active}
+          title={dirty ? 'Query edited, not run yet' : undefined}
+          onClick={onSelect}
+          onMouseDown={(e) => {
+            // Middle-click closes the tab. Prevent the default to suppress
+            // Windows' autoscroll cursor.
+            if (e.button === 1) {
+              e.preventDefault()
+              onClose()
+            }
+          }}
+          className={cn(
+            'group relative flex shrink-0 cursor-pointer items-center gap-2 border-r px-3 text-xs',
+            active
+              ? 'border-b-0 bg-background font-medium text-foreground'
+              : 'text-muted-foreground hover:bg-accent/40 hover:text-foreground data-[state=open]:bg-accent/40'
+          )}
+        >
+          {active && <span className="absolute inset-x-0 top-0 h-[2px] bg-primary" />}
+          <span className="font-mono">
+            <span className={active ? 'text-primary/70' : 'text-muted-foreground'}>{tab.db}.</span>
+            <span>{tab.coll}</span>
+            {ordinal !== null && <span className="ml-1 text-muted-foreground">#{ordinal}</span>}
+          </span>
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation()
+              onClose()
+            }}
+            className={cn(
+              'relative rounded-sm p-0.5 text-muted-foreground hover:bg-muted hover:text-foreground',
+              !dirty && 'opacity-0 group-hover:opacity-100'
+            )}
+            aria-label="Close tab"
+          >
+            {dirty && (
+              <span className="absolute inset-0 m-auto h-1.5 w-1.5 rounded-full bg-primary group-hover:hidden" />
+            )}
+            <X className={cn('h-3 w-3', dirty && 'invisible group-hover:visible')} />
+          </button>
+        </div>
+      </ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem onSelect={onDuplicate}>
+          <CopyPlus className="h-4 w-4" />
+          Duplicate tab
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem onSelect={onClose}>
+          <X className="h-4 w-4" />
+          Close tab
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
   )
 }
diff --git a/src/renderer/src/features/users/ManageUsersDialog.tsx b/src/renderer/src/features/users/ManageUsersDialog.tsx
index 89db726..3d3fc1e 100644
--- a/src/renderer/src/features/users/ManageUsersDialog.tsx
+++ b/src/renderer/src/features/users/ManageUsersDialog.tsx
@@ -45,8 +45,10 @@ import {
   type PasswordOptions
 } from '@/lib/passwordGenerator'
 import { queryKeys } from '@/lib/queryClient'
+import { diffRoles, orderRoles, roleKey, roleLabel } from '@/lib/userRoles'
 import { cn } from '@/lib/utils'
 import type { DatabaseUser, DatabaseUserRole } from '@shared/types'
+import { RoleEditor } from './RoleEditor'
 
 type Props = {
   open: boolean
@@ -57,15 +59,7 @@ type Props = {
 
 type FormMode = { kind: 'list' } | { kind: 'create' } | { kind: 'edit'; user: DatabaseUser }
 
-const COMMON_DB_ROLES = ['read', 'readWrite', 'dbAdmin', 'dbOwner', 'userAdmin'] as const
-
-const ROLE_LABEL: Record<string, string> = {
-  read: 'Read',
-  readWrite: 'Read & write',
-  dbAdmin: 'DB admin',
-  dbOwner: 'DB owner',
-  userAdmin: 'User admin'
-}
+const ROLE_PREVIEW_LIMIT = 6
 
 export function ManageUsersDialog({ open, connectionId, db, onClose }: Props) {
   const [mode, setMode] = useState<FormMode>({ kind: 'list' })
@@ -98,7 +92,7 @@ export function ManageUsersDialog({ open, connectionId, db, onClose }: Props) {
 
   return (
     <Dialog open={open} onOpenChange={(o) => !o && onClose()}>
-      <DialogContent className="max-w-3xl">
+      <DialogContent className="flex max-h-[85vh] max-w-3xl flex-col gap-4">
         <DialogHeader>
           <DialogTitle className="flex items-center gap-2">
             {mode.kind !== 'list' && (
@@ -114,7 +108,9 @@ export function ManageUsersDialog({ open, connectionId, db, onClose }: Props) {
             )}
             {mode.kind === 'list' && <>Manage users</>}
             {mode.kind === 'create' && <>New user</>}
-            {mode.kind === 'edit' && <>Edit user — {mode.user.user}</>}
+            {mode.kind === 'edit' && (
+              <span className="min-w-0 truncate">Edit user — {mode.user.user}</span>
+            )}
           </DialogTitle>
           <DialogDescription className="font-mono text-xs">{db}</DialogDescription>
         </DialogHeader>
@@ -136,6 +132,7 @@ export function ManageUsersDialog({ open, connectionId, db, onClose }: Props) {
             mode="create"
             connectionId={connectionId}
             db={db}
+            users={usersQuery.data ?? []}
             onDone={() => setMode({ kind: 'list' })}
           />
         )}
@@ -146,6 +143,7 @@ export function ManageUsersDialog({ open, connectionId, db, onClose }: Props) {
             connectionId={connectionId}
             db={db}
             existing={mode.user}
+            users={usersQuery.data ?? []}
             onDone={() => setMode({ kind: 'list' })}
           />
         )}
@@ -226,7 +224,7 @@ function UsersListView({
   }
 
   return (
-    <div className="grid gap-3">
+    <div className="flex min-h-0 flex-1 flex-col gap-3">
       <div className="flex items-center justify-between">
         <div className="text-xs text-muted-foreground">
           {users.length} user{users.length === 1 ? '' : 's'}
@@ -240,10 +238,10 @@ function UsersListView({
           No users defined in {db}.
         </div>
       ) : (
-        <div className="overflow-hidden rounded-md border">
+        <div className="min-h-0 flex-1 overflow-y-auto rounded-md border">
           <table className="w-full text-xs">
-            <thead className="bg-muted/40 text-left text-[10px] uppercase tracking-wider text-muted-foreground">
-              <tr>
+            <thead className="sticky top-0 z-10 bg-background text-left text-[10px] uppercase tracking-wider text-muted-foreground">
+              <tr className="bg-muted/40">
                 <th className="px-3 py-2 font-medium">User</th>
                 <th className="px-3 py-2 font-medium">Roles</th>
                 <th className="w-px px-3 py-2"></th>
@@ -252,24 +250,11 @@ function UsersListView({
             <tbody>
               {users.map((u) => (
                 <tr key={u.user} className="border-t hover:bg-accent/30">
-                  <td className="px-3 py-2 font-mono">{u.user}</td>
-                  <td className="px-3 py-2">
-                    <div className="flex flex-wrap gap-1">
-                      {u.roles.map((r, i) => (
-                        <span
-                          key={`${r.role}-${r.db}-${i}`}
-                          className="rounded-sm border bg-background px-1.5 py-0.5 font-mono text-[10px]"
-                        >
-                          {r.role}
-                          <span className="text-muted-foreground">@{r.db}</span>
-                        </span>
-                      ))}
-                      {u.roles.length === 0 && (
-                        <span className="text-[10px] italic text-muted-foreground">no roles</span>
-                      )}
-                    </div>
+                  <td className="min-w-32 break-all px-3 py-2 align-top font-mono">{u.user}</td>
+                  <td className="px-3 py-2 align-top">
+                    <UserRolesCell roles={u.roles} db={db} />
                   </td>
-                  <td className="px-3 py-2">
+                  <td className="px-3 py-2 align-top">
                     <div className="flex justify-end gap-1">
                       <Button
                         size="icon"
@@ -301,83 +286,76 @@ function UsersListView({
   )
 }
 
+function UserRolesCell({ roles, db }: { roles: DatabaseUserRole[]; db: string }) {
+  const [expanded, setExpanded] = useState(false)
+  const ordered = useMemo(() => orderRoles(roles, db), [roles, db])
+
+  if (ordered.length === 0) {
+    return <span className="text-[10px] italic text-muted-foreground">no roles</span>
+  }
+
+  const shown = expanded ? ordered : ordered.slice(0, ROLE_PREVIEW_LIMIT)
+  return (
+    <div className="flex flex-wrap gap-1">
+      {shown.map((r, i) => (
+        <span
+          // Stored user documents may repeat a role; the index keeps such keys unique.
+          key={`${i}:${roleKey(r)}`}
+          title={roleLabel(r)}
+          className="max-w-full truncate rounded-sm border bg-background px-1.5 py-0.5 font-mono text-[10px]"
+        >
+          {r.role}
+          <span className="text-muted-foreground">@{r.db}</span>
+        </span>
+      ))}
+      {ordered.length > ROLE_PREVIEW_LIMIT && (
+        <button
+          type="button"
+          aria-expanded={expanded}
+          onClick={() => setExpanded((v) => !v)}
+          className="text-[10px] text-muted-foreground hover:text-foreground"
+        >
+          {expanded ? 'Show less' : `+${ordered.length - ROLE_PREVIEW_LIMIT} more`}
+        </button>
+      )}
+    </div>
+  )
+}
+
 function UserForm({
   mode,
   connectionId,
   db,
   existing,
+  users,
   onDone
 }: {
   mode: 'create' | 'edit'
   connectionId: string
   db: string
   existing?: DatabaseUser
+  users: DatabaseUser[]
   onDone: () => void
 }) {
-  const initial = useMemo(() => {
-    if (mode === 'edit' && existing) {
-      const selected = new Set<string>()
-      const others: DatabaseUserRole[] = []
-      for (const r of existing.roles) {
-        if (r.db === db && (COMMON_DB_ROLES as readonly string[]).includes(r.role)) {
-          selected.add(r.role)
-        } else {
-          others.push(r)
-        }
-      }
-      return {
-        username: existing.user,
-        selectedRoles: selected,
-        customRoles: others.length ? JSON.stringify(others, null, 2) : ''
-      }
-    }
-    return { username: '', selectedRoles: new Set<string>(), customRoles: '' }
-  }, [mode, existing, db])
-
-  const [username, setUsername] = useState(initial.username)
+  const initialRoles = useMemo(() => existing?.roles ?? [], [existing])
+  const [username, setUsername] = useState(existing?.user ?? '')
   const [password, setPassword] = useState('')
   const [generatorOpen, setGeneratorOpen] = useState(false)
-  const [selectedRoles, setSelectedRoles] = useState<Set<string>>(new Set(initial.selectedRoles))
-  const [customRoles, setCustomRoles] = useState(initial.customRoles)
+  const [roles, setRoles] = useState<DatabaseUserRole[]>(initialRoles)
   const [serverError, setServerError] = useState<string | null>(null)
   const queryClient = useQueryClient()
 
-  const customRolesParse = useMemo(() => {
-    if (customRoles.trim().length === 0)
-      return { ok: true as const, roles: [] as DatabaseUserRole[] }
-    try {
-      const parsed = JSON.parse(customRoles)
-      if (!Array.isArray(parsed)) return { ok: false as const, error: 'Must be a JSON array' }
-      const roles: DatabaseUserRole[] = []
-      for (const r of parsed) {
-        if (typeof r !== 'object' || r === null || Array.isArray(r)) {
-          return { ok: false as const, error: 'Each entry must be an object' }
-        }
-        const role = (r as Record<string, unknown>)['role']
-        const roleDb = (r as Record<string, unknown>)['db']
-        if (typeof role !== 'string' || typeof roleDb !== 'string') {
-          return { ok: false as const, error: 'Each entry needs `role` and `db` strings' }
-        }
-        roles.push({ role, db: roleDb })
-      }
-      return { ok: true as const, roles }
-    } catch (e) {
-      return { ok: false as const, error: e instanceof Error ? e.message : 'Invalid JSON' }
-    }
-  }, [customRoles])
+  const diff = useMemo(() => diffRoles(initialRoles, roles), [initialRoles, roles])
+  const rolesChanged = diff.added.length + diff.removed.length > 0
+  // The server matches existing users by their exact name, whitespace included.
+  const targetUser = existing?.user ?? username.trim()
 
   const validation = useMemo(() => {
     if (username.trim().length === 0) return 'Username is required'
     if (mode === 'create' && password.length === 0) return 'Password is required'
-    if (!customRolesParse.ok) return `Custom roles: ${customRolesParse.error}`
+    if (mode === 'edit' && !rolesChanged && password.length === 0) return 'No changes to save'
     return null
-  }, [username, password, mode, customRolesParse])
-
-  const allRoles = (): DatabaseUserRole[] => {
-    if (!customRolesParse.ok) return []
-    const own = Array.from(selectedRoles).map((role) => ({ role, db }))
-    return [...own, ...customRolesParse.roles]
-  }
+  }, [username, password, mode, rolesChanged])
 
   const createMutation = useMutation({
     mutationFn: () =>
@@ -386,7 +364,7 @@ function UserForm({
         db,
         username: username.trim(),
         password,
-        roles: allRoles()
+        roles
       }),
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: queryKeys.users(connectionId, db) })
@@ -403,13 +381,13 @@ function UserForm({
       api.users.update({
         connectionId,
         db,
-        username: username.trim(),
+        username: targetUser,
         password: password.length > 0 ? password : null,
-        roles: allRoles()
+        roles: rolesChanged ? roles : null
       }),
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: queryKeys.users(connectionId, db) })
-      toast.success(`User ${username.trim()} updated`)
+      toast.success(`User ${targetUser} updated`)
       onDone()
     },
     onError: (e: unknown) => {
@@ -427,111 +405,67 @@ function UserForm({
 
   const busy = createMutation.isPending || updateMutation.isPending
 
-  const toggleRole = (role: string) =>
-    setSelectedRoles((prev) => {
-      const next = new Set(prev)
-      if (next.has(role)) next.delete(role)
-      else next.add(role)
-      return next
-    })
-
   return (
-    <form onSubmit={onSubmit} className="grid gap-4">
-      <div className="grid grid-cols-2 gap-4">
-        <div className="grid gap-1.5">
-          <Label htmlFor="user-name">Username</Label>
-          <Input
-            id="user-name"
-            value={username}
-            onChange={(e) => setUsername(e.target.value)}
-            disabled={mode === 'edit'}
-            spellCheck={false}
-            className="font-mono"
-            autoFocus={mode === 'create'}
-          />
-        </div>
-        <div className="grid gap-1.5">
-          <Label htmlFor="user-pwd" className="flex items-center gap-1">
-            <KeyRound className="h-3 w-3" />
-            {mode === 'edit' ? 'New password (optional)' : 'Password'}
-          </Label>
-          <div className="flex gap-1.5">
+    <form onSubmit={onSubmit} className="flex min-h-0 flex-1 flex-col gap-4">
+      <div className="-mr-2 grid min-h-0 flex-1 content-start gap-4 overflow-y-auto pr-2">
+        <div className="grid grid-cols-2 gap-4">
+          <div className="grid gap-1.5">
+            <Label htmlFor="user-name">Username</Label>
             <Input
-              id="user-pwd"
-              type="password"
-              value={password}
-              onChange={(e) => setPassword(e.target.value)}
-              autoComplete="new-password"
-              placeholder={mode === 'edit' ? 'Leave blank to keep current' : ''}
+              id="user-name"
+              value={username}
+              onChange={(e) => setUsername(e.target.value)}
+              disabled={mode === 'edit'}
+              spellCheck={false}
+              className="font-mono"
+              autoFocus={mode === 'create'}
             />
-            <Button
-              type="button"
-              size="icon"
-              variant={generatorOpen ? 'secondary' : 'outline'}
-              className="shrink-0"
-              onClick={() => {
-                if (!generatorOpen && password.length === 0) {
-                  setPassword(generatePassword(DEFAULT_OPTIONS))
-                }
-                setGeneratorOpen(!generatorOpen)
-              }}
-              aria-label="Toggle password generator"
-              title="Generate password"
-            >
-              <Wand2 className="h-4 w-4" />
-            </Button>
           </div>
-        </div>
-      </div>
-
-      {generatorOpen && <PasswordGeneratorPanel value={password} onChange={setPassword} />}
-
-      <div className="grid gap-2">
-        <Label className="text-[10px] uppercase tracking-wider">
-          Roles on <span className="font-mono normal-case text-foreground">{db}</span>
-        </Label>
-        <div className="grid grid-cols-2 gap-x-4 gap-y-2 rounded-md border bg-card p-3 sm:grid-cols-3">
-          {COMMON_DB_ROLES.map((role) => (
-            <label
-              key={role}
-              className={cn(
-                'flex cursor-pointer items-center gap-2 text-xs',
-                selectedRoles.has(role) ? 'text-foreground' : 'text-muted-foreground'
-              )}
-            >
-              <input
-                type="checkbox"
-                checked={selectedRoles.has(role)}
-                onChange={() => toggleRole(role)}
-                className="accent-primary"
+          <div className="grid gap-1.5">
+            <Label htmlFor="user-pwd" className="flex items-center gap-1">
+              <KeyRound className="h-3 w-3" />
+              {mode === 'edit' ? 'New password (optional)' : 'Password'}
+            </Label>
+            <div className="flex gap-1.5">
+              <Input
+                id="user-pwd"
+                type="password"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                autoComplete="new-password"
+                placeholder={mode === 'edit' ? 'Leave blank to keep current' : ''}
               />
-              <span className="font-medium">{ROLE_LABEL[role] ?? role}</span>
-              <span className="font-mono text-[10px] text-muted-foreground">{role}</span>
-            </label>
-          ))}
+              <Button
+                type="button"
+                size="icon"
+                variant={generatorOpen ? 'secondary' : 'outline'}
+                className="shrink-0"
+                onClick={() => {
+                  if (!generatorOpen && password.length === 0) {
+                    setPassword(generatePassword(DEFAULT_OPTIONS))
+                  }
+                  setGeneratorOpen(!generatorOpen)
+                }}
+                aria-label="Toggle password generator"
+                title="Generate password"
+              >
+                <Wand2 className="h-4 w-4" />
+              </Button>
+            </div>
+          </div>
         </div>
-      </div>
 
-      <div className="grid gap-1.5">
-        <Label htmlFor="user-customroles" className="text-[10px] uppercase tracking-wider">
-          Additional roles (JSON)
-        </Label>
-        <textarea
-          id="user-customroles"
-          value={customRoles}
-          onChange={(e) => setCustomRoles(e.target.value)}
-          spellCheck={false}
-          rows={3}
-          placeholder='[{"role": "clusterMonitor", "db": "admin"}]'
-          className="rounded-md border border-input bg-transparent px-3 py-2 font-mono text-xs shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        {generatorOpen && <PasswordGeneratorPanel value={password} onChange={setPassword} />}
+
+        <RoleEditor
+          connectionId={connectionId}
+          db={db}
+          roles={roles}
+          initialRoles={initialRoles}
+          showDiff={mode === 'edit'}
+          users={users}
+          onChange={setRoles}
         />
-        <p className="text-[10px] text-muted-foreground">
-          For roles outside <span className="font-mono">{db}</span> or non-standard roles. Each
-          entry: <span className="font-mono">{`{ role, db }`}</span>.
-        </p>
-        {!customRolesParse.ok && (
-          <p className="text-xs text-destructive">{customRolesParse.error}</p>
-        )}
       </div>
 
       {serverError && (
diff --git a/src/renderer/src/features/users/RoleEditor.tsx b/src/renderer/src/features/users/RoleEditor.tsx
new file mode 100644
index 0000000..88854bc
--- /dev/null
+++ b/src/renderer/src/features/users/RoleEditor.tsx
@@ -0,0 +1,308 @@
+import { type KeyboardEvent, memo, useId, useMemo, useRef, useState } from 'react'
+import { useQuery } from '@tanstack/react-query'
+import { Plus, RotateCcw, Search, X } from 'lucide-react'
+import { AutocompleteInput } from '@/components/ui/autocomplete-input'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { api } from '@/lib/api'
+import { queryKeys } from '@/lib/queryClient'
+import {
+  addRole,
+  COMMON_DB_ROLES,
+  databaseSuggestions,
+  diffRoles,
+  groupRoles,
+  matchesRoleFilter,
+  removeRole,
+  roleEntries,
+  roleKey,
+  roleLabel,
+  roleSuggestions,
+  type RoleGroup
+} from '@/lib/userRoles'
+import { cn } from '@/lib/utils'
+import type { DatabaseUser, DatabaseUserRole } from '@shared/types'
+
+type Props = {
+  connectionId: string
+  /** Dialog database: default add target, first group and quick toggles. */
+  db: string
+  roles: DatabaseUserRole[]
+  /** Roles before editing; empty in create mode. */
+  initialRoles: DatabaseUserRole[]
+  /** Mark added and removed roles against `initialRoles`. */
+  showDiff: boolean
+  /** Listed users of the dialog database; their roles feed the suggestions. */
+  users: DatabaseUser[]
+  onChange: (roles: DatabaseUserRole[]) => void
+}
+
+const ROLE_LABEL: Record<(typeof COMMON_DB_ROLES)[number], string> = {
+  read: 'Read',
+  readWrite: 'Read & write',
+  dbAdmin: 'DB admin',
+  dbOwner: 'DB owner',
+  userAdmin: 'User admin'
+}
+
+/** Edits a user's role list: any role on any database, grouped by database. */
+export function RoleEditor({
+  connectionId,
+  db,
+  roles,
+  initialRoles,
+  showDiff,
+  users,
+  onChange
+}: Props) {
+  const [filter, setFilter] = useState('')
+  const [newRole, setNewRole] = useState('')
+  const [newDb, setNewDb] = useState(db)
+  const roleInputRef = useRef<HTMLInputElement>(null)
+  const labelId = useId()
+
+  const databasesQuery = useQuery({
+    queryKey: queryKeys.databases(connectionId),
+    queryFn: () => api.databases.list(connectionId)
+  })
+  const dbOptions = useMemo(
+    () => databaseSuggestions(db, { databases: databasesQuery.data, users }),
+    [db, databasesQuery.data, users]
+  )
+
+  const target = newDb.trim()
+  // Only exact known names, so typing a database name does not fire one request per keystroke.
+  const rolesQuery = useQuery({
+    queryKey: queryKeys.roles(connectionId, target),
+    queryFn: () => api.roles.list({ connectionId, db: target }),
+    enabled: dbOptions.includes(target)
+  })
+  const roleOptions = useMemo(
+    () => roleSuggestions(target, { serverRoles: rolesQuery.data, users, assigned: roles }),
+    [target, rolesQuery.data, users, roles]
+  )
+
+  const diff = useMemo(() => diffRoles(initialRoles, roles), [initialRoles, roles])
+  const entries = useMemo(() => roleEntries(initialRoles, roles, db), [initialRoles, roles, db])
+  const groups = useMemo(() => groupRoles(entries, filter), [entries, filter])
+  const assignedKeys = useMemo(() => new Set(roles.map(roleKey)), [roles])
+  const listed = roles.length + diff.removed.length
+
+  const candidate: DatabaseUserRole = { role: newRole.trim(), db: target }
+  const complete = candidate.role !== '' && candidate.db !== ''
+  const duplicate = complete && assignedKeys.has(roleKey(candidate))
+  const canAdd = complete && !duplicate
+
+  const add = () => {
+    if (!canAdd) return
+    onChange(addRole(roles, candidate))
+    setNewRole('')
+    // Never add a role the active filter would hide.
+    if (!matchesRoleFilter(candidate, filter)) setFilter('')
+    roleInputRef.current?.focus()
+  }
+
+  // Enter adds the role instead of submitting the surrounding user form.
+  const onAddKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {
+    if (e.key !== 'Enter') return
+    e.preventDefault()
+    add()
+  }
+
+  const summary = [
+    `${roles.length} role${roles.length === 1 ? '' : 's'}`,
+    ...(showDiff && diff.added.length > 0 ? [`${diff.added.length} added`] : []),
+    ...(showDiff && diff.removed.length > 0 ? [`${diff.removed.length} removed`] : [])
+  ].join(' · ')
+
+  return (
+    <section aria-labelledby={labelId} className="grid gap-2">
+      <div className="sticky top-0 z-10 grid gap-2 bg-background pb-1">
+        <div className="flex items-center gap-2">
+          <Label id={labelId} className="text-[10px] uppercase tracking-wider">
+            Roles
+          </Label>
+          <span aria-live="polite" className="text-[10px] text-muted-foreground">
+            {summary}
+          </span>
+          <div className="relative ml-auto">
+            <Search className="pointer-events-none absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              value={filter}
+              onChange={(e) => setFilter(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') e.preventDefault()
+              }}
+              disabled={listed === 0}
+              aria-label="Filter roles"
+              placeholder="Filter roles…"
+              spellCheck={false}
+              className="h-8 w-48 pl-7 text-xs"
+            />
+          </div>
+        </div>
+
+        <div className="flex items-center gap-2">
+          <AutocompleteInput
+            ref={roleInputRef}
+            wrapperClassName="flex-1"
+            className="h-8 text-xs"
+            value={newRole}
+            onValueChange={setNewRole}
+            suggestions={roleOptions}
+            onKeyDown={onAddKeyDown}
+            aria-label="Role name"
+            placeholder="Add role…"
+            maxLength={120}
+            spellCheck={false}
+          />
+          <span className="text-xs text-muted-foreground">on</span>
+          <AutocompleteInput
+            wrapperClassName="w-44"
+            className="h-8 text-xs"
+            value={newDb}
+            onValueChange={setNewDb}
+            suggestions={dbOptions}
+            onKeyDown={onAddKeyDown}
+            aria-label="Database"
+            maxLength={64}
+            spellCheck={false}
+          />
+          <Button type="button" size="sm" variant="outline" onClick={add} disabled={!canAdd}>
+            <Plus /> Add
+          </Button>
+        </div>
+        {duplicate && <p className="text-[10px] text-muted-foreground">Already assigned.</p>}
+
+        <div role="group" aria-label={`Common roles on ${db}`} className="flex flex-wrap gap-1.5">
+          {COMMON_DB_ROLES.map((role) => {
+            const entry = { role, db }
+            const pressed = assignedKeys.has(roleKey(entry))
+            return (
+              <button
+                key={role}
+                type="button"
+                aria-pressed={pressed}
+                title={roleLabel(entry)}
+                onClick={() => onChange(pressed ? removeRole(roles, entry) : addRole(roles, entry))}
+                className={cn(
+                  'rounded-md border px-2 py-1 text-xs transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                  pressed
+                    ? 'border-primary/50 bg-primary/10 text-foreground'
+                    : 'text-muted-foreground'
+                )}
+              >
+                {ROLE_LABEL[role]}
+              </button>
+            )
+          })}
+        </div>
+      </div>
+
+      <RoleGroupList
+        groups={groups}
+        listed={listed}
+        filter={filter}
+        roles={roles}
+        showDiff={showDiff}
+        onChange={onChange}
+      />
+    </section>
+  )
+}
+
+// Memoized so typing in the add inputs does not re-render up to 10 000 role chips.
+const RoleGroupList = memo(function RoleGroupList({
+  groups,
+  listed,
+  filter,
+  roles,
+  showDiff,
+  onChange
+}: {
+  groups: RoleGroup[]
+  /** Assigned plus removed roles, before filtering. */
+  listed: number
+  filter: string
+  roles: DatabaseUserRole[]
+  showDiff: boolean
+  onChange: (roles: DatabaseUserRole[]) => void
+}) {
+  return (
+    <div className="grid gap-3 rounded-md border bg-card p-3">
+      {groups.length === 0 ? (
+        <p className="py-2 text-center text-xs text-muted-foreground">
+          {listed === 0 ? 'No roles assigned.' : `No roles match "${filter.trim()}".`}
+        </p>
+      ) : (
+        groups.map((group) => {
+          const assigned = group.roles.filter((entry) => entry.status !== 'removed').length
+          return (
+            <div key={group.db} className="grid gap-1.5">
+              <div className="flex h-6 items-center gap-2">
+                <span className="truncate font-mono text-[11px]">{group.db}</span>
+                <span className="text-[10px] text-muted-foreground">{assigned}</span>
+                {assigned >= 2 && (
+                  <Button
+                    type="button"
+                    size="sm"
+                    variant="ghost"
+                    className="ml-auto h-6 px-2 text-[10px]"
+                    aria-label={`Remove all ${filter.trim() ? 'matching ' : ''}roles on ${group.db}`}
+                    // Only what the filter shows; hidden roles stay assigned.
+                    onClick={() =>
+                      onChange(
+                        roles.filter((r) => r.db !== group.db || !matchesRoleFilter(r, filter))
+                      )
+                    }
+                  >
+                    Remove all
+                  </Button>
+                )}
+              </div>
+              <div className="flex flex-wrap gap-1">
+                {group.roles.map(({ role, status }) => {
+                  const removed = status === 'removed'
+                  const label = `${removed ? 'Restore' : 'Remove'} ${role.role} on ${role.db}`
+                  return (
+                    <span
+                      key={roleKey(role)}
+                      className={cn(
+                        'inline-flex max-w-full items-center gap-0.5 rounded-sm border bg-background py-0.5 pl-1.5 pr-0.5 font-mono text-[10px]',
+                        showDiff && status === 'added' && 'border-success/40 bg-success/5',
+                        showDiff && removed && 'border-dashed text-muted-foreground'
+                      )}
+                    >
+                      <span
+                        className={cn('truncate', showDiff && removed && 'line-through')}
+                        title={roleLabel(role)}
+                      >
+                        {role.role}
+                      </span>
+                      <button
+                        type="button"
+                        aria-label={label}
+                        title={label}
+                        onClick={() =>
+                          onChange(removed ? addRole(roles, role) : removeRole(roles, role))
+                        }
+                        className="shrink-0 rounded-sm p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                      >
+                        {removed ? (
+                          <RotateCcw className="h-2.5 w-2.5" />
+                        ) : (
+                          <X className="h-2.5 w-2.5" />
+                        )}
+                      </button>
+                    </span>
+                  )
+                })}
+              </div>
+            </div>
+          )
+        })
+      )}
+    </div>
+  )
+})
diff --git a/src/renderer/src/lib/aggregationPipeline.test.ts b/src/renderer/src/lib/aggregationPipeline.test.ts
new file mode 100644
index 0000000..291c4c5
--- /dev/null
+++ b/src/renderer/src/lib/aggregationPipeline.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest'
+import { checkPipeline, compilePipelineSource } from './aggregationPipeline'
+
+describe('checkPipeline', () => {
+  it('accepts an empty pipeline as document-preserving', () => {
+    expect(checkPipeline([])).toEqual({ ok: true, ejson: '[]', documentPreserving: true })
+  })
+
+  it('rejects a value that is not an array', () => {
+    expect(checkPipeline({ $match: {} })).toEqual({
+      ok: false,
+      error: 'Pipeline must be an array of stages, e.g. [{ $match: { … } }]'
+    })
+  })
+
+  it('rejects a stage that is not an object', () => {
+    expect(checkPipeline([{ $match: {} }, 5])).toEqual({
+      ok: false,
+      error: 'Stage 2 must be an object'
+    })
+    expect(checkPipeline([[]])).toEqual({ ok: false, error: 'Stage 1 must be an object' })
+  })
+
+  it('rejects a stage with zero or two operators', () => {
+    expect(checkPipeline([{}])).toEqual({
+      ok: false,
+      error: 'Stage 1 must have exactly one operator'
+    })
+    expect(checkPipeline([{ $match: {}, $sort: { a: 1 } }])).toEqual({
+      ok: false,
+      error: 'Stage 1 must have exactly one operator'
+    })
+  })
+
+  it('rejects a key that is not a stage operator', () => {
+    expect(checkPipeline([{ $match: {} }, { match: {} }])).toEqual({
+      ok: false,
+      error: 'Stage 2: "match" is not a stage operator'
+    })
+  })
+
+  it('rejects write stages with their position', () => {
+    expect(checkPipeline([{ $match: {} }, { $out: 'copy' }])).toEqual({
+      ok: false,
+      error:
+        'Stage 2: $out writes to the database; Aggregation mode only reads, run it in Shell mode'
+    })
+    expect(checkPipeline([{ $merge: { into: 'copy' } }])).toEqual({
+      ok: false,
+      error:
+        'Stage 1: $merge writes to the database; Aggregation mode only reads, run it in Shell mode'
+    })
+  })
+
+  it('rejects a change stream with its position', () => {
+    expect(checkPipeline([{ $match: {} }, { $changeStream: {} }])).toEqual({
+      ok: false,
+      error: 'Stage 2: $changeStream never ends, so it cannot run here'
+    })
+  })
+
+  it('marks $match / $sort / $skip / $limit pipelines as document-preserving', () => {
+    for (const stage of [{ $match: { a: 1 } }, { $sort: { a: 1 } }, { $skip: 5 }, { $limit: 5 }]) {
+      const r = checkPipeline([stage])
+      expect(r.ok && r.documentPreserving, JSON.stringify(stage)).toBe(true)
+    }
+    const all = checkPipeline([{ $match: {} }, { $sort: { a: -1 } }, { $skip: 1 }, { $limit: 2 }])
+    expect(all.ok && all.documentPreserving).toBe(true)
+  })
+
+  it('marks reshaping pipelines as not document-preserving', () => {
+    for (const stage of [
+      { $project: { a: 1 } },
+      { $group: { _id: '$a' } },
+      { $unwind: '$a' },
+      { $lookup: { from: 'b', localField: 'a', foreignField: 'a', as: 'b' } },
+      { $sample: { size: 1 } },
+      { $addFields: { b: 1 } }
+    ]) {
+      const r = checkPipeline([{ $match: {} }, stage])
+      expect(r.ok, JSON.stringify(stage)).toBe(true)
+      if (r.ok) expect(r.documentPreserving, JSON.stringify(stage)).toBe(false)
+    }
+  })
+
+  it('returns the pipeline as EJSON', () => {
+    const r = checkPipeline([{ $match: { _id: { $oid: '507f1f77bcf86cd799439011' } } }])
+    expect(r.ok && r.ejson).toBe('[{"$match":{"_id":{"$oid":"507f1f77bcf86cd799439011"}}}]')
+  })
+})
+
+describe('checkPipeline with allowFinalWrite', () => {
+  const allowFinalWrite = { allowFinalWrite: true }
+
+  it('accepts a final $out or $merge', () => {
+    expect(checkPipeline([{ $match: { a: 1 } }, { $out: 'copy' }], allowFinalWrite)).toEqual({
+      ok: true,
+      ejson: '[{"$match":{"a":1}},{"$out":"copy"}]',
+      documentPreserving: false
+    })
+    expect(checkPipeline([{ $merge: { into: 'copy' } }], allowFinalWrite).ok).toBe(true)
+  })
+
+  it('still accepts read pipelines', () => {
+    expect(checkPipeline([{ $match: {} }, { $limit: 5 }], allowFinalWrite)).toEqual({
+      ok: true,
+      ejson: '[{"$match":{}},{"$limit":5}]',
+      documentPreserving: true
+    })
+  })
+
+  it('rejects a write stage before the end with its position', () => {
+    expect(checkPipeline([{ $out: 'copy' }, { $match: {} }], allowFinalWrite)).toEqual({
+      ok: false,
+      error: 'Stage 1: $out must be the last stage'
+    })
+    expect(
+      checkPipeline([{ $match: {} }, { $merge: { into: 'a' } }, { $out: 'b' }], allowFinalWrite)
+    ).toEqual({ ok: false, error: 'Stage 2: $merge must be the last stage' })
+  })
+
+  it('rejects a change stream anywhere', () => {
+    expect(checkPipeline([{ $changeStream: {} }, { $out: 'copy' }], allowFinalWrite)).toEqual({
+      ok: false,
+      error: 'Stage 1: $changeStream never ends, so it cannot run here'
+    })
+    expect(checkPipeline([{ $match: {} }, { $changeStream: {} }], allowFinalWrite)).toEqual({
+      ok: false,
+      error: 'Stage 2: $changeStream never ends, so it cannot run here'
+    })
+  })
+
+  it('applies the stage shape rules to the final write stage', () => {
+    expect(checkPipeline([{ $out: 'copy', $match: {} }], allowFinalWrite)).toEqual({
+      ok: false,
+      error: 'Stage 1 must have exactly one operator'
+    })
+  })
+})
+
+describe('compilePipelineSource', () => {
+  it('compiles shell syntax with helpers', () => {
+    const r = compilePipelineSource('[{ $match: { _id: ObjectId("507f1f77bcf86cd799439011") } }]')
+    expect(r).toEqual({
+      ok: true,
+      ejson: '[{"$match":{"_id":{"$oid":"507f1f77bcf86cd799439011"}}}]',
+      documentPreserving: true
+    })
+  })
+
+  it('reports syntax errors from the parser', () => {
+    const r = compilePipelineSource('[{ $match: }]')
+    expect(r.ok).toBe(false)
+  })
+
+  it('reports a non-array source', () => {
+    expect(compilePipelineSource('{ $match: {} }')).toEqual({
+      ok: false,
+      error: 'Pipeline must be an array of stages, e.g. [{ $match: { … } }]'
+    })
+  })
+
+  it('rejects $out written in shell syntax', () => {
+    expect(compilePipelineSource("[{ $out: 'copy' }]")).toEqual({
+      ok: false,
+      error:
+        'Stage 1: $out writes to the database; Aggregation mode only reads, run it in Shell mode'
+    })
+  })
+})
diff --git a/src/renderer/src/lib/aggregationPipeline.ts b/src/renderer/src/lib/aggregationPipeline.ts
new file mode 100644
index 0000000..8265ef9
--- /dev/null
+++ b/src/renderer/src/lib/aggregationPipeline.ts
@@ -0,0 +1,64 @@
+import {
+  finalWriteStage,
+  findRejectedStage,
+  rejectedStageMessage,
+  writePipelineError
+} from '@shared/pipeline'
+import { isDocument } from '@shared/writeOps'
+import { parseMongoQuery } from './mongoQueryLang'
+
+/** A pipeline ready to send; `documentPreserving` means every output row is a whole stored document. */
+export type CompiledPipeline = { ejson: string; documentPreserving: boolean }
+export type PipelineCompileResult = ({ ok: true } & CompiledPipeline) | { ok: false; error: string }
+
+const DOCUMENT_PRESERVING_STAGES: ReadonlySet<string> = new Set([
+  '$match',
+  '$sort',
+  '$skip',
+  '$limit'
+])
+
+/**
+ * Validates a parsed pipeline: an array of single-operator stages that can all run here.
+ * @param options.allowFinalWrite also accepts a pipeline ending in `$out` / `$merge` (Shell mode).
+ */
+export function checkPipeline(
+  value: unknown,
+  options: { allowFinalWrite?: boolean } = {}
+): PipelineCompileResult {
+  if (!Array.isArray(value)) {
+    return { ok: false, error: 'Pipeline must be an array of stages, e.g. [{ $match: { … } }]' }
+  }
+  const allowFinalWrite = options.allowFinalWrite === true
+  const writeIndex = allowFinalWrite && finalWriteStage(value) !== null ? value.length - 1 : -1
+  let documentPreserving = true
+  for (const [index, stage] of value.entries()) {
+    const n = index + 1
+    if (!isDocument(stage)) {
+      return { ok: false, error: `Stage ${n} must be an object` }
+    }
+    const keys = Object.keys(stage)
+    if (keys.length !== 1) return { ok: false, error: `Stage ${n} must have exactly one operator` }
+    const operator = keys[0]!
+    if (!operator.startsWith('$')) {
+      return { ok: false, error: `Stage ${n}: "${operator}" is not a stage operator` }
+    }
+    const rejected = index === writeIndex ? null : findRejectedStage([stage])
+    if (rejected !== null) {
+      // Earlier stages passed, so writePipelineError describes this one unless it is the last.
+      const error =
+        (allowFinalWrite ? writePipelineError(value) : null) ??
+        `Stage ${n}: ${rejectedStageMessage(rejected)}`
+      return { ok: false, error }
+    }
+    if (!DOCUMENT_PRESERVING_STAGES.has(operator)) documentPreserving = false
+  }
+  return { ok: true, ejson: JSON.stringify(value), documentPreserving }
+}
+
+/** Compiles aggregation-mode source; callers handle blank input as "nothing to run". */
+export function compilePipelineSource(source: string): PipelineCompileResult {
+  const parsed = parseMongoQuery(source)
+  if (!parsed.ok) return { ok: false, error: parsed.error }
+  return checkPipeline(parsed.value)
+}
diff --git a/src/renderer/src/lib/api.ts b/src/renderer/src/lib/api.ts
index b747d66..3954d57 100644
--- a/src/renderer/src/lib/api.ts
+++ b/src/renderer/src/lib/api.ts
@@ -1,9 +1,16 @@
-import type { ConnectionDropped, UpdateCheckResult, UpdateProgress } from '@shared/events'
+import type {
+  CloudflaredLoginPrompt,
+  ConnectionDropped,
+  UpdateCheckResult,
+  UpdateProgress
+} from '@shared/events'
 import type { ApiErrorPayload, ErrorCode, Result } from '@shared/result'
 import type {
   AggregateRequest,
   AggregateResponse,
+  CancelQueryRequest,
   CollectionInfo,
+  CollectionSchema,
   CollectionStats,
   ConnectionConfig,
   ConnectionInput,
@@ -15,16 +22,20 @@ import type {
   CreateIndexPayload,
   CreateUserPayload,
   DatabaseInfo,
+  DatabaseRoleInfo,
   DatabaseUser,
   DeleteManyRequest,
   DeleteManyResponse,
   DeleteOneRequest,
   DeleteOneResponse,
+  DistinctRequest,
+  DistinctResponse,
   DropIndexPayload,
   DropUserPayload,
   FindRequest,
   FindResponse,
   IndexInfo,
+  IndexStatsReport,
   InsertManyRequest,
   InsertManyResponse,
   InsertOneRequest,
@@ -33,7 +44,9 @@ import type {
   ReplaceOneRequest,
   ReplaceOneResponse,
   ServerStats,
-  UpdateUserPayload
+  UpdateUserPayload,
+  WriteRequest,
+  WriteResponse
 } from '@shared/types'
 
 export class ApiError extends Error {
@@ -95,7 +108,12 @@ export const api = {
     drop: (payload: { connectionId: string; db: string; coll: string }): Promise<void> =>
       unwrap(window.api.collections.drop(payload)),
     rename: (payload: RenameCollectionPayload): Promise<void> =>
-      unwrap(window.api.collections.rename(payload))
+      unwrap(window.api.collections.rename(payload)),
+    schema: (payload: {
+      connectionId: string
+      db: string
+      coll: string
+    }): Promise<CollectionSchema> => unwrap(window.api.collections.schema(payload))
   },
   query: {
     find: (request: FindRequest): Promise<FindResponse> => unwrap(window.api.query.find(request)),
@@ -112,7 +130,13 @@ export const api = {
     deleteOne: (request: DeleteOneRequest): Promise<DeleteOneResponse> =>
       unwrap(window.api.query.deleteOne(request)),
     deleteMany: (request: DeleteManyRequest): Promise<DeleteManyResponse> =>
-      unwrap(window.api.query.deleteMany(request))
+      unwrap(window.api.query.deleteMany(request)),
+    distinct: (request: DistinctRequest): Promise<DistinctResponse> =>
+      unwrap(window.api.query.distinct(request)),
+    cancel: (request: CancelQueryRequest): Promise<void> =>
+      unwrap(window.api.query.cancel(request)),
+    write: (request: WriteRequest): Promise<WriteResponse> =>
+      unwrap(window.api.query.write(request))
   },
   users: {
     list: (payload: { connectionId: string; db: string }): Promise<DatabaseUser[]> =>
@@ -121,15 +145,32 @@ export const api = {
     update: (payload: UpdateUserPayload): Promise<void> => unwrap(window.api.users.update(payload)),
     drop: (payload: DropUserPayload): Promise<void> => unwrap(window.api.users.drop(payload))
   },
+  roles: {
+    list: (payload: { connectionId: string; db: string }): Promise<DatabaseRoleInfo[]> =>
+      unwrap(window.api.roles.list(payload))
+  },
   indexes: {
     list: (payload: { connectionId: string; db: string; coll: string }): Promise<IndexInfo[]> =>
       unwrap(window.api.indexes.list(payload)),
     create: (payload: CreateIndexPayload): Promise<{ name: string }> =>
       unwrap(window.api.indexes.create(payload)),
-    drop: (payload: DropIndexPayload): Promise<void> => unwrap(window.api.indexes.drop(payload))
+    drop: (payload: DropIndexPayload): Promise<void> => unwrap(window.api.indexes.drop(payload)),
+    stats: (payload: {
+      connectionId: string
+      db: string
+      coll: string
+    }): Promise<IndexStatsReport> => unwrap(window.api.indexes.stats(payload))
+  },
+  cloudflared: {
+    version: (binaryPath?: string): Promise<string> =>
+      unwrap(window.api.cloudflared.version(binaryPath)),
+    // A push subscription — no Result to unwrap.
+    onLogin: (listener: (prompt: CloudflaredLoginPrompt) => void): (() => void) =>
+      window.api.cloudflared.onLogin(listener)
   },
   dialog: {
-    pickPrivateKey: (): Promise<string | null> => unwrap(window.api.dialog.pickPrivateKey())
+    pickPrivateKey: (): Promise<string | null> => unwrap(window.api.dialog.pickPrivateKey()),
+    pickCloudflared: (): Promise<string | null> => unwrap(window.api.dialog.pickCloudflared())
   },
   updater: {
     check: (): Promise<UpdateCheckResult> => unwrap(window.api.updater.check()),
diff --git a/src/renderer/src/lib/bsonDisplay.test.ts b/src/renderer/src/lib/bsonDisplay.test.ts
new file mode 100644
index 0000000..d4136cc
--- /dev/null
+++ b/src/renderer/src/lib/bsonDisplay.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import type { DocumentEnvelope } from '@shared/types'
+import { extractColumns } from './bsonDisplay'
+
+const envelope = (data: Record<string, unknown>): DocumentEnvelope => ({
+  id: null,
+  data,
+  canonical: JSON.stringify(data),
+  hash: 'h'
+})
+
+describe('extractColumns', () => {
+  it('leads with _id when a document has it', () => {
+    const columns = extractColumns([
+      envelope({ name: 'a', _id: { $oid: '0123456789abcdef01234567' } }),
+      envelope({ age: 3 })
+    ])
+    expect(columns).toEqual(['_id', 'name', 'age'])
+  })
+
+  it('leaves _id out when no document has it', () => {
+    expect(extractColumns([envelope({ n: 5 }), envelope({ total: 1, n: 2 })])).toEqual([
+      'n',
+      'total'
+    ])
+  })
+
+  it('returns no columns for no documents', () => {
+    expect(extractColumns([])).toEqual([])
+  })
+})
diff --git a/src/renderer/src/lib/bsonDisplay.ts b/src/renderer/src/lib/bsonDisplay.ts
index 9b457d2..3f4c2cc 100644
--- a/src/renderer/src/lib/bsonDisplay.ts
+++ b/src/renderer/src/lib/bsonDisplay.ts
@@ -154,6 +154,7 @@ export function extractColumns(documents: DocumentEnvelope[]): string[] {
   for (const env of documents) {
     for (const key of Object.keys(env.data)) seen.add(key)
   }
+  if (!seen.has('_id')) return [...seen]
   return ['_id', ...[...seen].filter((k) => k !== '_id')]
 }
 
diff --git a/src/renderer/src/lib/completion/catalog.ts b/src/renderer/src/lib/completion/catalog.ts
new file mode 100644
index 0000000..6f04c42
--- /dev/null
+++ b/src/renderer/src/lib/completion/catalog.ts
@@ -0,0 +1,1296 @@
+/**
+ * Static completion data: query, update and expression operators, stages, accumulators,
+ * argument grammars, write options and shell methods. Templates are Monaco snippet text;
+ * literal `$` stays escaped.
+ */
+import type { BsonTypeName, WriteMethod } from '@shared/types'
+import {
+  BULK_OPERATION_FIELDS,
+  BULK_OPERATION_OPTIONS,
+  BULK_WRITE_OPERATIONS,
+  EXCLUSIVE_OPTIONS,
+  WRITE_ARGUMENTS,
+  WRITE_OPTIONS,
+  type WriteArgument,
+  type WriteField,
+  type WriteOptionKind
+} from '@shared/writeOps'
+
+/** Snippet text of the value after `key: `; `k` renders an inner key in the editor's key style. */
+export type Template = (k: (key: string) => string) => string
+
+export type KeyDef = {
+  name: string
+  doc: string
+  /** Value template; absent inserts only `key: `. */
+  template?: Template
+  /** Re-open suggestions after inserting; defaults to true for keys without a template. */
+  retrigger?: boolean
+}
+
+const OBJECT: Template = () => '{ $0 }'
+const ARRAY: Template = () => '[$0]'
+const STRING: Template = () => '"$0"'
+const FIELD_REF: Template = () => '"\\$$0"'
+
+export const QUERY_TOP_OPERATORS: readonly KeyDef[] = [
+  {
+    name: '$and',
+    doc: 'Matches when every clause matches.',
+    template: () => '[{ $0 }]',
+    retrigger: true
+  },
+  {
+    name: '$or',
+    doc: 'Matches when any clause matches.',
+    template: () => '[{ $0 }]',
+    retrigger: true
+  },
+  {
+    name: '$nor',
+    doc: 'Matches when no clause matches.',
+    template: () => '[{ $0 }]',
+    retrigger: true
+  },
+  {
+    name: '$expr',
+    doc: 'Evaluates an aggregation expression per document.',
+    template: OBJECT,
+    retrigger: true
+  },
+  {
+    name: '$text',
+    doc: 'Text search on a text index.',
+    template: (k) => `{ ${k('$search')}: "$0" }`
+  },
+  {
+    name: '$jsonSchema',
+    doc: 'Matches documents valid against a JSON Schema.',
+    template: OBJECT,
+    retrigger: true
+  },
+  {
+    name: '$where',
+    doc: 'Server-side JavaScript predicate; slow, avoid on large collections.',
+    template: STRING
+  },
+  {
+    name: '$comment',
+    doc: 'Attaches a comment to the query in logs and profiler output.',
+    template: STRING
+  }
+]
+
+/** Field types an operator fits; `regexOption` is offered only next to `$regex`. */
+export type OperatorFit =
+  'always' | 'comparable' | 'string' | 'regexOption' | 'array' | 'integer' | 'geo'
+
+export type FieldOperator = KeyDef & { fits: OperatorFit }
+
+const GEOMETRY: (type: string) => Template = (type) => (k) =>
+  `{ ${k('$geometry')}: { ${k('type')}: "\${1:${type}}", ${k('coordinates')}: [$0] } }`
+const NEAR: Template = (k) =>
+  `{ ${k('$geometry')}: { ${k('type')}: "Point", ${k('coordinates')}: [\${1:lng}, \${2:lat}] }, ${k('$maxDistance')}: \${0:1000} }`
+
+export const FIELD_OPERATORS: readonly FieldOperator[] = [
+  { name: '$eq', doc: 'Equal to a value.', fits: 'always' },
+  { name: '$ne', doc: 'Not equal to a value.', fits: 'always' },
+  { name: '$gt', doc: 'Greater than a value.', fits: 'comparable' },
+  { name: '$gte', doc: 'Greater than or equal to a value.', fits: 'comparable' },
+  { name: '$lt', doc: 'Less than a value.', fits: 'comparable' },
+  { name: '$lte', doc: 'Less than or equal to a value.', fits: 'comparable' },
+  {
+    name: '$in',
+    doc: 'Equal to any value in the array.',
+    fits: 'always',
+    template: ARRAY,
+    retrigger: true
+  },
+  {
+    name: '$nin',
+    doc: 'Equal to none of the values in the array.',
+    fits: 'always',
+    template: ARRAY,
+    retrigger: true
+  },
+  { name: '$exists', doc: 'The field is present (true) or missing (false).', fits: 'always' },
+  { name: '$type', doc: 'The value has one of the BSON types.', fits: 'always' },
+  {
+    name: '$not',
+    doc: 'Inverts an operator expression.',
+    fits: 'always',
+    template: OBJECT,
+    retrigger: true
+  },
+  { name: '$regex', doc: 'Matches a regular expression.', fits: 'string', template: () => '/$0/' },
+  { name: '$options', doc: 'Flags for $regex: i, m, x, s.', fits: 'regexOption' },
+  {
+    name: '$all',
+    doc: 'The array contains all the values.',
+    fits: 'array',
+    template: ARRAY,
+    retrigger: true
+  },
+  {
+    name: '$elemMatch',
+    doc: 'An array element matches all conditions.',
+    fits: 'array',
+    template: OBJECT,
+    retrigger: true
+  },
+  { name: '$size', doc: 'The array has this many elements.', fits: 'array', retrigger: false },
+  {
+    name: '$mod',
+    doc: 'value % divisor === remainder.',
+    fits: 'integer',
+    template: () => '[${1:divisor}, ${2:remainder}]'
+  },
+  { name: '$bitsAllSet', doc: 'All bits of the mask are set.', fits: 'integer', retrigger: false },
+  {
+    name: '$bitsAllClear',
+    doc: 'All bits of the mask are clear.',
+    fits: 'integer',
+    retrigger: false
+  },
+  { name: '$bitsAnySet', doc: 'Any bit of the mask is set.', fits: 'integer', retrigger: false },
+  {
+    name: '$bitsAnyClear',
+    doc: 'Any bit of the mask is clear.',
+    fits: 'integer',
+    retrigger: false
+  },
+  {
+    name: '$geoWithin',
+    doc: 'Geometry lies within a shape.',
+    fits: 'geo',
+    template: GEOMETRY('Polygon')
+  },
+  {
+    name: '$geoIntersects',
+    doc: 'Geometry intersects a shape.',
+    fits: 'geo',
+    template: GEOMETRY('Point')
+  },
+  {
+    name: '$near',
+    doc: 'Nearest to a point (planar), closest first.',
+    fits: 'geo',
+    template: NEAR
+  },
+  {
+    name: '$nearSphere',
+    doc: 'Nearest to a point (spherical), closest first.',
+    fits: 'geo',
+    template: NEAR
+  }
+]
+
+/** Extended-JSON wrapper key matching a field type, e.g. `$oid` for objectId. */
+export const EJSON_WRAPPERS: Partial<Record<BsonTypeName, KeyDef>> = {
+  objectId: { name: '$oid', doc: 'Extended JSON ObjectId.', template: STRING },
+  date: { name: '$date', doc: 'Extended JSON date (ISO-8601 string).', template: STRING },
+  int: { name: '$numberInt', doc: 'Extended JSON 32-bit integer.', template: STRING },
+  long: { name: '$numberLong', doc: 'Extended JSON 64-bit integer.', template: STRING },
+  double: { name: '$numberDouble', doc: 'Extended JSON double.', template: STRING },
+  decimal: { name: '$numberDecimal', doc: 'Extended JSON 128-bit decimal.', template: STRING },
+  uuid: { name: '$uuid', doc: 'Extended JSON UUID.', template: STRING },
+  binData: {
+    name: '$binary',
+    doc: 'Extended JSON binary.',
+    template: (k) => `{ ${k('base64')}: "$1", ${k('subType')}: "\${0:00}" }`
+  },
+  timestamp: {
+    name: '$timestamp',
+    doc: 'Extended JSON timestamp.',
+    template: (k) => `{ ${k('t')}: $1, ${k('i')}: \${0:1} }`
+  },
+  regex: {
+    name: '$regularExpression',
+    doc: 'Extended JSON regular expression.',
+    template: (k) => `{ ${k('pattern')}: "$1", ${k('options')}: "$0" }`
+  }
+}
+
+export const TEXT_KEYS: readonly KeyDef[] = [
+  { name: '$search', doc: 'Terms to search for.', template: STRING },
+  { name: '$language', doc: 'Language for stemming and stop words.', template: STRING },
+  { name: '$caseSensitive', doc: 'Case-sensitive search.' },
+  { name: '$diacriticSensitive', doc: 'Diacritic-sensitive search.' }
+]
+
+export const JSON_SCHEMA_KEYS: readonly KeyDef[] = [
+  { name: 'bsonType', doc: 'Allowed BSON type(s).' },
+  { name: 'required', doc: 'Fields that must be present.', template: ARRAY, retrigger: true },
+  { name: 'properties', doc: 'Schemas of named fields.', template: OBJECT, retrigger: true },
+  { name: 'additionalProperties', doc: 'Allow fields not listed in properties.' },
+  { name: 'enum', doc: 'Allowed values.', template: ARRAY },
+  { name: 'minimum', doc: 'Minimum number.', retrigger: false },
+  { name: 'maximum', doc: 'Maximum number.', retrigger: false },
+  { name: 'minLength', doc: 'Minimum string length.', retrigger: false },
+  { name: 'maxLength', doc: 'Maximum string length.', retrigger: false },
+  { name: 'pattern', doc: 'Regular expression a string must match.', template: STRING },
+  { name: 'items', doc: 'Schema of array elements.', template: OBJECT, retrigger: true },
+  { name: 'minItems', doc: 'Minimum array length.', retrigger: false },
+  { name: 'maxItems', doc: 'Maximum array length.', retrigger: false },
+  { name: 'uniqueItems', doc: 'Array elements must be unique.' },
+  { name: 'description', doc: 'Human-readable description.', template: STRING },
+  { name: 'title', doc: 'Short title.', template: STRING }
+]
+
+export const GEO_KEYS: readonly KeyDef[] = [
+  {
+    name: '$geometry',
+    doc: 'GeoJSON geometry.',
+    template: (k) => `{ ${k('type')}: "\${1:Point}", ${k('coordinates')}: [$0] }`
+  },
+  { name: '$maxDistance', doc: 'Maximum distance (meters for GeoJSON).', retrigger: false },
+  { name: '$minDistance', doc: 'Minimum distance (meters for GeoJSON).', retrigger: false },
+  {
+    name: '$box',
+    doc: 'Legacy rectangle: bottom-left and top-right corners.',
+    template: () => '[[$1], [$0]]'
+  },
+  { name: '$center', doc: 'Legacy circle on a plane.', template: () => '[[$1], ${0:radius}]' },
+  {
+    name: '$centerSphere',
+    doc: 'Circle on a sphere, radius in radians.',
+    template: () => '[[$1], ${0:radians}]'
+  },
+  { name: '$polygon', doc: 'Legacy polygon.', template: () => '[[$0]]' }
+]
+
+/** Operators of a projection field's object. */
+export const PROJECTION_OPERATORS: readonly KeyDef[] = [
+  { name: '$slice', doc: 'First n elements, or [skip, n].', retrigger: false },
+  {
+    name: '$elemMatch',
+    doc: 'First element matching a condition.',
+    template: OBJECT,
+    retrigger: true
+  },
+  {
+    name: '$meta',
+    doc: 'Metadata such as the text search score.',
+    template: () => '"${0:textScore}"'
+  }
+]
+
+export type UpdateOperatorDef = KeyDef & {
+  /** Type of the fields it applies to. */
+  fields?: TypeClass
+}
+
+const update = (name: string, doc: string, fields?: TypeClass): UpdateOperatorDef => ({
+  name,
+  doc,
+  template: OBJECT,
+  retrigger: true,
+  fields
+})
+
+/** Update operators; each takes an object keyed by field paths. */
+export const UPDATE_OPERATORS: readonly UpdateOperatorDef[] = [
+  update('$set', 'Sets fields to values.'),
+  update('$unset', 'Removes fields.'),
+  update('$inc', 'Adds to numeric fields.', 'number'),
+  update('$mul', 'Multiplies numeric fields.', 'number'),
+  update('$rename', 'Renames fields.'),
+  update('$min', 'Sets fields to the value if it is smaller.'),
+  update('$max', 'Sets fields to the value if it is larger.'),
+  update('$currentDate', 'Sets fields to the current date or timestamp.', 'date'),
+  update('$setOnInsert', 'Sets fields only when an upsert inserts.'),
+  update('$push', 'Appends to arrays.', 'array'),
+  update('$addToSet', 'Adds to arrays unless already present.', 'array'),
+  update('$pop', 'Removes the first (-1) or last (1) array element.', 'array'),
+  update('$pull', 'Removes array elements matching a condition.', 'array'),
+  update('$pullAll', 'Removes every listed value from arrays.', 'array'),
+  update('$bit', 'Bitwise and, or, xor of integer fields.', 'number')
+]
+
+/** Update path segments `$`, `$[]` and `$[name]`, which address array elements. */
+export const POSITIONAL_SEGMENT = /^\$(?:\[\w*\])?$/
+
+/** Schema path of an update path: its positional segments dropped, as elements share their array's path. */
+export function withoutPositional(path: string): string {
+  return path
+    .split('.')
+    .filter((segment) => !POSITIONAL_SEGMENT.test(segment))
+    .join('.')
+}
+
+/** Update operator whose value may be an object of modifiers. */
+export type ArrayModifierOwner = '$push' | '$addToSet'
+
+/** Modifiers of a `$push` / `$addToSet` value. */
+export const ARRAY_MODIFIERS: Readonly<Record<ArrayModifierOwner, readonly KeyDef[]>> = {
+  $push: [
+    { name: '$each', doc: 'Appends each element of the array.', template: ARRAY, retrigger: true },
+    { name: '$position', doc: 'Index to insert at.', retrigger: false },
+    {
+      name: '$slice',
+      doc: 'Keeps the first n, or with -n the last n, elements.',
+      retrigger: false
+    },
+    { name: '$sort', doc: 'Sorts the array: 1, -1 or by element fields.' }
+  ],
+  $addToSet: [
+    { name: '$each', doc: 'Adds each element of the array.', template: ARRAY, retrigger: true }
+  ]
+}
+
+/** `$type` aliases. */
+export const TYPE_ALIASES: readonly string[] = [
+  'double',
+  'string',
+  'object',
+  'array',
+  'binData',
+  'undefined',
+  'objectId',
+  'bool',
+  'date',
+  'null',
+  'regex',
+  'dbPointer',
+  'javascript',
+  'symbol',
+  'int',
+  'timestamp',
+  'long',
+  'decimal',
+  'minKey',
+  'maxKey',
+  'number'
+]
+
+/** `$type` alias of a sampled type. */
+export function typeAlias(type: BsonTypeName): string {
+  if (type === 'uuid' || type === 'uuidLegacy') return 'binData'
+  if (type === 'dbRef') return 'object'
+  return type
+}
+
+export type StageDef = KeyDef & {
+  /** Valid only as the first stage of a pipeline. */
+  firstOnly?: boolean
+  /** Valid only in a `$lookup` / `$unionWith` pipeline; a collection aggregate rejects it. */
+  subPipelineOnly?: boolean
+}
+
+export const STAGES: readonly StageDef[] = [
+  { name: '$match', doc: 'Filters documents with a query.', template: OBJECT, retrigger: true },
+  {
+    name: '$project',
+    doc: 'Includes, excludes or computes fields.',
+    template: OBJECT,
+    retrigger: true
+  },
+  {
+    name: '$group',
+    doc: 'Groups by _id and accumulates per group.',
+    template: (k) => `{ ${k('_id')}: $0 }`,
+    retrigger: true
+  },
+  { name: '$sort', doc: 'Sorts documents.', template: OBJECT, retrigger: true },
+  { name: '$limit', doc: 'Passes the first n documents.', template: () => '${0:10}' },
+  { name: '$skip', doc: 'Skips the first n documents.', template: () => '${0:0}' },
+  {
+    name: '$lookup',
+    doc: 'Joins documents of another collection.',
+    template: (k) => `{ ${k('from')}: "$0" }`,
+    retrigger: true
+  },
+  {
+    name: '$unwind',
+    doc: 'Outputs one document per array element.',
+    template: FIELD_REF,
+    retrigger: true
+  },
+  { name: '$addFields', doc: 'Adds or overwrites fields.', template: OBJECT, retrigger: true },
+  { name: '$set', doc: 'Alias of $addFields.', template: OBJECT, retrigger: true },
+  { name: '$unset', doc: 'Removes fields.', template: STRING, retrigger: true },
+  {
+    name: '$count',
+    doc: 'Outputs one document with the document count.',
+    template: () => '"${0:count}"'
+  },
+  {
+    name: '$sample',
+    doc: 'Picks n random documents.',
+    template: (k) => `{ ${k('size')}: \${0:10} }`
+  },
+  {
+    name: '$replaceRoot',
+    doc: 'Replaces each document with an embedded one.',
+    template: (k) => `{ ${k('newRoot')}: "\\$$0" }`,
+    retrigger: true
+  },
+  {
+    name: '$replaceWith',
+    doc: 'Replaces each document with an expression result.',
+    template: OBJECT
+  },
+  {
+    name: '$sortByCount',
+    doc: 'Groups by an expression and counts, largest first.',
+    template: FIELD_REF,
+    retrigger: true
+  },
+  { name: '$facet', doc: 'Runs several sub-pipelines on the same input.', template: OBJECT },
+  { name: '$bucket', doc: 'Groups into buckets by boundaries.', template: OBJECT },
+  { name: '$bucketAuto', doc: 'Groups into a number of evenly filled buckets.', template: OBJECT },
+  {
+    name: '$unionWith',
+    doc: 'Appends documents of another collection.',
+    template: (k) => `{ ${k('coll')}: "$0" }`,
+    retrigger: true
+  },
+  { name: '$graphLookup', doc: 'Recursive lookup over a collection.', template: OBJECT },
+  {
+    name: '$setWindowFields',
+    doc: 'Computes window functions over sorted partitions.',
+    template: OBJECT
+  },
+  { name: '$densify', doc: 'Fills gaps in a sequence of values.', template: OBJECT },
+  { name: '$fill', doc: 'Fills null and missing values.', template: OBJECT },
+  { name: '$redact', doc: 'Restricts content by $$DESCEND / $$PRUNE / $$KEEP.', template: OBJECT },
+  {
+    name: '$geoNear',
+    doc: 'Orders documents by distance to a point.',
+    template: OBJECT,
+    firstOnly: true
+  },
+  { name: '$collStats', doc: 'Collection statistics.', template: OBJECT, firstOnly: true },
+  { name: '$indexStats', doc: 'Index usage statistics.', template: OBJECT, firstOnly: true },
+  {
+    name: '$documents',
+    doc: 'Literal input documents.',
+    template: ARRAY,
+    firstOnly: true,
+    subPipelineOnly: true
+  },
+  {
+    name: '$changeStream',
+    doc: 'Change stream (does not end).',
+    template: OBJECT,
+    firstOnly: true
+  },
+  { name: '$search', doc: 'Atlas Search full-text query.', template: OBJECT, firstOnly: true },
+  { name: '$searchMeta', doc: 'Atlas Search metadata.', template: OBJECT, firstOnly: true },
+  { name: '$vectorSearch', doc: 'Atlas Vector Search.', template: OBJECT, firstOnly: true },
+  { name: '$listSessions', doc: 'Sessions (config database).', template: OBJECT, firstOnly: true },
+  { name: '$listSearchIndexes', doc: 'Atlas Search indexes.', template: OBJECT, firstOnly: true },
+  { name: '$planCacheStats', doc: 'Plan cache entries.', template: OBJECT, firstOnly: true },
+  { name: '$out', doc: 'Writes the output to a collection.', template: STRING },
+  { name: '$merge', doc: 'Merges the output into a collection.', template: OBJECT }
+]
+
+/** A BSON type, or `number` for any numeric type. */
+export type TypeClass = BsonTypeName | 'number'
+
+/** BSON types of the `number` type class. */
+export const NUMERIC_TYPES: ReadonlySet<BsonTypeName> = new Set<BsonTypeName>([
+  'int',
+  'long',
+  'double',
+  'decimal'
+])
+
+/** Grammar of a named argument's value. */
+export type ArgKind =
+  | 'expression'
+  /** An expression that yields a date. */
+  | 'dateExpr'
+  /** An expression that yields a bool. */
+  | 'boolExpr'
+  | 'arrayRef'
+  | 'query'
+  | 'sort'
+  | 'projection'
+  /** Update operators document or update pipeline. */
+  | 'update'
+  /** A whole document of the collection. */
+  | 'document'
+  /** Conditions on the array elements the update's `$[identifier]`s stand for. */
+  | 'arrayFilters'
+  | 'fieldPath'
+  | 'fieldPaths'
+  | 'collection'
+  | 'pipeline'
+  | 'accumulators'
+  | 'windowOutput'
+  | 'fillOutput'
+  | 'vars'
+  | 'bool'
+  | 'number'
+  | 'string'
+  | 'object'
+  | 'array'
+  | 'any'
+  | { enum: readonly string[] }
+  /** Object with the named arguments of `ARG_SPECS[args]`. */
+  | { args: string }
+
+export type ArgSpec = {
+  name: string
+  kind: ArgKind
+  required?: boolean
+  /** An argument that cannot be given together with this one. */
+  excludes?: string
+}
+
+const quoted = (values: readonly string[]): readonly string[] =>
+  values.map((v) => JSON.stringify(v))
+const TIME_UNITS = quoted([
+  'year',
+  'quarter',
+  'month',
+  'week',
+  'day',
+  'hour',
+  'minute',
+  'second',
+  'millisecond'
+])
+const WEEKDAYS = quoted([
+  'monday',
+  'tuesday',
+  'wednesday',
+  'thursday',
+  'friday',
+  'saturday',
+  'sunday'
+])
+
+const req = (name: string, kind: ArgKind): ArgSpec => ({ name, kind, required: true })
+const opt = (name: string, kind: ArgKind): ArgSpec => ({ name, kind })
+
+/** `ARG_SPECS` owner of a write method's options object. */
+export const optionsOwner = (method: string): string => `${method}.options`
+
+/** `ARG_SPECS` owner of the body of a `bulkWrite` operation. */
+export const bulkOperationOwner = (operation: string): string => `bulkWrite.${operation}`
+
+// Most used first; options not listed here follow in their WRITE_OPTIONS order.
+const OPTION_ORDER = [
+  'upsert',
+  'returnDocument',
+  'returnNewDocument',
+  'projection',
+  'sort',
+  'arrayFilters',
+  'ordered',
+  'bypassDocumentValidation',
+  'hint',
+  'collation',
+  'let'
+]
+
+function optionSpecs(options: Readonly<Record<string, WriteOptionKind>>): ArgSpec[] {
+  const rank = (name: string): number => {
+    const index = OPTION_ORDER.indexOf(name)
+    return index === -1 ? OPTION_ORDER.length : index
+  }
+  return Object.entries(options)
+    .sort(([a], [b]) => rank(a) - rank(b))
+    .map(([name, kind]) => ({
+      name,
+      kind: optionKind(name, kind),
+      excludes: EXCLUSIVE_OPTIONS.find((pair) => pair.includes(name))?.find((key) => key !== name)
+    }))
+}
+
+function optionKind(name: string, kind: WriteOptionKind): ArgKind {
+  if (name === 'sort' || name === 'projection' || name === 'arrayFilters') return name
+  switch (kind) {
+    case 'boolean':
+      return 'bool'
+    case 'returnDocument':
+      return { enum: quoted(['after', 'before']) }
+    default:
+      return 'any'
+  }
+}
+
+// Grammar of each write field, in bulkWrite operations and as a write method argument.
+const FIELD_KINDS: Readonly<Record<WriteField, 'document' | 'query' | 'update'>> = {
+  document: 'document',
+  filter: 'query',
+  update: 'update',
+  replacement: 'document'
+}
+
+/** Named arguments of stages, nested stage objects and expression operators. */
+export const ARG_SPECS: Readonly<Record<string, readonly ArgSpec[]>> = {
+  $lookup: [
+    req('from', 'collection'),
+    opt('localField', 'fieldPath'),
+    opt('foreignField', 'fieldPath'),
+    req('as', 'string'),
+    opt('let', 'vars'),
+    opt('pipeline', 'pipeline')
+  ],
+  $graphLookup: [
+    req('from', 'collection'),
+    req('startWith', 'expression'),
+    req('connectFromField', 'fieldPath'),
+    req('connectToField', 'fieldPath'),
+    req('as', 'string'),
+    opt('maxDepth', 'number'),
+    opt('depthField', 'string'),
+    opt('restrictSearchWithMatch', 'query')
+  ],
+  $unwind: [
+    req('path', 'arrayRef'),
+    opt('includeArrayIndex', 'string'),
+    opt('preserveNullAndEmptyArrays', 'bool')
+  ],
+  $bucket: [
+    req('groupBy', 'expression'),
+    req('boundaries', 'array'),
+    opt('default', 'any'),
+    opt('output', 'accumulators')
+  ],
+  $bucketAuto: [
+    req('groupBy', 'expression'),
+    req('buckets', 'number'),
+    opt('output', 'accumulators'),
+    opt('granularity', {
+      enum: quoted([
+        'R5',
+        'R10',
+        'R20',
+        'R40',
+        'R80',
+        '1-2-5',
+        'E6',
+        'E12',
+        'E24',
+        'E48',
+        'E96',
+        'E192',
+        'POWERSOF2'
+      ])
+    })
+  ],
+  $replaceRoot: [req('newRoot', 'expression')],
+  $unionWith: [req('coll', 'collection'), opt('pipeline', 'pipeline')],
+  $merge: [
+    req('into', 'collection'),
+    opt('on', 'fieldPaths'),
+    opt('let', 'vars'),
+    opt('whenMatched', { enum: quoted(['replace', 'keepExisting', 'merge', 'fail']) }),
+    opt('whenNotMatched', { enum: quoted(['insert', 'discard', 'fail']) })
+  ],
+  $out: [opt('db', 'string'), req('coll', 'collection')],
+  $sample: [req('size', 'number')],
+  $setWindowFields: [
+    opt('partitionBy', 'expression'),
+    opt('sortBy', 'sort'),
+    req('output', 'windowOutput')
+  ],
+  $densify: [
+    req('field', 'fieldPath'),
+    opt('partitionByFields', 'fieldPaths'),
+    req('range', { args: '$densify.range' })
+  ],
+  '$densify.range': [
+    req('step', 'number'),
+    opt('unit', { enum: TIME_UNITS }),
+    req('bounds', 'any')
+  ],
+  $fill: [
+    opt('partitionBy', 'expression'),
+    opt('partitionByFields', 'fieldPaths'),
+    opt('sortBy', 'sort'),
+    req('output', 'fillOutput')
+  ],
+  '$fill.output': [opt('value', 'expression'), opt('method', { enum: quoted(['linear', 'locf']) })],
+  $geoNear: [
+    req('near', 'any'),
+    req('distanceField', 'string'),
+    opt('spherical', 'bool'),
+    opt('maxDistance', 'number'),
+    opt('minDistance', 'number'),
+    opt('query', 'query'),
+    opt('includeLocs', 'string'),
+    opt('distanceMultiplier', 'number'),
+    opt('key', 'fieldPath')
+  ],
+  $collStats: [
+    opt('latencyStats', 'object'),
+    opt('storageStats', 'object'),
+    opt('count', 'object'),
+    opt('queryExecStats', 'object')
+  ],
+  window: [opt('documents', 'array'), opt('range', 'array'), opt('unit', { enum: TIME_UNITS })],
+  $filter: [
+    req('input', 'expression'),
+    req('cond', 'boolExpr'),
+    opt('as', 'string'),
+    opt('limit', 'expression')
+  ],
+  $map: [req('input', 'expression'), opt('as', 'string'), req('in', 'expression')],
+  $reduce: [req('input', 'expression'), req('initialValue', 'expression'), req('in', 'expression')],
+  $firstN: [req('n', 'expression'), req('input', 'expression')],
+  $lastN: [req('n', 'expression'), req('input', 'expression')],
+  $maxN: [req('n', 'expression'), req('input', 'expression')],
+  $minN: [req('n', 'expression'), req('input', 'expression')],
+  $sortArray: [req('input', 'expression'), req('sortBy', 'any')],
+  $zip: [
+    req('inputs', 'expression'),
+    opt('useLongestLength', 'bool'),
+    opt('defaults', 'expression')
+  ],
+  $cond: [req('if', 'boolExpr'), req('then', 'expression'), req('else', 'expression')],
+  $switch: [req('branches', 'array'), opt('default', 'expression')],
+  $dateAdd: [
+    req('startDate', 'dateExpr'),
+    req('unit', { enum: TIME_UNITS }),
+    req('amount', 'expression'),
+    opt('timezone', 'expression')
+  ],
+  $dateSubtract: [
+    req('startDate', 'dateExpr'),
+    req('unit', { enum: TIME_UNITS }),
+    req('amount', 'expression'),
+    opt('timezone', 'expression')
+  ],
+  $dateDiff: [
+    req('startDate', 'dateExpr'),
+    req('endDate', 'dateExpr'),
+    req('unit', { enum: TIME_UNITS }),
+    opt('timezone', 'expression'),
+    opt('startOfWeek', { enum: WEEKDAYS })
+  ],
+  $dateFromParts: [
+    opt('year', 'expression'),
+    opt('month', 'expression'),
+    opt('day', 'expression'),
+    opt('hour', 'expression'),
+    opt('minute', 'expression'),
+    opt('second', 'expression'),
+    opt('millisecond', 'expression'),
+    opt('isoWeekYear', 'expression'),
+    opt('isoWeek', 'expression'),
+    opt('isoDayOfWeek', 'expression'),
+    opt('timezone', 'expression')
+  ],
+  $dateFromString: [
+    req('dateString', 'expression'),
+    opt('format', 'string'),
+    opt('timezone', 'expression'),
+    opt('onError', 'expression'),
+    opt('onNull', 'expression')
+  ],
+  $dateToParts: [req('date', 'dateExpr'), opt('timezone', 'expression'), opt('iso8601', 'bool')],
+  $dateToString: [
+    req('date', 'dateExpr'),
+    opt('format', 'string'),
+    opt('timezone', 'expression'),
+    opt('onNull', 'expression')
+  ],
+  $dateTrunc: [
+    req('date', 'dateExpr'),
+    req('unit', { enum: TIME_UNITS }),
+    opt('binSize', 'expression'),
+    opt('timezone', 'expression'),
+    opt('startOfWeek', { enum: WEEKDAYS })
+  ],
+  $let: [req('vars', 'vars'), req('in', 'expression')],
+  $getField: [req('field', 'string'), opt('input', 'expression')],
+  $setField: [req('field', 'string'), req('input', 'expression'), req('value', 'expression')],
+  $unsetField: [req('field', 'string'), req('input', 'expression')],
+  $trim: [req('input', 'expression'), opt('chars', 'expression')],
+  $ltrim: [req('input', 'expression'), opt('chars', 'expression')],
+  $rtrim: [req('input', 'expression'), opt('chars', 'expression')],
+  $regexFind: [req('input', 'expression'), req('regex', 'any'), opt('options', 'string')],
+  $regexFindAll: [req('input', 'expression'), req('regex', 'any'), opt('options', 'string')],
+  $regexMatch: [req('input', 'expression'), req('regex', 'any'), opt('options', 'string')],
+  $replaceOne: [
+    req('input', 'expression'),
+    req('find', 'expression'),
+    req('replacement', 'expression')
+  ],
+  $replaceAll: [
+    req('input', 'expression'),
+    req('find', 'expression'),
+    req('replacement', 'expression')
+  ],
+  $convert: [
+    req('input', 'expression'),
+    req('to', {
+      enum: quoted([
+        'double',
+        'string',
+        'objectId',
+        'bool',
+        'date',
+        'int',
+        'long',
+        'decimal',
+        'binData'
+      ])
+    }),
+    opt('onError', 'expression'),
+    opt('onNull', 'expression')
+  ],
+  '$currentDate.field': [req('$type', { enum: quoted(['date', 'timestamp']) })],
+  '$bit.field': [opt('and', 'number'), opt('or', 'number'), opt('xor', 'number')],
+  ...Object.fromEntries(
+    Object.entries(WRITE_OPTIONS).map(([method, options]) => [
+      optionsOwner(method),
+      optionSpecs(options)
+    ])
+  ),
+  ...Object.fromEntries(
+    BULK_WRITE_OPERATIONS.map((operation) => [
+      bulkOperationOwner(operation),
+      [
+        ...BULK_OPERATION_FIELDS[operation].map((field) => req(field, FIELD_KINDS[field])),
+        ...optionSpecs(BULK_OPERATION_OPTIONS[operation])
+      ]
+    ])
+  )
+}
+
+/** How an expression operator takes its arguments. */
+export type OperatorForm = 'positional' | 'single' | 'named' | 'none'
+
+export type ExpressionOperator = {
+  name: string
+  doc: string
+  form: OperatorForm
+  returns?: BsonTypeName
+  /** Type its arguments usually have; `compared`: the arguments are compared with each other. */
+  args?: TypeClass | 'compared'
+}
+
+const expr = (
+  name: string,
+  form: OperatorForm,
+  doc: string,
+  returns?: BsonTypeName,
+  args?: TypeClass | 'compared'
+): ExpressionOperator => ({
+  name,
+  form,
+  doc,
+  returns,
+  args
+})
+
+export const EXPRESSION_OPERATORS: readonly ExpressionOperator[] = [
+  expr('$abs', 'single', 'Absolute value.', 'double', 'number'),
+  expr('$add', 'positional', 'Sum of numbers, or a date plus milliseconds.', 'double', 'number'),
+  expr('$ceil', 'single', 'Smallest integer ≥ the number.', 'double', 'number'),
+  expr('$divide', 'positional', 'Divides the first number by the second.', 'double', 'number'),
+  expr('$exp', 'single', 'e raised to the number.', 'double', 'number'),
+  expr('$floor', 'single', 'Largest integer ≤ the number.', 'double', 'number'),
+  expr('$ln', 'single', 'Natural logarithm.', 'double', 'number'),
+  expr('$log', 'positional', 'Logarithm in a base.', 'double', 'number'),
+  expr('$log10', 'single', 'Base-10 logarithm.', 'double', 'number'),
+  expr('$mod', 'positional', 'Remainder of a division.', 'double', 'number'),
+  expr('$multiply', 'positional', 'Product of numbers.', 'double', 'number'),
+  expr('$pow', 'positional', 'Number raised to an exponent.', 'double', 'number'),
+  expr('$round', 'positional', 'Rounds to a decimal place.', 'double', 'number'),
+  expr('$sqrt', 'single', 'Square root.', 'double', 'number'),
+  expr('$subtract', 'positional', 'Difference of numbers or dates.', 'double', 'number'),
+  expr('$trunc', 'positional', 'Truncates to a decimal place.', 'double', 'number'),
+  expr('$arrayElemAt', 'positional', 'Element at an index.'),
+  expr('$arrayToObject', 'single', 'Converts [k, v] pairs to an object.', 'object', 'array'),
+  expr('$concatArrays', 'positional', 'Concatenates arrays.', 'array', 'array'),
+  expr('$filter', 'named', 'Elements that match a condition.', 'array'),
+  expr('$first', 'single', 'First array element.', undefined, 'array'),
+  expr('$firstN', 'named', 'First n array elements.', 'array'),
+  expr('$in', 'positional', 'The value is in the array.', 'bool'),
+  expr('$indexOfArray', 'positional', 'Index of a value in an array.', 'int'),
+  expr('$isArray', 'positional', 'The value is an array.', 'bool'),
+  expr('$last', 'single', 'Last array element.', undefined, 'array'),
+  expr('$lastN', 'named', 'Last n array elements.', 'array'),
+  expr('$map', 'named', 'Applies an expression to each element.', 'array'),
+  expr('$maxN', 'named', 'n largest array elements.', 'array'),
+  expr('$minN', 'named', 'n smallest array elements.', 'array'),
+  expr('$objectToArray', 'single', 'Converts an object to [k, v] pairs.', 'array', 'object'),
+  expr('$range', 'positional', 'Sequence of integers.', 'array'),
+  expr('$reduce', 'named', 'Folds an array into one value.'),
+  expr('$reverseArray', 'single', 'Array in reverse order.', 'array', 'array'),
+  expr('$size', 'single', 'Number of array elements.', 'int', 'array'),
+  expr('$slice', 'positional', 'Subset of an array.', 'array'),
+  expr('$sortArray', 'named', 'Sorted array.', 'array'),
+  expr('$zip', 'named', 'Transposes arrays.', 'array'),
+  expr('$and', 'positional', 'True when every expression is true.', 'bool', 'bool'),
+  expr('$or', 'positional', 'True when any expression is true.', 'bool', 'bool'),
+  expr('$not', 'positional', 'Negates an expression.', 'bool', 'bool'),
+  expr('$cmp', 'positional', '-1, 0 or 1 comparing two values.', 'int', 'compared'),
+  expr('$eq', 'positional', 'Values are equal.', 'bool', 'compared'),
+  expr('$ne', 'positional', 'Values are not equal.', 'bool', 'compared'),
+  expr('$gt', 'positional', 'First value is greater.', 'bool', 'compared'),
+  expr('$gte', 'positional', 'First value is greater or equal.', 'bool', 'compared'),
+  expr('$lt', 'positional', 'First value is less.', 'bool', 'compared'),
+  expr('$lte', 'positional', 'First value is less or equal.', 'bool', 'compared'),
+  expr('$cond', 'named', 'If-then-else.'),
+  expr('$ifNull', 'positional', 'First non-null value.'),
+  expr('$switch', 'named', 'First branch whose case is true.'),
+  expr('$dateAdd', 'named', 'Adds a time span to a date.', 'date'),
+  expr('$dateDiff', 'named', 'Difference between dates in a unit.', 'long'),
+  expr('$dateFromParts', 'named', 'Date from its parts.', 'date'),
+  expr('$dateFromString', 'named', 'Parses a date string.', 'date'),
+  expr('$dateSubtract', 'named', 'Subtracts a time span from a date.', 'date'),
+  expr('$dateToParts', 'named', 'Parts of a date.', 'object'),
+  expr('$dateToString', 'named', 'Formats a date.', 'string'),
+  expr('$dateTrunc', 'named', 'Truncates a date to a unit.', 'date'),
+  expr('$dayOfMonth', 'single', 'Day of month, 1-31.', 'int', 'date'),
+  expr('$dayOfWeek', 'single', 'Day of week, 1 (Sunday) - 7.', 'int', 'date'),
+  expr('$dayOfYear', 'single', 'Day of year, 1-366.', 'int', 'date'),
+  expr('$hour', 'single', 'Hour, 0-23.', 'int', 'date'),
+  expr('$isoDayOfWeek', 'single', 'ISO weekday, 1 (Monday) - 7.', 'int', 'date'),
+  expr('$isoWeek', 'single', 'ISO week number.', 'int', 'date'),
+  expr('$isoWeekYear', 'single', 'ISO week-numbering year.', 'int', 'date'),
+  expr('$millisecond', 'single', 'Milliseconds, 0-999.', 'int', 'date'),
+  expr('$minute', 'single', 'Minute, 0-59.', 'int', 'date'),
+  expr('$month', 'single', 'Month, 1-12.', 'int', 'date'),
+  expr('$second', 'single', 'Second, 0-60.', 'int', 'date'),
+  expr('$week', 'single', 'Week of year, 0-53.', 'int', 'date'),
+  expr('$year', 'single', 'Year.', 'int', 'date'),
+  expr('$literal', 'single', 'A value taken literally, not as an expression.'),
+  expr('$rand', 'none', 'Random number in [0, 1).', 'double'),
+  expr('$let', 'named', 'Binds variables for an expression.'),
+  expr('$getField', 'named', 'Value of a field, including names with $ or dots.'),
+  expr('$setField', 'named', 'Object with a field set.', 'object'),
+  expr('$unsetField', 'named', 'Object with a field removed.', 'object'),
+  expr('$mergeObjects', 'positional', 'Merges objects.', 'object', 'object'),
+  expr('$allElementsTrue', 'positional', 'No array element is false.', 'bool', 'array'),
+  expr('$anyElementTrue', 'positional', 'Some array element is true.', 'bool', 'array'),
+  expr(
+    '$setDifference',
+    'positional',
+    'Elements of the first set not in the second.',
+    'array',
+    'array'
+  ),
+  expr('$setEquals', 'positional', 'Sets contain the same elements.', 'bool', 'array'),
+  expr('$setIntersection', 'positional', 'Elements in every set.', 'array', 'array'),
+  expr('$setIsSubset', 'positional', 'First set is a subset of the second.', 'bool', 'array'),
+  expr('$setUnion', 'positional', 'Elements in any set.', 'array', 'array'),
+  expr('$concat', 'positional', 'Concatenates strings.', 'string', 'string'),
+  expr('$indexOfBytes', 'positional', 'Byte index of a substring.', 'int', 'string'),
+  expr('$indexOfCP', 'positional', 'Code-point index of a substring.', 'int', 'string'),
+  expr('$ltrim', 'named', 'Removes leading characters.', 'string'),
+  expr('$regexFind', 'named', 'First regex match.', 'object'),
+  expr('$regexFindAll', 'named', 'All regex matches.', 'array'),
+  expr('$regexMatch', 'named', 'The string matches a regex.', 'bool'),
+  expr('$replaceAll', 'named', 'Replaces every occurrence.', 'string'),
+  expr('$replaceOne', 'named', 'Replaces the first occurrence.', 'string'),
+  expr('$rtrim', 'named', 'Removes trailing characters.', 'string'),
+  expr('$split', 'positional', 'Splits a string by a delimiter.', 'array', 'string'),
+  expr('$strcasecmp', 'positional', 'Case-insensitive comparison.', 'int', 'string'),
+  expr('$strLenBytes', 'single', 'Length in UTF-8 bytes.', 'int', 'string'),
+  expr('$strLenCP', 'single', 'Length in code points.', 'int', 'string'),
+  expr('$substrBytes', 'positional', 'Substring by bytes.', 'string', 'string'),
+  expr('$substrCP', 'positional', 'Substring by code points.', 'string', 'string'),
+  expr('$toLower', 'single', 'Lowercase string.', 'string', 'string'),
+  expr('$toUpper', 'single', 'Uppercase string.', 'string', 'string'),
+  expr('$trim', 'named', 'Removes leading and trailing characters.', 'string'),
+  expr('$convert', 'named', 'Converts to a type, with error handling.'),
+  expr('$isNumber', 'single', 'The value is a number.', 'bool'),
+  expr('$toBool', 'single', 'Converts to bool.', 'bool'),
+  expr('$toDate', 'single', 'Converts to date.', 'date'),
+  expr('$toDecimal', 'single', 'Converts to decimal.', 'decimal'),
+  expr('$toDouble', 'single', 'Converts to double.', 'double'),
+  expr('$toInt', 'single', 'Converts to int.', 'int'),
+  expr('$toLong', 'single', 'Converts to long.', 'long'),
+  expr('$toObjectId', 'single', 'Converts to ObjectId.', 'objectId'),
+  expr('$toString', 'single', 'Converts to string.', 'string'),
+  expr('$type', 'single', 'BSON type name of the value.', 'string'),
+  expr('$sum', 'positional', 'Sum of numbers.', 'double', 'number'),
+  expr('$avg', 'positional', 'Average of numbers.', 'double', 'number'),
+  expr('$max', 'positional', 'Largest value.'),
+  expr('$min', 'positional', 'Smallest value.')
+]
+
+/** `EXPRESSION_OPERATORS` by name. */
+export const EXPRESSIONS: ReadonlyMap<string, ExpressionOperator> = new Map(
+  EXPRESSION_OPERATORS.map((op) => [op.name, op])
+)
+
+/** Result type of an accumulator: a BSON type, or derived from its argument. */
+export type AccumulatorResult = BsonTypeName | 'arg' | 'argArray' | 'sum' | 'output'
+
+export type AccumulatorDef = KeyDef & {
+  returns: AccumulatorResult
+  windowOnly?: boolean
+  /** Type its argument usually has. */
+  args?: TypeClass
+}
+
+const acc = (
+  name: string,
+  doc: string,
+  returns: AccumulatorResult,
+  template: Template,
+  extra: { retrigger?: boolean; windowOnly?: boolean; args?: TypeClass } = {}
+): AccumulatorDef => ({ name, doc, returns, template, ...extra })
+
+const REF_ARG = { retrigger: true }
+const NUMBER_REF_ARG = { retrigger: true, args: 'number' } as const
+
+export const ACCUMULATORS: readonly AccumulatorDef[] = [
+  acc('$sum', 'Sum; `1` counts documents.', 'sum', () => '${0:1}', { args: 'number' }),
+  acc('$avg', 'Average.', 'double', FIELD_REF, NUMBER_REF_ARG),
+  acc('$min', 'Smallest value.', 'arg', FIELD_REF, REF_ARG),
+  acc('$max', 'Largest value.', 'arg', FIELD_REF, REF_ARG),
+  acc('$first', 'Value of the first document.', 'arg', FIELD_REF, REF_ARG),
+  acc('$last', 'Value of the last document.', 'arg', FIELD_REF, REF_ARG),
+  acc('$push', 'Array of all values.', 'argArray', FIELD_REF, REF_ARG),
+  acc('$addToSet', 'Array of distinct values.', 'argArray', FIELD_REF, REF_ARG),
+  acc('$count', 'Number of documents.', 'int', () => '{}'),
+  acc('$mergeObjects', 'Merges the objects.', 'arg', FIELD_REF, REF_ARG),
+  acc('$stdDevPop', 'Population standard deviation.', 'double', FIELD_REF, NUMBER_REF_ARG),
+  acc('$stdDevSamp', 'Sample standard deviation.', 'double', FIELD_REF, NUMBER_REF_ARG),
+  acc(
+    '$top',
+    'Output of the top document by sortBy.',
+    'output',
+    (k) => `{ ${k('sortBy')}: { $1 }, ${k('output')}: "\\$$0" }`
+  ),
+  acc(
+    '$bottom',
+    'Output of the bottom document by sortBy.',
+    'output',
+    (k) => `{ ${k('sortBy')}: { $1 }, ${k('output')}: "\\$$0" }`
+  ),
+  acc(
+    '$topN',
+    'Outputs of the top n documents.',
+    'array',
+    (k) => `{ ${k('n')}: \${1:1}, ${k('sortBy')}: { $2 }, ${k('output')}: "\\$$0" }`
+  ),
+  acc(
+    '$bottomN',
+    'Outputs of the bottom n documents.',
+    'array',
+    (k) => `{ ${k('n')}: \${1:1}, ${k('sortBy')}: { $2 }, ${k('output')}: "\\$$0" }`
+  ),
+  acc(
+    '$firstN',
+    'First n values.',
+    'array',
+    (k) => `{ ${k('n')}: \${1:1}, ${k('input')}: "\\$$0" }`
+  ),
+  acc('$lastN', 'Last n values.', 'array', (k) => `{ ${k('n')}: \${1:1}, ${k('input')}: "\\$$0" }`),
+  acc(
+    '$maxN',
+    'n largest values.',
+    'array',
+    (k) => `{ ${k('n')}: \${1:1}, ${k('input')}: "\\$$0" }`
+  ),
+  acc(
+    '$minN',
+    'n smallest values.',
+    'array',
+    (k) => `{ ${k('n')}: \${1:1}, ${k('input')}: "\\$$0" }`
+  ),
+  acc(
+    '$median',
+    'Approximate median.',
+    'double',
+    (k) => `{ ${k('input')}: "\\$$0", ${k('method')}: "approximate" }`
+  ),
+  acc(
+    '$percentile',
+    'Approximate percentiles.',
+    'array',
+    (k) => `{ ${k('input')}: "\\$$1", ${k('p')}: [\${0:0.95}], ${k('method')}: "approximate" }`
+  ),
+  acc('$rank', 'Rank by sortBy, with gaps.', 'int', () => '{}', { windowOnly: true }),
+  acc('$denseRank', 'Rank by sortBy, without gaps.', 'int', () => '{}', { windowOnly: true }),
+  acc('$documentNumber', 'Position in the partition.', 'int', () => '{}', { windowOnly: true }),
+  acc(
+    '$shift',
+    'Value of a document at an offset.',
+    'output',
+    (k) => `{ ${k('output')}: "\\$$1", ${k('by')}: \${0:1} }`,
+    { windowOnly: true }
+  ),
+  acc('$derivative', 'Rate of change.', 'double', (k) => `{ ${k('input')}: "\\$$0" }`, {
+    windowOnly: true
+  }),
+  acc('$integral', 'Area under the curve.', 'double', (k) => `{ ${k('input')}: "\\$$0" }`, {
+    windowOnly: true
+  }),
+  acc(
+    '$expMovingAvg',
+    'Exponential moving average.',
+    'double',
+    (k) => `{ ${k('input')}: "\\$$1", ${k('N')}: \${0:3} }`,
+    { windowOnly: true }
+  ),
+  acc('$covariancePop', 'Population covariance.', 'double', () => '["\\$$1", "\\$$0"]', {
+    windowOnly: true
+  }),
+  acc('$covarianceSamp', 'Sample covariance.', 'double', () => '["\\$$1", "\\$$0"]', {
+    windowOnly: true
+  }),
+  acc('$linearFill', 'Fills nulls by linear interpolation.', 'arg', FIELD_REF, {
+    retrigger: true,
+    windowOnly: true
+  }),
+  acc('$locf', 'Fills nulls with the last non-null value.', 'arg', FIELD_REF, {
+    retrigger: true,
+    windowOnly: true
+  })
+]
+
+/** `ACCUMULATORS` by name. */
+export const ACCUMULATOR_DEFS: ReadonlyMap<string, AccumulatorDef> = new Map(
+  ACCUMULATORS.map((def) => [def.name, def])
+)
+
+/** Window bounds next to a window accumulator. */
+export const WINDOW_KEY: KeyDef = {
+  name: 'window',
+  doc: 'Window bounds: documents or range.',
+  template: OBJECT,
+  retrigger: true
+}
+
+/** BSON type each shell constructor produces. */
+export const CONSTRUCTOR_TYPES: Readonly<Record<string, BsonTypeName>> = {
+  ObjectId: 'objectId',
+  ISODate: 'date',
+  Date: 'date',
+  NumberLong: 'long',
+  Long: 'long',
+  NumberInt: 'int',
+  Int32: 'int',
+  NumberDecimal: 'decimal',
+  Decimal128: 'decimal',
+  NumberDouble: 'double',
+  Double: 'double',
+  UUID: 'uuid',
+  JUUID: 'uuidLegacy',
+  BinData: 'binData',
+  Timestamp: 'timestamp',
+  Code: 'javascript',
+  RegExp: 'regex',
+  Symbol: 'symbol',
+  DBRef: 'dbRef',
+  MinKey: 'minKey',
+  MaxKey: 'maxKey'
+}
+
+/** System variables, without the `$$` prefix. */
+export const SYSTEM_VARIABLES: readonly string[] = [
+  'ROOT',
+  'CURRENT',
+  'NOW',
+  'REMOVE',
+  'CLUSTER_TIME'
+]
+
+/** Grammar of a shell method argument; `options` is the options object of a write method. */
+export type ShellArg =
+  | 'query'
+  | 'projection'
+  | 'pipeline'
+  | 'sort'
+  | 'fieldName'
+  | 'document'
+  | 'documents'
+  | 'update'
+  | 'bulkOperations'
+  | 'options'
+
+const WRITE_ARGUMENT_KINDS: Readonly<Record<WriteArgument, ShellArg>> = {
+  ...FIELD_KINDS,
+  documents: 'documents',
+  operations: 'bulkOperations'
+}
+
+/** Argument grammars of collection methods, by position. */
+export const SHELL_METHOD_ARGS: Readonly<Record<string, readonly ShellArg[]>> = {
+  find: ['query', 'projection'],
+  findOne: ['query', 'projection'],
+  aggregate: ['pipeline'],
+  countDocuments: ['query'],
+  count: ['query'],
+  estimatedDocumentCount: [],
+  distinct: ['fieldName', 'query'],
+  ...Object.fromEntries(
+    Object.entries(WRITE_ARGUMENTS).map(([method, args]): [string, ShellArg[]] => [
+      method,
+      [...args.map((arg) => WRITE_ARGUMENT_KINDS[arg]), 'options']
+    ])
+  )
+}
+
+/** Argument grammars of cursor methods after `find(…)`, by position. */
+export const SHELL_CURSOR_ARGS: Readonly<Record<string, readonly ShellArg[]>> = {
+  sort: ['sort'],
+  projection: ['projection'],
+  skip: [],
+  limit: [],
+  toArray: [],
+  pretty: []
+}
+
+export type MethodDef = { template: string; doc: string; retrigger?: boolean }
+
+const objectCall = (method: string, doc: string): MethodDef => ({
+  template: `${method}({ $0 })`,
+  doc,
+  retrigger: true
+})
+
+const WRITE_METHOD_DEFS: Readonly<Record<WriteMethod, MethodDef>> = {
+  insertOne: objectCall('insertOne', 'Inserts a document.'),
+  insertMany: { template: 'insertMany([{ $0 }])', doc: 'Inserts documents.', retrigger: true },
+  updateOne: objectCall('updateOne', 'Updates the first document matching a filter.'),
+  updateMany: objectCall('updateMany', 'Updates every document matching a filter.'),
+  replaceOne: objectCall('replaceOne', 'Replaces the first document matching a filter.'),
+  deleteOne: objectCall('deleteOne', 'Deletes the first document matching a filter.'),
+  deleteMany: objectCall('deleteMany', 'Deletes every document matching a filter.'),
+  findOneAndUpdate: objectCall(
+    'findOneAndUpdate',
+    'Updates the first matching document and returns it.'
+  ),
+  findOneAndReplace: objectCall(
+    'findOneAndReplace',
+    'Replaces the first matching document and returns it.'
+  ),
+  findOneAndDelete: objectCall(
+    'findOneAndDelete',
+    'Deletes the first matching document and returns it.'
+  ),
+  bulkWrite: {
+    template: 'bulkWrite([$0])',
+    doc: 'Runs insert, update, replace and delete operations in one call.',
+    retrigger: true
+  }
+}
+
+/** Call templates of shell collection and cursor methods. */
+export const SHELL_METHODS: Readonly<Record<string, MethodDef>> = {
+  ...WRITE_METHOD_DEFS,
+  find: objectCall('find', 'Documents matching a filter; chain sort, skip, limit, projection.'),
+  findOne: objectCall('findOne', 'The first document matching a filter.'),
+  aggregate: {
+    template: 'aggregate([$0])',
+    doc: 'Runs an aggregation pipeline; a final $out or $merge writes its output.',
+    retrigger: true
+  },
+  countDocuments: objectCall('countDocuments', 'Exact count of matching documents.'),
+  count: objectCall('count', 'Count; an empty filter uses the metadata estimate.'),
+  estimatedDocumentCount: {
+    template: 'estimatedDocumentCount()',
+    doc: 'Count from collection metadata.'
+  },
+  distinct: { template: 'distinct("$0")', doc: 'Distinct values of a field.', retrigger: true },
+  sort: objectCall('sort', 'Sort order.'),
+  skip: { template: 'skip(${0:0})', doc: 'Skips documents.' },
+  limit: { template: 'limit(${0:50})', doc: 'Maximum number of documents.' },
+  projection: objectCall('projection', 'Fields to include or exclude.'),
+  toArray: { template: 'toArray()', doc: 'All results as an array.' },
+  pretty: { template: 'pretty()', doc: 'Formatted output (no effect here).' }
+}
diff --git a/src/renderer/src/lib/completion/context.test.ts b/src/renderer/src/lib/completion/context.test.ts
new file mode 100644
index 0000000..17527b4
--- /dev/null
+++ b/src/renderer/src/lib/completion/context.test.ts
@@ -0,0 +1,588 @@
+import { describe, expect, it } from 'vitest'
+import { analyzeContext, type EditorKind } from './context'
+
+/** Analyzes `marked` at its `|` marker in an editor bound to `users`. */
+const at = (marked: string, kind: EditorKind) => {
+  const offset = marked.indexOf('|')
+  return analyzeContext(marked.slice(0, offset) + marked.slice(offset + 1), offset, kind, 'users')
+}
+
+describe('analyzeContext: positions', () => {
+  it.each<[string, EditorKind, Record<string, unknown>]>([
+    ['{ "_id": |', 'filter', { at: 'queryValue', field: '_id', operator: null, inArray: false }],
+    ['{ age: { $g|', 'filter', { at: 'operatorKey', field: 'age', present: [] }],
+    ['{ $or: [ { na|', 'filter', { at: 'queryKey', base: '', topLevel: true }],
+    ['{ items: { $elemMatch: { s|', 'filter', { at: 'elemMatchKey', field: 'items' }],
+    ['{ items: { $elemMatch: { qty: |', 'filter', { at: 'queryValue', field: 'items.qty' }],
+    [
+      '{ a: { $in: [ObjectId("x"), |',
+      'filter',
+      { at: 'queryValue', field: 'a', operator: '$in', inArray: true, siblings: ['ObjectId("x")'] }
+    ],
+    ['{ a: { $in: |', 'filter', { at: 'queryValue', field: 'a', operator: '$in', inArray: false }],
+    ['{ a: { $type: |', 'filter', { at: 'typeAlias', field: 'a' }],
+    ['{ a: { $type: ["string", |', 'filter', { at: 'typeAlias', field: 'a' }],
+    [
+      '{ a: { $exists: |',
+      'filter',
+      { at: 'literal', values: ['true', 'false'], preferred: 'true' }
+    ],
+    ['{ a: { $not: { |', 'filter', { at: 'operatorKey', field: 'a' }],
+    ['{ a: { $geoWithin: { |', 'filter', { at: 'geoKey' }],
+    ['{ $text: { |', 'filter', { at: 'textKey' }],
+    ['{ $jsonSchema: { properties: { |', 'filter', { at: 'queryKey', topLevel: false }],
+    ['{ $jsonSchema: { |', 'filter', { at: 'jsonSchemaKey' }],
+    ['{ $expr: { $eq: ["$|', 'filter', { at: 'expressionValue' }],
+    ['{ $expr: { |', 'filter', { at: 'expressionKey' }],
+    ['{ a: ObjectId("|', 'filter', { at: 'ctorArg', field: 'a', ctor: 'ObjectId' }],
+    [
+      '{ tags: ["a", |',
+      'filter',
+      { at: 'queryValue', field: 'tags', inArray: true, siblings: ['"a"'] }
+    ],
+    ['[ |', 'pipeline', { at: 'stageElement', stageIndex: 0 }],
+    ['|', 'pipeline', { at: 'rootValue', expect: 'array' }],
+    ['|', 'filter', { at: 'rootValue', expect: 'object' }],
+    ['[{ $match: {} }, { |', 'pipeline', { at: 'stageKey', stageIndex: 1, present: [] }],
+    ['[{ $group: { _id: "$|', 'pipeline', { at: 'expressionValue' }],
+    ['[{ $group: { _id: null, total: { |', 'pipeline', { at: 'accumulatorKey', window: false }],
+    ['[{ $group: { |', 'pipeline', { at: 'newFieldKey', group: true }],
+    ['[{ $lookup: { from: "|', 'pipeline', { at: 'collectionName' }],
+    ['[{ $lookup: { |', 'pipeline', { at: 'stageArgKey', stage: '$lookup' }],
+    ['[{ $unwind: |', 'pipeline', { at: 'expressionValue', prefer: 'array' }],
+    [
+      '[{ $unwind: { preserveNullAndEmptyArrays: |',
+      'pipeline',
+      { at: 'literal', values: ['true', 'false'] }
+    ],
+    ['[{ $project: { a: 1, |', 'pipeline', { at: 'projectionKey', present: ['a'] }],
+    ['[{ $sort: { a: |', 'pipeline', { at: 'sortValue', field: 'a' }],
+    [
+      '[{ $addFields: { x: { $dateToString: { |',
+      'pipeline',
+      { at: 'operatorArgKey', operator: '$dateToString' }
+    ],
+    ['[{ $addFields: { x: { $dateAdd: { unit: |', 'pipeline', { at: 'literal' }],
+    ['[{ $setWindowFields: { output: { r: { |', 'pipeline', { at: 'accumulatorKey', window: true }],
+    ['[{ $densify: { range: { |', 'pipeline', { at: 'stageArgKey', stage: '$densify.range' }],
+    ['{ name: 1, |', 'projection', { at: 'projectionKey', present: ['name'] }],
+    ['{ name: 1, a: |', 'projection', { at: 'projectionValue', field: 'a', mode: 'include' }],
+    ['{ name: 0, a: |', 'projection', { at: 'projectionValue', mode: 'exclude' }],
+    ['{ _id: 0, a: |', 'projection', { at: 'projectionValue', mode: null }],
+    ['{ name: |', 'projection', { at: 'projectionValue', field: 'name' }],
+    ['{ items: { |', 'projection', { at: 'projectionOperatorKey', field: 'items' }],
+    ['{ createdAt: |', 'sort', { at: 'sortValue', field: 'createdAt' }],
+    ['{ |', 'sort', { at: 'sortKey' }],
+    ['db.|', 'shell', { at: 'shellCollection' }],
+    ['db.users.|', 'shell', { at: 'shellMethod', coll: 'users' }],
+    ['db.users.fi|', 'shell', { at: 'shellMethod', coll: 'users' }],
+    ['db.a.b.|', 'shell', { at: 'shellMethod', coll: 'a.b' }],
+    [
+      'db.users.find({}).limit(5).|',
+      'shell',
+      { at: 'shellCursorMethod', head: 'find', used: ['limit'] }
+    ],
+    ['db.users.aggregate([]).|', 'shell', { at: 'shellCursorMethod', head: 'aggregate', used: [] }],
+    ['d|', 'shell', { at: 'shellRoot' }],
+    ['db.getCollection("|', 'shell', { at: 'collectionName' }],
+    ['db["|', 'shell', { at: 'collectionName' }],
+    ['db.users.find({}).sort({ |', 'shell', { at: 'sortKey' }],
+    ['db.users.find({}, { |', 'shell', { at: 'projectionKey' }],
+    ['db.users.distinct("|', 'shell', { at: 'fieldName' }],
+    ['db.users.estimatedDocumentCount(|', 'shell', { at: 'none' }],
+    ['db.users.aggregate([{ $match: { |', 'shell', { at: 'queryKey' }],
+    ['{ address: { ci|', 'document', { at: 'documentKey', path: 'address' }],
+    ['{ items: [ { s|', 'document', { at: 'documentKey', path: 'items' }],
+    ['[{ a: 1 }, { |', 'document', { at: 'documentKey', path: '', present: [] }],
+    ['{ a: 1 }, { b: 2, |', 'document', { at: 'documentKey', path: '', present: ['b'] }],
+    ['{ tags: [ |', 'document', { at: 'documentValue', path: 'tags', element: true }],
+    ['{ tags: |', 'document', { at: 'documentValue', path: 'tags', element: false }],
+    ['{ _id: ObjectId("|', 'document', { at: 'ctorArg', field: '_id', ctor: 'ObjectId' }]
+  ])('%s (%s)', (marked, kind, expected) => {
+    expect(at(marked, kind).position).toMatchObject(expected)
+  })
+})
+
+describe('analyzeContext: key and value slots', () => {
+  it('offers keys after a comma, not values', () => {
+    expect(at('{ a: 1, |', 'filter').position).toMatchObject({ at: 'queryKey', present: ['a'] })
+  })
+
+  it('treats a comma inside an array as an array element', () => {
+    expect(at('{ a: [1, |', 'filter').position).toMatchObject({ at: 'queryValue', inArray: true })
+  })
+
+  it('stays inside a string value', () => {
+    const ctx = at('{ a: "x, |', 'filter')
+    expect(ctx.position).toMatchObject({ at: 'queryValue', field: 'a' })
+    expect(ctx.token.quote).toBe('"')
+  })
+
+  it('offers values after a colon', () => {
+    expect(at('{ a: |', 'filter').position).toMatchObject({ at: 'queryValue', field: 'a' })
+  })
+
+  it('is dead inside comments and right after values', () => {
+    expect(at('{ a: 1 // x|', 'filter').position).toEqual({ at: 'none' })
+    expect(at('{ a: 12|', 'filter').position).toEqual({ at: 'none' })
+  })
+
+  it('reports nothing after a complete key', () => {
+    expect(at('{ name |', 'filter').position).toEqual({ at: 'none' })
+  })
+})
+
+describe('analyzeContext: pipeline flow', () => {
+  it('passes the stages before the cursor to the field source', () => {
+    const position = at(
+      '[{ $match: {} }, { $unwind: "$items" }, { $match: { |',
+      'pipeline'
+    ).position
+    expect(position.at).toBe('queryKey')
+    if (position.at !== 'queryKey') return
+    expect(position.source.coll).toBe('users')
+    expect(position.source.stages.map((s) => s.name)).toEqual(['$match', '$unwind'])
+  })
+
+  it('reads foreign fields from the $lookup target', () => {
+    const ctx = at('[{ $lookup: { from: "orders", foreignField: "|', 'pipeline')
+    expect(ctx.position).toMatchObject({ at: 'fieldName', source: { coll: 'orders', stages: [] } })
+    expect(ctx.collections).toEqual(['users', 'orders'])
+  })
+
+  it('reads local fields from the pipeline input', () => {
+    const ctx = at('[{ $unwind: "$a" }, { $lookup: { from: "orders", localField: "|', 'pipeline')
+    expect(ctx.position).toMatchObject({ at: 'fieldName', source: { coll: 'users' } })
+  })
+
+  it('runs a $lookup pipeline over the target with the let variables', () => {
+    const position = at(
+      '[{ $lookup: { from: "orders", let: { uid: "$_id" }, pipeline: [{ $match: { $expr: { $eq: ["$|',
+      'pipeline'
+    ).position
+    expect(position).toMatchObject({
+      at: 'expressionValue',
+      source: { coll: 'orders' },
+      vars: [{ name: 'uid', field: { source: { coll: 'users' }, path: '_id' } }]
+    })
+  })
+
+  it('reads let and from written after the $lookup pipeline', () => {
+    const ctx = at(
+      '[{ $lookup: { pipeline: [{ $match: { $expr: { $eq: ["$a", "$$|"] } } }], from: "orders", let: { uid: "$_id" } } }]',
+      'pipeline'
+    )
+    expect(ctx.position).toMatchObject({
+      at: 'expressionValue',
+      source: { coll: 'orders' },
+      vars: [{ name: 'uid' }]
+    })
+    expect(ctx.collections).toEqual(['users', 'orders'])
+  })
+
+  it('includes the facet prefix and the branch stages', () => {
+    const position = at(
+      '[{ $unwind: "$x" }, { $facet: { a: [ { $limit: 1 }, { $match: { |',
+      'pipeline'
+    ).position
+    expect(position.at).toBe('queryKey')
+    if (position.at !== 'queryKey') return
+    expect(position.source.stages.map((s) => s.name)).toEqual(['$unwind', '$limit'])
+  })
+
+  it('binds $map and $let variables', () => {
+    expect(
+      at('{ $expr: { $map: { input: "$a", as: "item", in: "$|', 'filter').position
+    ).toMatchObject({
+      at: 'expressionValue',
+      vars: [{ name: 'item' }]
+    })
+    expect(at('{ $expr: { $let: { vars: { t: 1 }, in: "$|', 'filter').position).toMatchObject({
+      at: 'expressionValue',
+      vars: [{ name: 't' }]
+    })
+  })
+
+  it('binds variables to the field they iterate or name', () => {
+    const map = at('{ $expr: { $map: { input: "$items", as: "it", in: "$$it.|', 'filter')
+    expect(map.position).toMatchObject({
+      vars: [{ name: 'it', field: { source: { coll: 'users' }, path: 'items' } }]
+    })
+    const filter = at('{ $expr: { $filter: { input: "$items", cond: "$$|', 'filter')
+    expect(filter.position).toMatchObject({ vars: [{ name: 'this', field: { path: 'items' } }] })
+    const reduce = at('{ $expr: { $reduce: { input: "$items", in: "$$|', 'filter')
+    expect(reduce.position).toMatchObject({
+      vars: [{ name: 'value' }, { name: 'this', field: { path: 'items' } }]
+    })
+    const bound = at('{ $expr: { $let: { vars: { home: "$address", n: 1 }, in: "$$|', 'filter')
+    expect(bound.position).toMatchObject({
+      vars: [{ name: 'home', field: { path: 'address' } }, { name: 'n' }]
+    })
+    expect(bound.position.at === 'expressionValue' && bound.position.vars[1]?.field).toBe(undefined)
+  })
+
+  it('lists lookup targets of earlier stages, including nested pipelines', () => {
+    const ctx = at(
+      '[{ $lookup: { from: "orders", as: "o" } }, { $facet: { f: [{ $unionWith: "logs" }] } }, { $match: { |',
+      'pipeline'
+    )
+    expect(ctx.collections).toEqual(['users', 'orders', 'logs'])
+  })
+})
+
+describe('analyzeContext: keys after the cursor', () => {
+  it('counts keys after the cursor as present in a document', () => {
+    expect(at('{\n  "|"\n  "_id": 1, "name": "x"\n}', 'document').position).toMatchObject({
+      at: 'documentKey',
+      present: ['_id', 'name']
+    })
+  })
+
+  it('counts keys after the cursor as present in a filter', () => {
+    expect(at('{ |, name: "x" }', 'filter').position).toMatchObject({
+      at: 'queryKey',
+      present: ['name']
+    })
+  })
+})
+
+describe('analyzeContext: expected types', () => {
+  it.each<[string, EditorKind, Record<string, unknown>]>([
+    [
+      '[{ $group: { _id: null, t: { $sum: "$|',
+      'pipeline',
+      { at: 'expressionValue', prefer: 'number' }
+    ],
+    ['[{ $project: { y: { $year: "$|', 'pipeline', { at: 'expressionValue', prefer: 'date' }],
+    [
+      '[{ $project: { d: { $dateToString: { date: "$|',
+      'pipeline',
+      { at: 'expressionValue', prefer: 'date' }
+    ],
+    ['{ $expr: { |', 'filter', { at: 'expressionKey', prefer: 'bool' }],
+    ['{ $expr: { $and: [{ |', 'filter', { at: 'expressionKey', prefer: 'bool' }],
+    ['{ $expr: { $cond: { if: "$|', 'filter', { at: 'expressionValue', prefer: 'bool' }],
+    [
+      '{ $expr: { $gt: ["$coins", "$|',
+      'filter',
+      { at: 'expressionValue', prefer: { source: { coll: 'users' }, path: 'coins' } }
+    ],
+    [
+      '[{ $lookup: { from: "orders", localField: "uid", foreignField: "|',
+      'pipeline',
+      {
+        at: 'fieldName',
+        source: { coll: 'orders' },
+        prefer: { source: { coll: 'users' }, path: 'uid' }
+      }
+    ]
+  ])('%s (%s)', (marked, kind, expected) => {
+    expect(at(marked, kind).position).toMatchObject(expected)
+  })
+
+  it('expects nothing in particular where any value fits', () => {
+    const position = at('[{ $set: { x: "$|', 'pipeline').position
+    expect(position.at).toBe('expressionValue')
+    expect(position.at === 'expressionValue' && position.prefer).toBeUndefined()
+  })
+})
+
+describe('analyzeContext: object literals and nested pipelines', () => {
+  it('takes keys of a $set object literal from the field it extends', () => {
+    expect(at('[{ $set: { address: { |', 'pipeline').position).toMatchObject({
+      at: 'expressionKey',
+      literalBase: 'address'
+    })
+    expect(at('[{ $set: { address: { geo: { |', 'pipeline').position).toMatchObject({
+      literalBase: 'address.geo'
+    })
+  })
+
+  it('takes compound $group keys from the root fields', () => {
+    expect(at('[{ $group: { _id: { |', 'pipeline').position).toMatchObject({
+      at: 'expressionKey',
+      literalBase: ''
+    })
+    const operator = at('[{ $set: { x: { $add: [{ |', 'pipeline').position
+    expect(operator.at).toBe('expressionKey')
+    expect(operator.at === 'expressionKey' && operator.literalBase).toBeUndefined()
+  })
+
+  it('offers only direct children as $jsonSchema property names', () => {
+    expect(at('{ $jsonSchema: { properties: { |', 'filter').position).toMatchObject({
+      at: 'queryKey',
+      childrenOnly: true
+    })
+  })
+
+  it('marks $facet branches and $lookup / $unionWith pipelines', () => {
+    expect(at('[{ $facet: { a: [{ |', 'pipeline').position).toMatchObject({
+      at: 'stageKey',
+      nested: 'facet'
+    })
+    expect(at('[{ $lookup: { from: "orders", pipeline: [|', 'pipeline').position).toMatchObject({
+      at: 'stageElement',
+      nested: 'sub'
+    })
+    expect(
+      at('[{ $unionWith: { coll: "orders", pipeline: [{ |', 'pipeline').position
+    ).toMatchObject({ at: 'stageKey', nested: 'sub' })
+    const main = at('[{ |', 'pipeline').position
+    expect(main.at).toBe('stageKey')
+    expect(main.at === 'stageKey' && main.nested).toBeUndefined()
+  })
+})
+
+describe('analyzeContext: shell source', () => {
+  it('uses the command collection as the field source', () => {
+    const ctx = at('db.orders.find({ |', 'shell')
+    expect(ctx.position).toMatchObject({ at: 'queryKey', source: { coll: 'orders' } })
+    expect(ctx.collections).toEqual(['orders'])
+  })
+
+  it('resolves getCollection and bracket accessors', () => {
+    expect(at('db.getCollection("a-b").find({ |', 'shell').position).toMatchObject({
+      source: { coll: 'a-b' }
+    })
+    expect(at('db["a b"].find({ |', 'shell').position).toMatchObject({ source: { coll: 'a b' } })
+  })
+
+  it('keeps the tab collection when no command names one', () => {
+    expect(at('|', 'shell').collections).toEqual(['users'])
+  })
+})
+
+describe('analyzeContext: shell writes', () => {
+  it.each<[string, Record<string, unknown>]>([
+    ['db.users.insertOne(|', { at: 'rootValue', expect: 'object' }],
+    ['db.users.insertOne({ |', { at: 'documentKey', coll: 'users', path: '', present: [] }],
+    ['db.users.insertOne({ address: { |', { at: 'documentKey', path: 'address' }],
+    ['db.users.insertOne({ tags: [ |', { at: 'documentValue', path: 'tags', element: true }],
+    ['db.users.insertOne({ _id: ObjectId("|', { at: 'ctorArg', field: '_id', ctor: 'ObjectId' }],
+    ['db.users.insertOne({}, { |', { at: 'stageArgKey', stage: 'insertOne.options' }],
+    ['db.users.insertMany(|', { at: 'rootValue', expect: 'array' }],
+    ['db.users.insertMany([|', { at: 'rootValue', expect: 'object' }],
+    ['db.users.insertMany([{ a: 1 }, { |', { at: 'documentKey', path: '', present: [] }],
+    ['db.users.insertMany([], { ordered: |', { at: 'literal', values: ['true', 'false'] }],
+    ['db.users.updateOne({ |', { at: 'queryKey', topLevel: true }],
+    ['db.users.updateOne({}, |', { at: 'rootValue', expect: 'object' }],
+    ['db.users.updateOne({}, { |', { at: 'updateKey', present: [] }],
+    ['db.users.updateOne({}, { $set: { a: 1 }, | })', { at: 'updateKey', present: ['$set'] }],
+    ['db.users.updateOne({}, { $set: { |', { at: 'updateFieldKey', op: '$set', present: [] }],
+    [
+      'db.users.updateOne({}, { $set: { name: |',
+      { at: 'documentValue', path: 'name', element: false }
+    ],
+    ['db.users.updateOne({}, { $set: { address: { |', { at: 'documentKey', path: 'address' }],
+    ['db.users.updateOne({}, { $setOnInsert: { at: |', { at: 'documentValue', path: 'at' }],
+    ['db.users.updateOne({}, { $min: { age: |', { at: 'documentValue', path: 'age' }],
+    ['db.users.updateOne({}, { $inc: { age: |', { at: 'updateValue', op: '$inc', field: 'age' }],
+    ['db.users.updateOne({}, { $mul: { age: |', { at: 'updateValue', op: '$mul', field: 'age' }],
+    ['db.users.updateOne({}, { $unset: { age: |', { at: 'updateValue', op: '$unset' }],
+    ['db.users.updateOne({}, { $pop: { tags: |', { at: 'updateValue', op: '$pop', field: 'tags' }],
+    ['db.users.updateOne({}, { $currentDate: { at: |', { at: 'updateValue', op: '$currentDate' }],
+    [
+      'db.users.updateOne({}, { $currentDate: { at: { |',
+      { at: 'stageArgKey', stage: '$currentDate.field' }
+    ],
+    [
+      'db.users.updateOne({}, { $currentDate: { at: { $type: |',
+      { at: 'literal', values: ['"date"', '"timestamp"'] }
+    ],
+    ['db.users.updateOne({}, { $bit: { flags: |', { at: 'updateValue', op: '$bit' }],
+    ['db.users.updateOne({}, { $bit: { flags: { |', { at: 'stageArgKey', stage: '$bit.field' }],
+    ['db.users.updateOne({}, { $rename: { name: "|', { at: 'fieldName', renaming: 'name' }],
+    [
+      'db.users.updateOne({}, { $push: { tags: |',
+      { at: 'documentValue', path: 'tags', element: true, modifiersOf: '$push' }
+    ],
+    [
+      'db.users.updateOne({}, { $push: { tags: { |',
+      { at: 'documentKey', path: 'tags', modifiersOf: '$push' }
+    ],
+    [
+      'db.users.updateOne({}, { $addToSet: { tags: { |',
+      { at: 'documentKey', path: 'tags', modifiersOf: '$addToSet' }
+    ],
+    [
+      'db.users.updateOne({}, { $push: { tags: { $each: |',
+      { at: 'documentValue', path: 'tags', element: false }
+    ],
+    [
+      'db.users.updateOne({}, { $push: { tags: { $each: [|',
+      { at: 'documentValue', path: 'tags', element: true }
+    ],
+    [
+      'db.users.updateOne({}, { $push: { items: { $sort: |',
+      { at: 'literal', values: ['1', '-1'], preferred: '1' }
+    ],
+    ['db.users.updateOne({}, { $push: { items: { $sort: { |', { at: 'documentKey', path: 'items' }],
+    ['db.users.updateOne({}, { $push: { items: { $slice: |', { at: 'none' }],
+    [
+      'db.users.updateOne({}, { $push: { items: { sku: |',
+      { at: 'documentValue', path: 'items.sku' }
+    ],
+    [
+      'db.users.updateOne({}, { $pull: { tags: |',
+      { at: 'queryValue', field: 'tags', operator: null }
+    ],
+    ['db.users.updateOne({}, { $pull: { items: { |', { at: 'elemMatchKey', field: 'items' }],
+    [
+      'db.users.updateOne({}, { $pull: { items: { qty: { $g|',
+      { at: 'operatorKey', field: 'items.qty' }
+    ],
+    [
+      'db.users.updateOne({}, { $pullAll: { tags: [|',
+      { at: 'documentValue', path: 'tags', element: true }
+    ],
+    ['db.users.updateOne({}, { name: { |', { at: 'none' }],
+    ['db.users.updateOne({}, { $where: { |', { at: 'none' }],
+    ['db.users.updateOne({}, [|', { at: 'stageElement', stageIndex: 0, nested: 'update' }],
+    [
+      'db.users.updateOne({}, [{ $set: { a: 1 } }, { |',
+      { at: 'stageKey', stageIndex: 1, nested: 'update' }
+    ],
+    ['db.users.updateMany({}, [{ $set: { a: "$|', { at: 'expressionValue' }],
+    ['db.users.updateOne({}, {}, { |', { at: 'stageArgKey', stage: 'updateOne.options' }],
+    ['db.users.updateOne({}, {}, { upsert: |', { at: 'literal', values: ['true', 'false'] }],
+    ['db.users.replaceOne({}, { |', { at: 'documentKey', path: '' }],
+    ['db.users.replaceOne({}, {}, { |', { at: 'stageArgKey', stage: 'replaceOne.options' }],
+    ['db.users.deleteMany({ |', { at: 'queryKey' }],
+    ['db.users.deleteOne({}, { |', { at: 'stageArgKey', stage: 'deleteOne.options' }],
+    ['db.users.findOneAndDelete({}, { sort: { |', { at: 'sortKey' }],
+    ['db.users.findOneAndReplace({}, {}, { projection: { |', { at: 'projectionKey' }],
+    [
+      'db.users.findOneAndUpdate({}, {}, { returnDocument: |',
+      { at: 'literal', values: ['"after"', '"before"'] }
+    ],
+    ['db.users.bulkWrite(|', { at: 'rootValue', expect: 'array' }],
+    ['db.users.bulkWrite([|', { at: 'bulkOperationElement' }],
+    ['db.users.bulkWrite([{ |', { at: 'bulkOperationKey' }],
+    ['db.users.bulkWrite([{ | deleteOne: {} }])', { at: 'none' }],
+    ['db.users.bulkWrite([{ updateOne: { |', { at: 'stageArgKey', stage: 'bulkWrite.updateOne' }],
+    ['db.users.bulkWrite([{ updateOne: { filter: { |', { at: 'queryKey' }],
+    ['db.users.bulkWrite([{ updateMany: { update: { |', { at: 'updateKey' }],
+    ['db.users.bulkWrite([{ insertOne: { document: { |', { at: 'documentKey', path: '' }],
+    ['db.users.bulkWrite([{ replaceOne: { replacement: { a|', { at: 'documentKey', path: '' }],
+    ['db.users.bulkWrite([{ foo: { |', { at: 'none' }],
+    ['db.users.bulkWrite([], { |', { at: 'stageArgKey', stage: 'bulkWrite.options' }]
+  ])('%s', (marked, expected) => {
+    expect(at(marked, 'shell').position).toMatchObject(expected)
+  })
+
+  it('reads documents and updates against the command collection', () => {
+    const ctx = at('db.orders.insertOne({ |', 'shell')
+    expect(ctx.position).toMatchObject({ at: 'documentKey', coll: 'orders' })
+    expect(ctx.collections).toEqual(['orders'])
+    expect(at('db.orders.updateOne({}, { $inc: { |', 'shell').position).toMatchObject({
+      at: 'updateFieldKey',
+      source: { coll: 'orders', stages: [] }
+    })
+  })
+
+  it('counts fields other update operators change as present', () => {
+    const position = at(
+      'db.users.updateOne({}, { $set: { a: 1 }, $inc: { b: 1, | }, $unset: { c: "" } })',
+      'shell'
+    ).position
+    expect(position).toMatchObject({ at: 'updateFieldKey', op: '$inc' })
+    expect(position.at === 'updateFieldKey' && [...position.present].sort()).toEqual([
+      'a',
+      'b',
+      'c'
+    ])
+  })
+
+  it('resolves positional update paths to the array they address', () => {
+    expect(
+      at('db.users.updateOne({}, { $set: { "items.$[it].qty": |', 'shell').position
+    ).toMatchObject({ at: 'documentValue', path: 'items.qty', element: false })
+    expect(at('db.users.updateOne({}, { $set: { "tags.$": |', 'shell').position).toMatchObject({
+      at: 'documentValue',
+      path: 'tags',
+      element: true
+    })
+    expect(
+      at('db.users.updateOne({}, { $inc: { "items.$[].qty": |', 'shell').position
+    ).toMatchObject({
+      at: 'updateValue',
+      field: 'items.qty'
+    })
+  })
+
+  it('offers the $[identifier]s of the update as arrayFilters keys', () => {
+    const update =
+      '{ $set: { "items.$[it].qty": 1, "grades.$[g]": 0 }, $inc: { "items.$[it].n": 1 } }'
+    expect(
+      at(`db.users.updateMany({}, ${update}, { arrayFilters: [{ |`, 'shell').position
+    ).toMatchObject({
+      at: 'arrayFilterKey',
+      identifiers: [
+        { name: 'it', path: 'items' },
+        { name: 'g', path: 'grades' }
+      ],
+      present: []
+    })
+    expect(
+      at(`db.users.updateMany({}, ${update}, { arrayFilters: [{ it: 1 }, { |`, 'shell').position
+    ).toMatchObject({ at: 'arrayFilterKey', identifiers: [{ name: 'g', path: 'grades' }] })
+    expect(
+      at(`db.users.updateMany({}, ${update}, { arrayFilters: [{ "it.qty": 1, | }] })`, 'shell')
+        .position
+    ).toMatchObject({ at: 'arrayFilterKey', identifiers: [{ name: 'it', path: 'items' }] })
+  })
+
+  it('reads arrayFilters conditions as queries on the identified array elements', () => {
+    const update = '{ $set: { "items.$[it].qty": 1 } }'
+    expect(
+      at(`db.users.updateOne({}, ${update}, { arrayFilters: [{ "it.qty": |`, 'shell').position
+    ).toMatchObject({ at: 'queryValue', field: 'items.qty' })
+    expect(
+      at(`db.users.updateOne({}, ${update}, { arrayFilters: [{ it: { $|`, 'shell').position
+    ).toMatchObject({ at: 'operatorKey', field: 'items' })
+    expect(
+      at(`db.users.updateOne({}, ${update}, { arrayFilters: [{ other: |`, 'shell').position
+    ).toEqual({ at: 'none' })
+    expect(
+      at(
+        'db.users.bulkWrite([{ updateMany: { arrayFilters: [{ | }], filter: {}, update: { $unset: { "a.$[x].b": "" } } } }])',
+        'shell'
+      ).position
+    ).toMatchObject({ at: 'arrayFilterKey', identifiers: [{ name: 'x', path: 'a' }] })
+  })
+
+  it('lets a shell aggregate end with a write stage', () => {
+    expect(at('db.users.aggregate([{ $match: {} }, { |', 'shell').position).toMatchObject({
+      at: 'stageKey',
+      stageIndex: 1,
+      finalWrite: true
+    })
+    expect(at('db.users.aggregate([|', 'shell').position).toMatchObject({
+      at: 'stageElement',
+      finalWrite: true
+    })
+    expect(at('db.users.aggregate([{ | }, { $match: {} }])', 'shell').position).toMatchObject({
+      at: 'stageKey',
+      finalWrite: false
+    })
+    const sub = at(
+      'db.users.aggregate([{ $lookup: { from: "orders", pipeline: [{ |',
+      'shell'
+    ).position
+    expect(sub).toMatchObject({ at: 'stageKey', nested: 'sub' })
+    expect(sub.at === 'stageKey' && sub.finalWrite).toBeFalsy()
+    const editor = at('[{ $match: {} }, { |', 'pipeline').position
+    expect(editor.at === 'stageKey' && editor.finalWrite).toBeFalsy()
+  })
+})
+
+describe('analyzeContext: key quoting', () => {
+  it('uses double quotes when the text has only quoted keys', () => {
+    expect(at('{ "a": 1, | }', 'filter').keyQuote).toBe('"')
+  })
+
+  it('uses shell style when any key is unquoted or there are none', () => {
+    expect(at('{ "a": { $gt: 1 }, | }', 'filter').keyQuote).toBeNull()
+    expect(at('{ | }', 'filter').keyQuote).toBeNull()
+  })
+})
diff --git a/src/renderer/src/lib/completion/context.ts b/src/renderer/src/lib/completion/context.ts
new file mode 100644
index 0000000..951af32
--- /dev/null
+++ b/src/renderer/src/lib/completion/context.ts
@@ -0,0 +1,1292 @@
+/**
+ * Classifies the cursor of a query, pipeline, shell or document editor into a Mongo-semantic
+ * position by walking the scanner's open frames with a grammar per container.
+ */
+import { BULK_WRITE_OPERATIONS } from '@shared/writeOps'
+import {
+  ACCUMULATOR_DEFS,
+  ARG_SPECS,
+  EXPRESSIONS,
+  FIELD_OPERATORS,
+  POSITIONAL_SEGMENT,
+  SHELL_CURSOR_ARGS,
+  SHELL_METHOD_ARGS,
+  UPDATE_OPERATORS,
+  bulkOperationOwner,
+  optionsOwner,
+  withoutPositional,
+  type ArgKind,
+  type ArrayModifierOwner,
+  type ShellArg,
+  type TypeClass
+} from './catalog'
+import {
+  fieldRefPath,
+  foreignCollection,
+  join,
+  projectionMode,
+  type ProjectionMode
+} from './pipelineFlow'
+import {
+  entryValue,
+  scan,
+  stringValue,
+  toStages,
+  type ArrayNode,
+  type AstNode,
+  type Frame,
+  type ObjectNode,
+  type StageAst,
+  type TokenSpan
+} from './scanner'
+
+export type EditorKind = 'filter' | 'projection' | 'sort' | 'pipeline' | 'shell' | 'document'
+
+/** Fields of `coll` as they look after `stages` ran. */
+export type FieldSource = { coll: string; stages: readonly StageAst[] }
+
+/** A field of a field source. */
+export type FieldRef = { source: FieldSource; path: string }
+
+/** Field type a value slot ranks first: a type class, or the type of a referenced field. */
+export type Prefer = TypeClass | FieldRef
+
+/** An aggregation variable; `field` is the field it holds (the elements, for an array). */
+export type Variable = { name: string; field?: FieldRef }
+
+/** A pipeline inside a `$facet` branch, inside a `$lookup` / `$unionWith` stage, or an update pipeline. */
+export type Nesting = 'facet' | 'sub' | 'update'
+
+/** A `$[name]` placeholder of an update and the array path it stands for. */
+export type ArrayIdentifier = { name: string; path: string }
+
+export type Position =
+  | { at: 'none' }
+  /** A value slot that takes an object or array, e.g. an empty filter. */
+  | { at: 'rootValue'; expect: 'object' | 'array' }
+  /** `base` is the `$elemMatch` path the keys are relative to; `childrenOnly` offers only its direct children. */
+  | {
+      at: 'queryKey'
+      source: FieldSource
+      base: string
+      present: string[]
+      topLevel: boolean
+      childrenOnly?: boolean
+    }
+  | { at: 'operatorKey'; source: FieldSource; field: string; present: string[] }
+  | { at: 'elemMatchKey'; source: FieldSource; field: string; present: string[] }
+  | {
+      at: 'queryValue'
+      source: FieldSource
+      field: string
+      operator: string | null
+      inArray: boolean
+      /** Other elements of the enclosing array as normalized literals. */
+      siblings: string[]
+    }
+  | { at: 'ctorArg'; source: FieldSource; field: string | null; ctor: string }
+  | { at: 'typeAlias'; source: FieldSource; field: string }
+  | { at: 'literal'; values: readonly string[]; preferred?: string }
+  | { at: 'textKey' | 'jsonSchemaKey' | 'geoKey'; present: string[] }
+  | { at: 'projectionKey'; source: FieldSource; present: string[] }
+  | { at: 'projectionValue'; source: FieldSource; field: string; mode: ProjectionMode }
+  /** Keys of a projection field's object: `$slice`, `$elemMatch`, `$meta`, subfields, expressions. */
+  | { at: 'projectionOperatorKey'; source: FieldSource; field: string; present: string[] }
+  | { at: 'sortKey'; source: FieldSource; present: string[] }
+  | { at: 'sortValue'; source: FieldSource; field: string }
+  /** `finalWrite`: `$out` / `$merge` may end the pipeline here. */
+  | { at: 'stageElement'; stageIndex: number; nested?: Nesting; finalWrite?: boolean }
+  | {
+      at: 'stageKey'
+      stageIndex: number
+      present: string[]
+      nested?: Nesting
+      finalWrite?: boolean
+    }
+  /** Named arguments of a stage or nested stage object (`ARG_SPECS` owner); `present` includes those it cannot take. */
+  | { at: 'stageArgKey'; stage: string; present: string[] }
+  | { at: 'newFieldKey'; source: FieldSource; present: string[]; group: boolean }
+  | { at: 'accumulatorKey'; window: boolean; present: string[] }
+  /** `literalBase`: an object literal whose keys name subfields of that path ('' = root fields). */
+  | {
+      at: 'expressionKey'
+      source: FieldSource
+      present: string[]
+      prefer?: Prefer
+      literalBase?: string
+    }
+  | { at: 'expressionValue'; source: FieldSource; vars: readonly Variable[]; prefer?: Prefer }
+  | { at: 'operatorArgKey'; operator: string; present: string[] }
+  /** `renaming`: the field a `$rename` moves; the names are its targets. */
+  | { at: 'fieldName'; source: FieldSource; prefer?: Prefer; renaming?: string }
+  | { at: 'collectionName' }
+  | { at: 'shellRoot' }
+  | { at: 'shellCollection' }
+  | { at: 'shellMethod'; coll: string }
+  | { at: 'shellCursorMethod'; head: string; used: string[] }
+  /** `modifiersOf`: the object is a `$push` / `$addToSet` value, which may hold that operator's modifiers. */
+  | {
+      at: 'documentKey'
+      coll: string
+      path: string
+      present: string[]
+      modifiersOf?: ArrayModifierOwner
+    }
+  /** `element`: the value is an element of the array at `path`. */
+  | {
+      at: 'documentValue'
+      coll: string
+      path: string
+      element: boolean
+      modifiersOf?: ArrayModifierOwner
+    }
+  | { at: 'updateKey'; present: string[] }
+  /** Field paths an update operator changes; `present` includes those other operators change. */
+  | { at: 'updateFieldKey'; source: FieldSource; op: string; present: string[] }
+  /** Value of `$inc`, `$mul`, `$unset`, `$pop`, `$currentDate` or `$bit` for `field`. */
+  | { at: 'updateValue'; source: FieldSource; op: string; field: string }
+  | {
+      at: 'arrayFilterKey'
+      source: FieldSource
+      identifiers: readonly ArrayIdentifier[]
+      present: string[]
+    }
+  | { at: 'bulkOperationElement' }
+  | { at: 'bulkOperationKey' }
+
+export type CompletionContext = {
+  kind: EditorKind
+  position: Position
+  token: TokenSpan
+  /** Schemas the suggestions may need: the editor's/command's collection first, then $lookup/$graphLookup/$unionWith targets. */
+  collections: string[]
+  /** '"' when the text uses quoted keys and no unquoted ones; null means shell-style keys. */
+  keyQuote: '"' | null
+}
+
+/**
+ * Classifies the cursor position of `text` at `offset` for an editor of `kind` bound to collection `coll`.
+ * @returns the position plus the token span and the collections whose schemas apply
+ */
+export function analyzeContext(
+  text: string,
+  offset: number,
+  kind: EditorKind,
+  coll: string
+): CompletionContext {
+  const root = kind === 'shell' ? 'shell' : kind === 'document' ? 'documents' : 'value'
+  const result = scan(text, offset, root)
+  const walker = new Walker(result.frames, coll)
+  const position = result.dead ? NONE : walker.position(kind)
+  return {
+    kind,
+    position,
+    token: result.token,
+    collections: walker.collections(),
+    keyQuote: result.quotedKeys && !result.unquotedKeys ? '"' : null
+  }
+}
+
+/** Grammar of the value a frame (or the cursor's slot) holds. */
+type Grammar =
+  | { g: 'opaque' }
+  | { g: 'query'; source: FieldSource; base: string; topLevel: boolean; vars: readonly Variable[] }
+  | { g: 'queryList'; source: FieldSource; base: string; vars: readonly Variable[] }
+  /** Value of a query field: a literal, an operator object, an array or a constructor. */
+  | { g: 'field'; source: FieldSource; field: string }
+  | {
+      g: 'opValue'
+      source: FieldSource
+      field: string
+      operator: string | null
+      inArray: boolean
+      siblings: string[]
+    }
+  | { g: 'elemMatch'; source: FieldSource; field: string }
+  | { g: 'literal'; values: readonly string[]; preferred?: string }
+  | { g: 'typeAlias'; source: FieldSource; field: string }
+  | { g: 'text' }
+  | { g: 'geo' }
+  | { g: 'jsonSchema'; source: FieldSource; base: string }
+  | { g: 'jsonProps'; source: FieldSource; base: string }
+  | { g: 'projection'; source: FieldSource }
+  | { g: 'projField'; source: FieldSource; field: string; mode: ProjectionMode }
+  | { g: 'sort'; source: FieldSource }
+  | { g: 'sortField'; source: FieldSource; field: string }
+  /** `writes`: the pipeline may end with `$out` / `$merge`. */
+  | {
+      g: 'pipeline'
+      source: FieldSource
+      vars: readonly Variable[]
+      nested?: Nesting
+      writes?: boolean
+    }
+  | {
+      g: 'stage'
+      source: FieldSource
+      index: number
+      vars: readonly Variable[]
+      nested?: Nesting
+      finalWrite?: boolean
+    }
+  /** `compared`: the arguments of a comparison, each preferring the type of a field another one references. */
+  | {
+      g: 'expression'
+      source: FieldSource
+      vars: readonly Variable[]
+      prefer?: Prefer
+      compared?: boolean
+      literalBase?: string
+    }
+  | { g: 'opArgs'; operator: string; source: FieldSource; vars: readonly Variable[] }
+  /** Named arguments of `ARG_SPECS[owner]`; `scalar` is the grammar of a non-object value, `update` the update `arrayFilters` refer to. */
+  | {
+      g: 'args'
+      owner: string
+      source: FieldSource
+      vars: readonly Variable[]
+      scalar?: Grammar
+      update?: AstNode
+    }
+  /** `$addFields` / `$set` body, or a `$group` body when `group`. */
+  | { g: 'newFields'; source: FieldSource; vars: readonly Variable[]; group: boolean }
+  /** Named outputs whose values are accumulator objects. */
+  | { g: 'outputs'; source: FieldSource; vars: readonly Variable[]; window: boolean }
+  | { g: 'fillOutput'; source: FieldSource; vars: readonly Variable[] }
+  | { g: 'accumulator'; source: FieldSource; vars: readonly Variable[]; window: boolean }
+  | { g: 'facet'; source: FieldSource; vars: readonly Variable[] }
+  | { g: 'letVars'; source: FieldSource; vars: readonly Variable[] }
+  | { g: 'fieldName'; source: FieldSource; prefer?: Prefer; renaming?: string }
+  | { g: 'collection' }
+  /** An object stored at `path` of a document ('' = the document itself). */
+  | { g: 'document'; coll: string; path: string }
+  | { g: 'docValue'; coll: string; path: string; element: boolean }
+  /** An array whose elements all have grammar `of`. */
+  | { g: 'list'; of: Grammar }
+  | { g: 'update'; source: FieldSource }
+  /** The object under update operator `op`; `taken` are the fields other operators change. */
+  | { g: 'updateFields'; source: FieldSource; op: string; taken: readonly string[] }
+  | { g: 'updateValue'; source: FieldSource; op: string; field: string }
+  /** Value of a `$push` / `$addToSet` field: an element, or an object of modifiers. */
+  | { g: 'arrayPush'; coll: string; path: string; op: ArrayModifierOwner }
+  /** `$push` `$sort` by direction or by element fields. */
+  | { g: 'elementSort'; coll: string; path: string }
+  /** Value of a `$pull` field: an element or a condition on the elements. */
+  | { g: 'pull'; source: FieldSource; field: string }
+  | { g: 'bulkOperation'; source: FieldSource }
+  | { g: 'arrayFilters'; source: FieldSource; identifiers: readonly ArrayIdentifier[] }
+  /** One `arrayFilters` condition; `used`: identifiers the other conditions filter. */
+  | {
+      g: 'arrayFilter'
+      source: FieldSource
+      identifiers: readonly ArrayIdentifier[]
+      used: readonly string[]
+    }
+
+const NONE: Position = { at: 'none' }
+const ROOT_OBJECT: Position = { at: 'rootValue', expect: 'object' }
+const ROOT_ARRAY: Position = { at: 'rootValue', expect: 'array' }
+const OPAQUE: Grammar = { g: 'opaque' }
+const COLLECTION: Grammar = { g: 'collection' }
+const BOOL: Grammar = { g: 'literal', values: ['true', 'false'] }
+const SORT_DIRECTION: Grammar = { g: 'literal', values: ['1', '-1'], preferred: '1' }
+const LOGICAL = new Set(['$and', '$or', '$nor'])
+const GEO_OPERATORS = new Set(
+  FIELD_OPERATORS.filter((op) => op.fits === 'geo').map((op) => op.name)
+)
+const UPDATE_OPERATOR_NAMES = new Set(UPDATE_OPERATORS.map((op) => op.name))
+const BULK_OPERATIONS: ReadonlySet<string> = new Set(BULK_WRITE_OPERATIONS)
+const ARRAY_IDENTIFIER = /^\$\[([a-z][A-Za-z0-9]*)\]$/
+
+class Walker {
+  private readonly sources: FieldSource[] = []
+  private commandColl: string | null = null
+
+  constructor(
+    private readonly frames: readonly Frame[],
+    private readonly coll: string
+  ) {}
+
+  position(kind: EditorKind): Position {
+    switch (kind) {
+      case 'filter':
+        return this.resolve(
+          { g: 'query', source: this.source(this.coll), base: '', topLevel: true, vars: [] },
+          0
+        )
+      case 'projection':
+        return this.resolve({ g: 'projection', source: this.source(this.coll) }, 0)
+      case 'sort':
+        return this.resolve({ g: 'sort', source: this.source(this.coll) }, 0)
+      case 'pipeline':
+        return this.resolve({ g: 'pipeline', source: this.source(this.coll), vars: [] }, 0)
+      case 'document':
+        return this.resolve({ g: 'document', coll: this.coll, path: '' }, 0)
+      case 'shell':
+        return this.shell()
+    }
+  }
+
+  collections(): string[] {
+    const out: string[] = []
+    const add = (name: string | null): void => {
+      if (name && !out.includes(name)) out.push(name)
+    }
+    add(this.commandColl ?? this.coll)
+    for (const source of this.sources) {
+      add(source.coll)
+      collectTargets(source.stages, add)
+    }
+    return out
+  }
+
+  private source(coll: string, stages: readonly StageAst[] = []): FieldSource {
+    const source = { coll, stages }
+    this.sources.push(source)
+    return source
+  }
+
+  private resolve(grammar: Grammar, depth: number): Position {
+    const frame = this.frames[depth]
+    if (!frame) return this.slot(grammar)
+    switch (frame.f) {
+      case 'object':
+        if (frame.slot === 'key') return this.key(grammar, frame.node)
+        if (frame.slot === 'value' && frame.key !== null) {
+          return this.resolve(this.child(grammar, frame.key, frame.node), depth + 1)
+        }
+        return NONE
+      case 'array':
+        if (frame.slot !== 'element') return NONE
+        return this.resolve(this.element(grammar, frame.node, frame.index, frame.more), depth + 1)
+      case 'call':
+        if (frame.slot !== 'arg' || frame.argIndex !== 0 || depth !== this.frames.length - 1) {
+          return NONE
+        }
+        return this.ctorArg(grammar, frame.callee)
+      case 'chain':
+        return NONE
+    }
+  }
+
+  /** The cursor sits directly in a value slot of `grammar`, possibly on a partial word or string. */
+  private slot(grammar: Grammar): Position {
+    switch (grammar.g) {
+      case 'query':
+      case 'elemMatch':
+      case 'text':
+      case 'geo':
+      case 'jsonSchema':
+      case 'jsonProps':
+      case 'projection':
+      case 'sort':
+      case 'opArgs':
+      case 'newFields':
+      case 'outputs':
+      case 'fillOutput':
+      case 'facet':
+      case 'letVars':
+      case 'document':
+      case 'update':
+      case 'updateFields':
+      case 'arrayFilter':
+        return ROOT_OBJECT
+      case 'queryList':
+      case 'pipeline':
+      case 'list':
+      case 'arrayFilters':
+        return ROOT_ARRAY
+      case 'field':
+      case 'pull':
+        return {
+          at: 'queryValue',
+          source: grammar.source,
+          field: grammar.field,
+          operator: null,
+          inArray: false,
+          siblings: []
+        }
+      case 'opValue':
+        return {
+          at: 'queryValue',
+          source: grammar.source,
+          field: grammar.field,
+          operator: grammar.operator,
+          inArray: grammar.inArray,
+          siblings: grammar.siblings
+        }
+      case 'literal':
+        return { at: 'literal', values: grammar.values, preferred: grammar.preferred }
+      case 'typeAlias':
+        return { at: 'typeAlias', source: grammar.source, field: grammar.field }
+      case 'projField':
+        return {
+          at: 'projectionValue',
+          source: grammar.source,
+          field: grammar.field,
+          mode: grammar.mode
+        }
+      case 'sortField':
+        return { at: 'sortValue', source: grammar.source, field: grammar.field }
+      case 'stage':
+        return {
+          at: 'stageElement',
+          stageIndex: grammar.index,
+          nested: grammar.nested,
+          finalWrite: grammar.finalWrite
+        }
+      case 'expression':
+        return {
+          at: 'expressionValue',
+          source: grammar.source,
+          vars: grammar.vars,
+          prefer: grammar.prefer
+        }
+      case 'args':
+        return grammar.scalar ? this.slot(grammar.scalar) : ROOT_OBJECT
+      case 'fieldName':
+        return {
+          at: 'fieldName',
+          source: grammar.source,
+          prefer: grammar.prefer,
+          renaming: grammar.renaming
+        }
+      case 'collection':
+        return { at: 'collectionName' }
+      case 'docValue':
+        return {
+          at: 'documentValue',
+          coll: grammar.coll,
+          path: grammar.path,
+          element: grammar.element
+        }
+      case 'arrayPush':
+        return {
+          at: 'documentValue',
+          coll: grammar.coll,
+          path: grammar.path,
+          element: true,
+          modifiersOf: grammar.op
+        }
+      case 'updateValue':
+        return { at: 'updateValue', source: grammar.source, op: grammar.op, field: grammar.field }
+      case 'elementSort':
+        return this.slot(SORT_DIRECTION)
+      case 'bulkOperation':
+        return { at: 'bulkOperationElement' }
+      case 'accumulator':
+      case 'opaque':
+        return NONE
+    }
+  }
+
+  /** The cursor sits in the key slot of an object whose grammar is `grammar`. */
+  private key(grammar: Grammar, node: ObjectNode): Position {
+    const present = node.entries.map((entry) => entry.key)
+    switch (grammar.g) {
+      case 'query':
+        return {
+          at: 'queryKey',
+          source: grammar.source,
+          base: grammar.base,
+          present,
+          topLevel: grammar.topLevel
+        }
+      case 'jsonProps':
+        // Property names are literal keys of one level, never dotted paths.
+        return {
+          at: 'queryKey',
+          source: grammar.source,
+          base: grammar.base,
+          present,
+          topLevel: false,
+          childrenOnly: true
+        }
+      case 'field':
+        return { at: 'operatorKey', source: grammar.source, field: grammar.field, present }
+      case 'elemMatch':
+      case 'pull':
+        return { at: 'elemMatchKey', source: grammar.source, field: grammar.field, present }
+      case 'text':
+        return { at: 'textKey', present }
+      case 'geo':
+        return { at: 'geoKey', present }
+      case 'jsonSchema':
+        return { at: 'jsonSchemaKey', present }
+      case 'projection':
+        return { at: 'projectionKey', source: grammar.source, present }
+      case 'projField':
+        return {
+          at: 'projectionOperatorKey',
+          source: grammar.source,
+          field: grammar.field,
+          present
+        }
+      case 'sort':
+        return { at: 'sortKey', source: grammar.source, present }
+      case 'stage':
+        return {
+          at: 'stageKey',
+          stageIndex: grammar.index,
+          present,
+          nested: grammar.nested,
+          finalWrite: grammar.finalWrite
+        }
+      case 'expression':
+        return {
+          at: 'expressionKey',
+          source: grammar.source,
+          present,
+          prefer: grammar.prefer,
+          literalBase: grammar.literalBase
+        }
+      case 'opArgs':
+        return { at: 'operatorArgKey', operator: grammar.operator, present }
+      case 'args': {
+        // A pipeline-style update takes no arrayFilters.
+        const pipeline = (grammar.update ?? entryValue(node, 'update'))?.n === 'array'
+        return {
+          at: 'stageArgKey',
+          stage: grammar.owner,
+          present: pipeline ? [...present, 'arrayFilters'] : present
+        }
+      }
+      case 'newFields':
+        return { at: 'newFieldKey', source: grammar.source, present, group: grammar.group }
+      case 'outputs':
+      case 'fillOutput':
+      case 'facet':
+        return { at: 'newFieldKey', source: grammar.source, present, group: false }
+      case 'accumulator':
+        return { at: 'accumulatorKey', window: grammar.window, present }
+      case 'document':
+      case 'docValue':
+      case 'elementSort':
+        return { at: 'documentKey', coll: grammar.coll, path: grammar.path, present }
+      case 'arrayPush':
+        return {
+          at: 'documentKey',
+          coll: grammar.coll,
+          path: grammar.path,
+          present,
+          modifiersOf: grammar.op
+        }
+      case 'update':
+        return { at: 'updateKey', present }
+      case 'updateFields':
+        return {
+          at: 'updateFieldKey',
+          source: grammar.source,
+          op: grammar.op,
+          present: [...present, ...grammar.taken]
+        }
+      case 'bulkOperation':
+        // An operation object names exactly one operation.
+        return present.length === 0 ? { at: 'bulkOperationKey' } : NONE
+      case 'arrayFilter':
+        return {
+          at: 'arrayFilterKey',
+          source: grammar.source,
+          identifiers: filteredIdentifiers(grammar, present),
+          present
+        }
+      default:
+        return NONE
+    }
+  }
+
+  /** Grammar of the value under `key` of `node`, an object whose grammar is `grammar`. */
+  private child(grammar: Grammar, key: string, node: ObjectNode): Grammar {
+    switch (grammar.g) {
+      case 'query':
+        return queryChild(grammar.source, grammar.base, grammar.vars, key)
+      case 'jsonProps':
+        return { g: 'jsonSchema', source: grammar.source, base: join(grammar.base, key) }
+      case 'field':
+        return operatorChild(grammar.source, grammar.field, key)
+      case 'elemMatch':
+      case 'pull':
+        if (LOGICAL.has(key))
+          return { g: 'queryList', source: grammar.source, base: grammar.field, vars: [] }
+        if (key.startsWith('$')) return operatorChild(grammar.source, grammar.field, key)
+        return { g: 'field', source: grammar.source, field: join(grammar.field, key) }
+      case 'text':
+        return key === '$caseSensitive' || key === '$diacriticSensitive' ? BOOL : OPAQUE
+      case 'jsonSchema':
+        return jsonSchemaChild(grammar.source, grammar.base, key)
+      case 'projection':
+        return { g: 'projField', source: grammar.source, field: key, mode: projectionMode(node) }
+      case 'projField':
+        return projectionOperatorChild(grammar, key)
+      case 'sort':
+        return { g: 'sortField', source: grammar.source, field: key }
+      case 'sortField':
+        return key === '$meta'
+          ? { g: 'literal', values: ['"textScore"'], preferred: '"textScore"' }
+          : OPAQUE
+      case 'stage':
+        return stageBody(grammar.source, grammar.vars, key)
+      case 'expression':
+        if (grammar.literalBase !== undefined && !key.startsWith('$')) {
+          return {
+            g: 'expression',
+            source: grammar.source,
+            vars: grammar.vars,
+            literalBase: join(grammar.literalBase, key)
+          }
+        }
+        return operand(grammar.source, grammar.vars, key)
+      case 'opArgs':
+        return operatorArg(grammar.operator, grammar.source, grammar.vars, key, node)
+      case 'args':
+        return this.namedArg(grammar, key, node)
+      case 'newFields':
+        if (grammar.group && key !== '_id') {
+          return { g: 'accumulator', source: grammar.source, vars: grammar.vars, window: false }
+        }
+        // An object literal extends the field in $set, and names a compound key in a $group _id.
+        return {
+          g: 'expression',
+          source: grammar.source,
+          vars: grammar.vars,
+          literalBase: grammar.group ? '' : key
+        }
+      case 'outputs':
+        return {
+          g: 'accumulator',
+          source: grammar.source,
+          vars: grammar.vars,
+          window: grammar.window
+        }
+      case 'fillOutput':
+        return { g: 'args', owner: '$fill.output', source: grammar.source, vars: grammar.vars }
+      case 'accumulator':
+        if (key === 'window' && grammar.window) {
+          return { g: 'args', owner: 'window', source: grammar.source, vars: grammar.vars }
+        }
+        return {
+          g: 'expression',
+          source: grammar.source,
+          vars: grammar.vars,
+          prefer: ACCUMULATOR_DEFS.get(key)?.args
+        }
+      case 'facet':
+        return { g: 'pipeline', source: grammar.source, vars: grammar.vars, nested: 'facet' }
+      case 'letVars':
+        return { g: 'expression', source: grammar.source, vars: grammar.vars }
+      case 'document':
+      case 'docValue':
+        return { g: 'docValue', coll: grammar.coll, path: join(grammar.path, key), element: false }
+      case 'update':
+        return UPDATE_OPERATOR_NAMES.has(key)
+          ? { g: 'updateFields', source: grammar.source, op: key, taken: takenFields(node, key) }
+          : OPAQUE
+      case 'updateFields':
+        return updateFieldValue(grammar.source, grammar.op, key)
+      case 'arrayPush':
+        return arrayPushChild(grammar, key)
+      case 'elementSort':
+        return SORT_DIRECTION
+      case 'bulkOperation':
+        return BULK_OPERATIONS.has(key)
+          ? { g: 'args', owner: bulkOperationOwner(key), source: grammar.source, vars: [] }
+          : OPAQUE
+      case 'arrayFilter': {
+        const [name, ...rest] = key.split('.')
+        const identifier = grammar.identifiers.find((id) => id.name === name)
+        if (!identifier) return OPAQUE
+        return {
+          g: 'field',
+          source: grammar.source,
+          field: rest.length === 0 ? identifier.path : join(identifier.path, rest.join('.'))
+        }
+      }
+      default:
+        return OPAQUE
+    }
+  }
+
+  /** Grammar of the element at `index` of `node`, an array whose grammar is `grammar`; `more`: elements follow it. */
+  private element(grammar: Grammar, node: ArrayNode, index: number, more: boolean): Grammar {
+    switch (grammar.g) {
+      case 'queryList':
+        return {
+          g: 'query',
+          source: grammar.source,
+          base: grammar.base,
+          topLevel: grammar.base === '',
+          vars: grammar.vars
+        }
+      case 'field':
+      case 'pull':
+        return {
+          g: 'opValue',
+          source: grammar.source,
+          field: grammar.field,
+          operator: null,
+          inArray: true,
+          siblings: siblingsOf(node)
+        }
+      case 'opValue':
+        return { ...grammar, inArray: true, siblings: siblingsOf(node) }
+      case 'pipeline': {
+        const stages = [...grammar.source.stages, ...toStages(node.items)]
+        return {
+          g: 'stage',
+          source: this.source(grammar.source.coll, stages),
+          index,
+          vars: grammar.vars,
+          nested: grammar.nested,
+          finalWrite: grammar.writes && !more
+        }
+      }
+      case 'update':
+        // An update given as an array is an update pipeline.
+        return this.element(
+          { g: 'pipeline', source: grammar.source, vars: [], nested: 'update' },
+          node,
+          index,
+          more
+        )
+      case 'list':
+        return grammar.of
+      case 'arrayPush':
+        return { g: 'docValue', coll: grammar.coll, path: grammar.path, element: true }
+      case 'arrayFilters':
+        return {
+          g: 'arrayFilter',
+          source: grammar.source,
+          identifiers: grammar.identifiers,
+          used: node.items.flatMap((item) =>
+            item.n === 'object' ? item.entries.map((entry) => firstSegment(entry.key)) : []
+          )
+        }
+      case 'expression':
+        return {
+          g: 'expression',
+          source: grammar.source,
+          vars: grammar.vars,
+          prefer: grammar.compared ? comparedField(grammar.source, node) : grammar.prefer
+        }
+      case 'typeAlias':
+      case 'jsonSchema':
+      case 'fieldName':
+      case 'document':
+        return grammar
+      case 'docValue':
+        return { ...grammar, element: true }
+      default:
+        return OPAQUE
+    }
+  }
+
+  private ctorArg(grammar: Grammar, ctor: string): Position {
+    switch (grammar.g) {
+      case 'field':
+      case 'opValue':
+      case 'pull':
+        return { at: 'ctorArg', source: grammar.source, field: grammar.field, ctor }
+      case 'expression':
+        return { at: 'ctorArg', source: grammar.source, field: null, ctor }
+      case 'docValue':
+      case 'arrayPush':
+        return { at: 'ctorArg', source: this.source(grammar.coll), field: grammar.path, ctor }
+      default:
+        return NONE
+    }
+  }
+
+  /** Named arguments; `$lookup`-like stages read some from their target collection, `arrayFilters` from the update. */
+  private namedArg(
+    grammar: Extract<Grammar, { g: 'args' }>,
+    key: string,
+    node: ObjectNode
+  ): Grammar {
+    const { owner, source, vars } = grammar
+    const target = (name: string): FieldSource =>
+      this.source(stringValue(entryValue(node, name)) ?? '')
+    switch (owner) {
+      case '$lookup':
+        if (key === 'foreignField') {
+          const local = stringValue(entryValue(node, 'localField'))
+          return {
+            g: 'fieldName',
+            source: target('from'),
+            prefer: local === null ? undefined : { source, path: local }
+          }
+        }
+        // A $lookup pipeline sees only the variables bound in `let`.
+        if (key === 'pipeline')
+          return {
+            g: 'pipeline',
+            source: target('from'),
+            vars: boundVariables(entryValue(node, 'let'), source),
+            nested: 'sub'
+          }
+        break
+      case '$graphLookup':
+        if (key === 'connectFromField' || key === 'connectToField')
+          return { g: 'fieldName', source: target('from') }
+        if (key === 'restrictSearchWithMatch')
+          return { g: 'query', source: target('from'), base: '', topLevel: true, vars: [] }
+        break
+      case '$unionWith':
+        if (key === 'pipeline') {
+          return { g: 'pipeline', source: target('coll'), vars: [], nested: 'sub' }
+        }
+        break
+    }
+    const spec = ARG_SPECS[owner]?.find((arg) => arg.name === key)
+    if (spec?.kind === 'arrayFilters') {
+      const update = grammar.update ?? entryValue(node, 'update')
+      return { g: 'arrayFilters', source, identifiers: arrayIdentifiers(update) }
+    }
+    return spec ? argGrammar(spec.kind, source, vars) : OPAQUE
+  }
+
+  private shell(): Position {
+    const chain = this.frames[0]
+    if (chain?.f !== 'chain') return NONE
+    const call = this.frames[1]
+    if (!call) return this.chainPosition(chain)
+    if (call.f !== 'call' || call.slot !== 'arg' || call.receiver[0] !== 'db') return NONE
+    const coll = call.receiver.slice(1).join('.')
+    if (coll === '') {
+      return call.callee === 'getCollection' && call.argIndex === 0
+        ? this.resolve(COLLECTION, 2)
+        : NONE
+    }
+    this.commandColl = coll
+    const head = chain.calls[0]
+    const table: Readonly<Record<string, readonly ShellArg[]>> = !head
+      ? SHELL_METHOD_ARGS
+      : head.name === 'find'
+        ? SHELL_CURSOR_ARGS
+        : {}
+    const args = table[call.callee] ?? []
+    const arg = args[call.argIndex]
+    if (!arg) return NONE
+    // A write's options read the update for the `$[identifier]`s its arrayFilters filter.
+    const update = call.args[args.indexOf('update')]
+    return this.resolve(shellArg(arg, this.source(coll), call.callee, update), 2)
+  }
+
+  private chainPosition(chain: Extract<Frame, { f: 'chain' }>): Position {
+    if (chain.segments.length === 0) return { at: 'shellRoot' }
+    if (chain.segments[0] !== 'db' || !chain.afterDot) return NONE
+    const coll = chain.segments.slice(1).join('.')
+    if (coll === '') return chain.calls.length === 0 ? { at: 'shellCollection' } : NONE
+    this.commandColl = coll
+    const [head, ...rest] = chain.calls
+    if (!head) return { at: 'shellMethod', coll }
+    return { at: 'shellCursorMethod', head: head.name, used: rest.map((call) => call.name) }
+  }
+}
+
+function queryChild(
+  source: FieldSource,
+  base: string,
+  vars: readonly Variable[],
+  key: string
+): Grammar {
+  if (LOGICAL.has(key)) return { g: 'queryList', source, base, vars }
+  if (key === '$expr') return { g: 'expression', source, vars, prefer: 'bool' }
+  if (key === '$text') return { g: 'text' }
+  if (key === '$jsonSchema') return { g: 'jsonSchema', source, base: '' }
+  if (key.startsWith('$')) return OPAQUE
+  return { g: 'field', source, field: join(base, key) }
+}
+
+function operatorChild(source: FieldSource, field: string, op: string): Grammar {
+  switch (op) {
+    case '$in':
+    case '$nin':
+    case '$all':
+    case '$eq':
+    case '$ne':
+    case '$gt':
+    case '$gte':
+    case '$lt':
+    case '$lte':
+    case '$regex':
+    case '$size':
+      return { g: 'opValue', source, field, operator: op, inArray: false, siblings: [] }
+    case '$not':
+      return { g: 'field', source, field }
+    case '$elemMatch':
+      return { g: 'elemMatch', source, field }
+    case '$exists':
+      return { g: 'literal', values: ['true', 'false'], preferred: 'true' }
+    case '$type':
+      return { g: 'typeAlias', source, field }
+    case '$options':
+      return { g: 'literal', values: ['"i"', '"m"', '"x"', '"s"', '"im"'] }
+  }
+  if (GEO_OPERATORS.has(op)) return { g: 'geo' }
+  if (op.startsWith('$')) return OPAQUE
+  // A plain key inside a field's object is an embedded-document match.
+  return {
+    g: 'opValue',
+    source,
+    field: join(field, op),
+    operator: null,
+    inArray: false,
+    siblings: []
+  }
+}
+
+function jsonSchemaChild(source: FieldSource, base: string, key: string): Grammar {
+  switch (key) {
+    case 'properties':
+      return { g: 'jsonProps', source, base }
+    case 'items':
+      return { g: 'jsonSchema', source, base }
+    case 'bsonType':
+      return { g: 'typeAlias', source, field: base }
+    case 'required':
+      // Required names are relative to the schema's level; only the top level maps to field paths.
+      return base === '' ? { g: 'fieldName', source } : OPAQUE
+    default:
+      return OPAQUE
+  }
+}
+
+function projectionOperatorChild(
+  grammar: Extract<Grammar, { g: 'projField' }>,
+  key: string
+): Grammar {
+  if (key === '$elemMatch') return { g: 'elemMatch', source: grammar.source, field: grammar.field }
+  if (key === '$meta') {
+    return {
+      g: 'literal',
+      values: ['"textScore"', '"indexKey"', '"searchScore"', '"searchHighlights"'],
+      preferred: '"textScore"'
+    }
+  }
+  if (key === '$slice') return OPAQUE
+  if (key.startsWith('$')) return operand(grammar.source, [], key)
+  return { ...grammar, field: join(grammar.field, key) }
+}
+
+function operand(source: FieldSource, vars: readonly Variable[], op: string): Grammar {
+  const def = EXPRESSIONS.get(op)
+  if (def?.form === 'named') return { g: 'opArgs', operator: op, source, vars }
+  const args = def?.args
+  if (args === 'compared') return { g: 'expression', source, vars, compared: true }
+  return { g: 'expression', source, vars, prefer: args }
+}
+
+function operatorArg(
+  operator: string,
+  source: FieldSource,
+  vars: readonly Variable[],
+  key: string,
+  node: ObjectNode
+): Grammar {
+  const spec = ARG_SPECS[operator]?.find((arg) => arg.name === key)
+  const grammar = spec ? argGrammar(spec.kind, source, vars) : OPAQUE
+  const bound = argVariables(operator, key, node, source)
+  if (grammar.g !== 'expression' || bound.length === 0) return grammar
+  return { ...grammar, vars: [...vars, ...bound] }
+}
+
+/** Variables an operator binds for its argument `key`. */
+function argVariables(
+  operator: string,
+  key: string,
+  node: ObjectNode,
+  source: FieldSource
+): Variable[] {
+  const input = entryValue(node, 'input')
+  switch (operator) {
+    case '$let':
+      return key === 'in' ? boundVariables(entryValue(node, 'vars'), source) : []
+    case '$map':
+    case '$filter':
+      if (key !== 'in' && key !== 'cond') return []
+      return [variable(stringValue(entryValue(node, 'as')) ?? 'this', input, source)]
+    case '$reduce':
+      return key === 'in' ? [{ name: 'value' }, variable('this', input, source)] : []
+    default:
+      return []
+  }
+}
+
+/** Variables named by the keys of a `let` / `vars` object. */
+function boundVariables(node: AstNode | null | undefined, source: FieldSource): Variable[] {
+  if (node?.n !== 'object') return []
+  return node.entries.map((entry) => variable(entry.key, entry.value, source))
+}
+
+/** Variable `name` holding `value`; bound to a field when `value` references one. */
+function variable(name: string, value: AstNode | null | undefined, source: FieldSource): Variable {
+  const path = fieldPath(value)
+  return path === null ? { name } : { name, field: { source, path } }
+}
+
+/** The field another argument of a comparison references. */
+function comparedField(source: FieldSource, node: ArrayNode): FieldRef | undefined {
+  for (const item of node.items) {
+    const path = fieldPath(item)
+    if (path !== null) return { source, path }
+  }
+  return undefined
+}
+
+/** Path of a `"$path"` field reference; null for anything else, `"$$var"` and a bare `"$"` included. */
+function fieldPath(node: AstNode | null | undefined): string | null {
+  const path = fieldRefPath(stringValue(node))
+  return path === '' ? null : path
+}
+
+function stageBody(source: FieldSource, vars: readonly Variable[], name: string): Grammar {
+  switch (name) {
+    case '$match':
+      return { g: 'query', source, base: '', topLevel: true, vars }
+    case '$project':
+      return { g: 'projection', source }
+    case '$addFields':
+    case '$set':
+      return { g: 'newFields', source, vars, group: false }
+    case '$group':
+      return { g: 'newFields', source, vars, group: true }
+    case '$unset':
+      return { g: 'fieldName', source }
+    case '$sort':
+      return { g: 'sort', source }
+    case '$replaceWith':
+    case '$sortByCount':
+    case '$redact':
+      return { g: 'expression', source, vars }
+    case '$facet':
+      return { g: 'facet', source, vars }
+    case '$unwind':
+      return {
+        g: 'args',
+        owner: name,
+        source,
+        vars,
+        scalar: { g: 'expression', source, vars, prefer: 'array' }
+      }
+    case '$unionWith':
+    case '$out':
+    case '$merge':
+      return { g: 'args', owner: name, source, vars, scalar: COLLECTION }
+  }
+  return ARG_SPECS[name] ? { g: 'args', owner: name, source, vars } : OPAQUE
+}
+
+function argGrammar(kind: ArgKind, source: FieldSource, vars: readonly Variable[]): Grammar {
+  if (typeof kind === 'object') {
+    return 'enum' in kind
+      ? { g: 'literal', values: kind.enum }
+      : { g: 'args', owner: kind.args, source, vars }
+  }
+  switch (kind) {
+    case 'expression':
+      return { g: 'expression', source, vars }
+    case 'dateExpr':
+      return { g: 'expression', source, vars, prefer: 'date' }
+    case 'boolExpr':
+      return { g: 'expression', source, vars, prefer: 'bool' }
+    case 'arrayRef':
+      return { g: 'expression', source, vars, prefer: 'array' }
+    case 'query':
+      return { g: 'query', source, base: '', topLevel: true, vars }
+    case 'sort':
+      return { g: 'sort', source }
+    case 'projection':
+      return { g: 'projection', source }
+    case 'update':
+      return { g: 'update', source }
+    case 'document':
+      return { g: 'document', coll: source.coll, path: '' }
+    case 'fieldPath':
+    case 'fieldPaths':
+      return { g: 'fieldName', source }
+    case 'collection':
+      return COLLECTION
+    case 'pipeline':
+      return { g: 'pipeline', source, vars, nested: 'sub' }
+    case 'accumulators':
+      return { g: 'outputs', source, vars, window: false }
+    case 'windowOutput':
+      return { g: 'outputs', source, vars, window: true }
+    case 'fillOutput':
+      return { g: 'fillOutput', source, vars }
+    case 'vars':
+      return { g: 'letVars', source, vars }
+    case 'bool':
+      return BOOL
+    default:
+      return OPAQUE
+  }
+}
+
+function shellArg(
+  arg: ShellArg,
+  source: FieldSource,
+  method: string,
+  update: AstNode | undefined
+): Grammar {
+  const document: Grammar = { g: 'document', coll: source.coll, path: '' }
+  switch (arg) {
+    case 'query':
+      return { g: 'query', source, base: '', topLevel: true, vars: [] }
+    case 'projection':
+      return { g: 'projection', source }
+    case 'pipeline':
+      // A shell aggregate may write its output with a final $out / $merge.
+      return { g: 'pipeline', source, vars: [], writes: true }
+    case 'sort':
+      return { g: 'sort', source }
+    case 'fieldName':
+      return { g: 'fieldName', source }
+    case 'document':
+      return document
+    case 'documents':
+      return { g: 'list', of: document }
+    case 'update':
+      return { g: 'update', source }
+    case 'bulkOperations':
+      return { g: 'list', of: { g: 'bulkOperation', source } }
+    case 'options':
+      return { g: 'args', owner: optionsOwner(method), source, vars: [], update }
+  }
+}
+
+/** Grammar of the value update operator `op` gives `key`, a field path that may address array elements. */
+function updateFieldValue(source: FieldSource, op: string, key: string): Grammar {
+  const path = withoutPositional(key)
+  const element = POSITIONAL_SEGMENT.test(key.slice(key.lastIndexOf('.') + 1))
+  const coll = source.coll
+  switch (op) {
+    case '$set':
+    case '$setOnInsert':
+    case '$min':
+    case '$max':
+      return { g: 'docValue', coll, path, element }
+    case '$pullAll':
+      return { g: 'docValue', coll, path, element: false }
+    case '$push':
+    case '$addToSet':
+      return { g: 'arrayPush', coll, path, op }
+    case '$pull':
+      return { g: 'pull', source, field: path }
+    case '$rename':
+      return { g: 'fieldName', source, renaming: path }
+    case '$currentDate':
+    case '$bit':
+      return {
+        g: 'args',
+        owner: `${op}.field`,
+        source,
+        vars: [],
+        scalar: { g: 'updateValue', source, op, field: path }
+      }
+    default:
+      return { g: 'updateValue', source, op, field: path }
+  }
+}
+
+function arrayPushChild(grammar: Extract<Grammar, { g: 'arrayPush' }>, key: string): Grammar {
+  const { coll, path } = grammar
+  if (key === '$each') return { g: 'docValue', coll, path, element: false }
+  if (key === '$sort') return { g: 'elementSort', coll, path }
+  if (key.startsWith('$')) return OPAQUE
+  // A plain key makes the pushed element a document.
+  return { g: 'docValue', coll, path: join(path, key), element: false }
+}
+
+/** Field paths the other operators of an update document change. */
+function takenFields(update: ObjectNode, op: string): string[] {
+  return update.entries.flatMap((entry) =>
+    entry.key !== op && entry.value?.n === 'object'
+      ? entry.value.entries.map((field) => field.key)
+      : []
+  )
+}
+
+/** `$[name]` placeholders in the field paths of an update document, with the array path each stands for. */
+function arrayIdentifiers(update: AstNode | null | undefined): ArrayIdentifier[] {
+  const out: ArrayIdentifier[] = []
+  if (update?.n !== 'object') return out
+  for (const operator of update.entries) {
+    if (operator.value?.n !== 'object') continue
+    for (const { key } of operator.value.entries) {
+      const path: string[] = []
+      for (const segment of key.split('.')) {
+        const name = ARRAY_IDENTIFIER.exec(segment)?.[1]
+        if (name !== undefined && !out.some((id) => id.name === name)) {
+          out.push({ name, path: path.join('.') })
+        }
+        if (!POSITIONAL_SEGMENT.test(segment)) path.push(segment)
+      }
+    }
+  }
+  return out
+}
+
+/** Identifiers one condition may filter: the one its keys name, else those no other condition filters. */
+function filteredIdentifiers(
+  grammar: Extract<Grammar, { g: 'arrayFilter' }>,
+  present: readonly string[]
+): ArrayIdentifier[] {
+  const named = grammar.identifiers.filter((id) =>
+    present.some((key) => firstSegment(key) === id.name)
+  )
+  if (named.length > 0) return named
+  return grammar.identifiers.filter((id) => !grammar.used.includes(id.name))
+}
+
+function firstSegment(path: string): string {
+  const dot = path.indexOf('.')
+  return dot === -1 ? path : path.slice(0, dot)
+}
+
+function siblingsOf(node: ArrayNode): string[] {
+  return node.items.map(literalText).filter((text): text is string => text !== null)
+}
+
+/** Source-independent text of a literal, comparable with rendered sample values. */
+function literalText(node: AstNode): string | null {
+  switch (node.n) {
+    case 'string':
+      return JSON.stringify(node.value)
+    case 'number':
+      return String(Number(node.raw))
+    case 'ident':
+      return node.name
+    case 'call': {
+      const args = node.args.map(literalText)
+      return args.every((arg) => arg !== null) ? `${node.callee}(${args.join(', ')})` : null
+    }
+    default:
+      return null
+  }
+}
+
+function collectTargets(stages: readonly StageAst[], add: (name: string | null) => void): void {
+  for (const stage of stages) {
+    switch (stage.name) {
+      case '$lookup':
+      case '$graphLookup':
+      case '$unionWith':
+        add(foreignCollection(stage))
+        collectPipeline(entryValue(stage.body, 'pipeline'), add)
+        break
+      case '$facet':
+        if (stage.body?.n === 'object') {
+          for (const entry of stage.body.entries) collectPipeline(entry.value, add)
+        }
+        break
+    }
+  }
+}
+
+function collectPipeline(
+  node: AstNode | null | undefined,
+  add: (name: string | null) => void
+): void {
+  if (node?.n === 'array') collectTargets(toStages(node.items), add)
+}
diff --git a/src/renderer/src/lib/completion/monacoAdapter.test.ts b/src/renderer/src/lib/completion/monacoAdapter.test.ts
new file mode 100644
index 0000000..386d999
--- /dev/null
+++ b/src/renderer/src/lib/completion/monacoAdapter.test.ts
@@ -0,0 +1,305 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type * as Monaco from 'monaco-editor'
+import { createSchemaBuilder } from '@shared/collectionSchema'
+import type { CollectionSchema } from '@shared/types'
+import { attachCompletion, registerMongoCompletion, type CompletionBinding } from './monacoAdapter'
+import type { CompletionEnv } from './useCompletionEnv'
+
+type Provider = Monaco.languages.CompletionItemProvider
+
+const monacoState = vi.hoisted(() => ({
+  registrations: [] as Array<{ language: string; provider: unknown }>,
+  editors: [] as unknown[]
+}))
+
+vi.mock('monaco-editor', () => ({
+  languages: {
+    CompletionItemKind: {
+      Method: 0,
+      Function: 1,
+      Constructor: 2,
+      Field: 3,
+      Variable: 4,
+      Class: 5,
+      Module: 8,
+      Operator: 11,
+      Value: 13,
+      EnumMember: 16,
+      Keyword: 17,
+      TypeParameter: 24
+    },
+    CompletionItemInsertTextRule: { InsertAsSnippet: 4 },
+    CompletionTriggerKind: { Invoke: 0, TriggerCharacter: 1, TriggerForIncompleteCompletions: 2 },
+    registerCompletionItemProvider: (language: string, provider: unknown) => {
+      monacoState.registrations.push({ language, provider })
+      return { dispose: () => undefined }
+    }
+  },
+  editor: { getEditors: () => monacoState.editors }
+}))
+
+const schemaOf = (...docs: unknown[]): CollectionSchema => {
+  const builder = createSchemaBuilder()
+  for (const doc of docs) builder.add(doc)
+  return builder.build()
+}
+
+const SCHEMAS: Record<string, CollectionSchema> = {
+  users: schemaOf({ _id: { $oid: '507f1f77bcf86cd799439011' }, name: 'ada' }),
+  orders: schemaOf({ _id: { $oid: '507f1f77bcf86cd799439012' }, total: { $numberInt: '3' } })
+}
+
+/** Text model double with Monaco's 1-based line/column positions. */
+function fakeModel(text: string) {
+  const lineStarts = [0]
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') lineStarts.push(i + 1)
+  return {
+    getValue: () => text,
+    getOffsetAt: (p: { lineNumber: number; column: number }) =>
+      (lineStarts[p.lineNumber - 1] ?? 0) + p.column - 1,
+    getPositionAt: (offset: number) => {
+      let line = 0
+      while (line + 1 < lineStarts.length && (lineStarts[line + 1] ?? 0) <= offset) line++
+      return { lineNumber: line + 1, column: offset - (lineStarts[line] ?? 0) + 1 }
+    }
+  }
+}
+
+function fakeEditor(model: ReturnType<typeof fakeModel>) {
+  const focusListeners = new Set<() => void>()
+  const disposeListeners = new Set<() => void>()
+  const actions = new Map<string, Monaco.editor.IActionDescriptor>()
+  const editor = {
+    getModel: () => model,
+    onDidFocusEditorText: (fn: () => void) => {
+      focusListeners.add(fn)
+      return { dispose: () => focusListeners.delete(fn) }
+    },
+    onDidDispose: (fn: () => void) => {
+      disposeListeners.add(fn)
+      return { dispose: () => disposeListeners.delete(fn) }
+    },
+    addAction: (descriptor: Monaco.editor.IActionDescriptor) => {
+      actions.set(descriptor.id, descriptor)
+      return { dispose: () => actions.delete(descriptor.id) }
+    },
+    focus: () => focusListeners.forEach((fn) => fn()),
+    dispose: () => disposeListeners.forEach((fn) => fn()),
+    actions
+  }
+  monacoState.editors.push(editor)
+  return editor
+}
+
+const asEditor = (e: ReturnType<typeof fakeEditor>) =>
+  e as unknown as Monaco.editor.IStandaloneCodeEditor
+
+function makeEnv(overrides: Partial<CompletionEnv> = {}): CompletionEnv {
+  return {
+    coll: 'users',
+    collections: ['users', 'orders'],
+    uuidEncoding: 'default',
+    timezone: 'UTC',
+    loadSchema: vi.fn(async (name: string) => SCHEMAS[name] ?? null),
+    prefetchSchema: vi.fn(),
+    refreshSchema: vi.fn(),
+    ...overrides
+  }
+}
+
+const INVOKE: Monaco.languages.CompletionContext = { triggerKind: 0 }
+const char = (c: string): Monaco.languages.CompletionContext => ({
+  triggerKind: 1,
+  triggerCharacter: c
+})
+
+let provider: Provider
+
+beforeEach(() => {
+  monacoState.registrations.length = 0
+  monacoState.editors.length = 0
+  registerMongoCompletion()
+  provider = monacoState.registrations[0]?.provider as Provider
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+/** Completion list at the `|` marker of `marked` in an editor bound to `binding`. */
+async function complete(
+  marked: string,
+  binding: CompletionBinding | null,
+  options: {
+    context?: Monaco.languages.CompletionContext
+    cancelled?: () => boolean
+  } = {}
+): Promise<Monaco.languages.CompletionList> {
+  const offset = marked.indexOf('|')
+  const model = fakeModel(marked.slice(0, offset) + marked.slice(offset + 1))
+  attachCompletion(asEditor(fakeEditor(model)), () => binding)
+  const token = {
+    get isCancellationRequested() {
+      return options.cancelled?.() ?? false
+    }
+  }
+  const list = await provider.provideCompletionItems(
+    model as unknown as Monaco.editor.ITextModel,
+    model.getPositionAt(offset) as Monaco.Position,
+    options.context ?? INVOKE,
+    token as Monaco.CancellationToken
+  )
+  if (!list) throw new Error('provider returned nothing')
+  return list
+}
+
+const labelOf = (item: Monaco.languages.CompletionItem): string =>
+  typeof item.label === 'string' ? item.label : item.label.label
+const byLabel = (list: Monaco.languages.CompletionList, label: string) =>
+  list.suggestions.find((s) => labelOf(s) === label)
+
+describe('registerMongoCompletion', () => {
+  it('registers one mongo-shell provider with the completion trigger characters', () => {
+    expect(monacoState.registrations.map((r) => r.language)).toEqual(['mongo-shell'])
+    expect(provider.triggerCharacters).toEqual(['"', "'", '$', ':', ' ', '.', '{', '['])
+  })
+})
+
+describe('mongo-shell completion provider', () => {
+  it('maps a snippet constructor with its range, rank and preselection', async () => {
+    const env = makeEnv()
+    const list = await complete('{\n  "_id":|\n}', { kind: 'filter', env })
+
+    const ctor = list.suggestions.find((s) => s.preselect)
+    expect(ctor).toMatchObject({
+      label: { label: 'ObjectId("…")' },
+      kind: 2,
+      insertText: ' ObjectId("$0")',
+      insertTextRules: 4,
+      range: { startLineNumber: 2, startColumn: 9, endLineNumber: 2, endColumn: 9 }
+    })
+    expect(ctor?.sortText?.startsWith('a')).toBe(true)
+    expect(list.incomplete).toBe(false)
+    expect(env.loadSchema).toHaveBeenCalledWith('users')
+  })
+
+  it('inserts field keys as plain text and re-opens suggestions after them', async () => {
+    const list = await complete('{ na| }', { kind: 'filter', env: makeEnv() })
+
+    expect(byLabel(list, 'name')).toMatchObject({
+      kind: 3,
+      insertText: 'name: ',
+      insertTextRules: undefined,
+      filterText: 'name',
+      command: { id: 'editor.action.triggerSuggest', title: 'Suggest' },
+      range: { startLineNumber: 1, startColumn: 3, endLineNumber: 1, endColumn: 5 }
+    })
+    expect(byLabel(list, '$and')).toMatchObject({ kind: 11 })
+  })
+
+  it('applies trigger-character gating and treats incomplete re-requests as invokes', async () => {
+    const binding: CompletionBinding = { kind: 'filter', env: makeEnv() }
+
+    expect((await complete('{ na |', binding, { context: char(' ') })).suggestions).toEqual([])
+    expect(
+      (await complete('{ "_id": |', binding, { context: char(' ') })).suggestions.length
+    ).toBeGreaterThan(0)
+    expect(
+      (await complete('{ na|', binding, { context: { triggerKind: 2 } })).suggestions.length
+    ).toBeGreaterThan(0)
+  })
+
+  it("loads the schema of the command's collection in the shell editor", async () => {
+    const env = makeEnv()
+    const list = await complete('db.orders.find({ t| })', { kind: 'shell', env })
+
+    expect(env.loadSchema).toHaveBeenCalledWith('orders')
+    expect(byLabel(list, 'total')).toBeDefined()
+    expect(byLabel(list, 'name')).toBeUndefined()
+  })
+
+  it('uses the shell parser rules for collection accessors and aggregate cursors', async () => {
+    const env = makeEnv({ coll: 'my logs' })
+    const root = await complete('|', { kind: 'shell', env })
+    expect(root.suggestions.find((s) => s.preselect)?.insertText).toBe(
+      'db.getCollection("my logs").find({ $0 })'
+    )
+    const cursor = await complete('db.users.aggregate([]).|', { kind: 'shell', env })
+    expect(cursor.suggestions.map(labelOf)).toEqual(['toArray', 'pretty'])
+  })
+
+  it('answers without a slow schema and marks the list incomplete', async () => {
+    vi.useFakeTimers()
+    const env = makeEnv({ loadSchema: vi.fn(() => new Promise<null>(() => undefined)) })
+
+    const pending = complete('{ na|', { kind: 'filter', env })
+    await vi.advanceTimersByTimeAsync(300)
+    const list = await pending
+
+    expect(list.incomplete).toBe(true)
+    expect(byLabel(list, 'name')).toBeUndefined()
+    expect(byLabel(list, '$or')).toBeDefined()
+  })
+
+  it('returns nothing for a cancelled request, a dead position or a missing binding', async () => {
+    const env = makeEnv()
+    expect(
+      (await complete('{ na|', { kind: 'filter', env }, { cancelled: () => true })).suggestions
+    ).toEqual([])
+    expect((await complete('{ a: 1 // na|', { kind: 'filter', env })).suggestions).toEqual([])
+    expect((await complete('{ na|', null)).suggestions).toEqual([])
+  })
+
+  it('ignores models that no bound editor shows', async () => {
+    const model = fakeModel('{ ')
+    const list = await provider.provideCompletionItems(
+      model as unknown as Monaco.editor.ITextModel,
+      { lineNumber: 1, column: 3 } as Monaco.Position,
+      INVOKE,
+      { isCancellationRequested: false } as Monaco.CancellationToken
+    )
+    expect(list).toEqual({ suggestions: [] })
+  })
+})
+
+describe('attachCompletion', () => {
+  it('prefetches on focus and offers a refresh action', () => {
+    const env = makeEnv()
+    const editor = fakeEditor(fakeModel(''))
+    attachCompletion(asEditor(editor), () => ({ kind: 'filter', env }))
+
+    editor.focus()
+    void editor.actions.get('mongobench.refreshSchema')?.run(asEditor(editor))
+
+    expect(env.prefetchSchema).toHaveBeenCalledTimes(1)
+    expect(env.refreshSchema).toHaveBeenCalledTimes(1)
+  })
+
+  it('unbinds the editor when disposed or when the editor is disposed', async () => {
+    const env = makeEnv()
+    const model = fakeModel('{ ')
+    const request = () =>
+      provider.provideCompletionItems(
+        model as unknown as Monaco.editor.ITextModel,
+        { lineNumber: 1, column: 3 } as Monaco.Position,
+        INVOKE,
+        { isCancellationRequested: false } as Monaco.CancellationToken
+      ) as Promise<Monaco.languages.CompletionList>
+
+    const first = fakeEditor(model)
+    const attachment = attachCompletion(asEditor(first), () => ({ kind: 'filter', env }))
+    expect((await request()).suggestions.length).toBeGreaterThan(0)
+    attachment.dispose()
+    expect((await request()).suggestions).toEqual([])
+    expect(first.actions.size).toBe(0)
+    first.focus()
+    expect(env.prefetchSchema).not.toHaveBeenCalled()
+
+    monacoState.editors.length = 0
+    const second = fakeEditor(model)
+    attachCompletion(asEditor(second), () => ({ kind: 'filter', env }))
+    second.dispose()
+    expect((await request()).suggestions).toEqual([])
+    expect(second.actions.size).toBe(0)
+  })
+})
diff --git a/src/renderer/src/lib/completion/monacoAdapter.ts b/src/renderer/src/lib/completion/monacoAdapter.ts
new file mode 100644
index 0000000..63ffe06
--- /dev/null
+++ b/src/renderer/src/lib/completion/monacoAdapter.ts
@@ -0,0 +1,165 @@
+import * as monaco from 'monaco-editor'
+import type { CollectionSchema } from '@shared/types'
+import {
+  SHELL_AGGREGATE_CURSOR_METHODS,
+  SHELL_COLLECTION_METHODS,
+  SHELL_CURSOR_METHODS,
+  shellCollectionAccessor
+} from '../shellParser'
+import { analyzeContext, type EditorKind } from './context'
+import { suggest, type Suggestion, type SuggestionKind, type SuggestTrigger } from './suggest'
+import type { CompletionEnv } from './useCompletionEnv'
+
+export type CompletionBinding = { kind: EditorKind; env: CompletionEnv }
+
+// No `,` (quick suggestions already cover the next key), no `(` and no letters.
+const TRIGGER_CHARACTERS = ['"', "'", '$', ':', ' ', '.', '{', '[']
+// A cached or quick sample makes it into this request; a slower one into the next keystroke's.
+const SCHEMA_WAIT_MS = 300
+
+const Kind = monaco.languages.CompletionItemKind
+const ITEM_KINDS: Record<SuggestionKind, monaco.languages.CompletionItemKind> = {
+  field: Kind.Field,
+  operator: Kind.Operator,
+  stage: Kind.Module,
+  expression: Kind.Function,
+  accumulator: Kind.Function,
+  constructor: Kind.Constructor,
+  value: Kind.Value,
+  literal: Kind.Keyword,
+  enum: Kind.EnumMember,
+  typeAlias: Kind.TypeParameter,
+  collection: Kind.Class,
+  method: Kind.Method,
+  variable: Kind.Variable
+}
+
+const RETRIGGER: monaco.languages.Command = { id: 'editor.action.triggerSuggest', title: 'Suggest' }
+
+// Keyed by editor, not model: query editors swap models per tab and slot.
+const bindings = new WeakMap<monaco.editor.ICodeEditor, () => CompletionBinding | null>()
+
+/** Registers the single `mongo-shell` completion provider; call once from monacoSetup. */
+export function registerMongoCompletion(): void {
+  monaco.languages.registerCompletionItemProvider('mongo-shell', {
+    triggerCharacters: TRIGGER_CHARACTERS,
+    provideCompletionItems
+  })
+}
+
+/**
+ * Binds completion to `editor` until disposed or the editor is disposed.
+ * @param binding read on every request; null disables completion for the moment
+ */
+export function attachCompletion(
+  editor: monaco.editor.IStandaloneCodeEditor,
+  binding: () => CompletionBinding | null
+): monaco.IDisposable {
+  bindings.set(editor, binding)
+  const disposables = [
+    editor.onDidFocusEditorText(() => binding()?.env.prefetchSchema()),
+    editor.addAction({
+      id: 'mongobench.refreshSchema',
+      label: 'Refresh Field Suggestions',
+      contextMenuGroupId: 'navigation',
+      run: () => binding()?.env.refreshSchema()
+    })
+  ]
+  const dispose = (): void => {
+    if (bindings.get(editor) === binding) bindings.delete(editor)
+    for (const d of disposables.splice(0)) d.dispose()
+  }
+  disposables.push(editor.onDidDispose(dispose))
+  return { dispose }
+}
+
+async function provideCompletionItems(
+  model: monaco.editor.ITextModel,
+  position: monaco.Position,
+  context: monaco.languages.CompletionContext,
+  token: monaco.CancellationToken
+): Promise<monaco.languages.CompletionList> {
+  const editor = monaco.editor.getEditors().find((e) => e.getModel() === model)
+  const binding = editor ? bindings.get(editor)?.() : null
+  if (!binding) return { suggestions: [] }
+  const { kind, env } = binding
+  const ctx = analyzeContext(model.getValue(), model.getOffsetAt(position), kind, env.coll)
+  if (ctx.position.at === 'none') return { suggestions: [] }
+
+  const { schemas, pending } = await loadSchemas(ctx.collections, env)
+  if (token.isCancellationRequested) return { suggestions: [] }
+  const result = suggest(
+    ctx,
+    {
+      ...env,
+      schemaOf: (name) => schemas.get(name) ?? null,
+      now: new Date(),
+      shellMethods: SHELL_COLLECTION_METHODS,
+      cursorMethods: SHELL_CURSOR_METHODS,
+      aggregateCursorMethods: SHELL_AGGREGATE_CURSOR_METHODS,
+      collectionAccessor: shellCollectionAccessor
+    },
+    triggerOf(context)
+  )
+  const start = model.getPositionAt(result.range.start)
+  const end = model.getPositionAt(result.range.end)
+  const range: monaco.IRange = {
+    startLineNumber: start.lineNumber,
+    startColumn: start.column,
+    endLineNumber: end.lineNumber,
+    endColumn: end.column
+  }
+  // Incomplete makes Monaco ask again on the next keystroke, when the schema may have arrived.
+  return {
+    suggestions: result.items.map((item) => toCompletionItem(item, range)),
+    incomplete: pending
+  }
+}
+
+const LOADING = Symbol('loading')
+
+async function loadSchemas(
+  names: readonly string[],
+  env: CompletionEnv
+): Promise<{ schemas: Map<string, CollectionSchema>; pending: boolean }> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<typeof LOADING>((resolve) => {
+    timer = setTimeout(() => resolve(LOADING), SCHEMA_WAIT_MS)
+  })
+  const loaded = await Promise.all(
+    names.map((name) => Promise.race([env.loadSchema(name), timeout]))
+  )
+  clearTimeout(timer)
+  const schemas = new Map<string, CollectionSchema>()
+  let pending = false
+  loaded.forEach((schema, i) => {
+    if (schema === LOADING) pending = true
+    else if (schema) schemas.set(names[i] as string, schema)
+  })
+  return { schemas, pending }
+}
+
+function triggerOf(context: monaco.languages.CompletionContext): SuggestTrigger {
+  // A re-request for an incomplete list continues what the user is typing, like an invoke.
+  return context.triggerKind === monaco.languages.CompletionTriggerKind.TriggerCharacter &&
+    context.triggerCharacter !== undefined
+    ? { kind: 'character', char: context.triggerCharacter }
+    : { kind: 'invoke' }
+}
+
+function toCompletionItem(item: Suggestion, range: monaco.IRange): monaco.languages.CompletionItem {
+  return {
+    label: item.description ? { label: item.label, description: item.description } : item.label,
+    kind: ITEM_KINDS[item.kind],
+    insertText: item.insertText,
+    insertTextRules: item.snippet
+      ? monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet
+      : undefined,
+    filterText: item.filterText,
+    sortText: item.sortText,
+    preselect: item.preselect,
+    documentation: item.documentation ? { value: item.documentation } : undefined,
+    command: item.retrigger ? RETRIGGER : undefined,
+    range
+  }
+}
diff --git a/src/renderer/src/lib/completion/pipelineFlow.test.ts b/src/renderer/src/lib/completion/pipelineFlow.test.ts
new file mode 100644
index 0000000..a707f93
--- /dev/null
+++ b/src/renderer/src/lib/completion/pipelineFlow.test.ts
@@ -0,0 +1,297 @@
+import { describe, expect, it } from 'vitest'
+import { createSchemaBuilder, dominantType } from '@shared/collectionSchema'
+import type { CollectionSchema } from '@shared/types'
+import { applyStages } from './pipelineFlow'
+import { scan, toStages, type StageAst } from './scanner'
+
+/** Stage ASTs of a pipeline written without its brackets. */
+const stages = (source: string): StageAst[] => {
+  const text = `[${source}, `
+  const pipeline = scan(text, text.length, 'value').frames[0]
+  if (pipeline?.f !== 'array') throw new Error(`not a pipeline: ${source}`)
+  return toStages(pipeline.node.items)
+}
+
+const schemaOf = (...docs: unknown[]): CollectionSchema => {
+  const builder = createSchemaBuilder()
+  for (const doc of docs) builder.add(doc)
+  return builder.build()
+}
+
+const users = schemaOf(
+  {
+    _id: { $oid: '507f1f77bcf86cd799439011' },
+    name: 'Ada',
+    age: { $numberInt: '36' },
+    price: { $numberDouble: '9.5' },
+    userId: { $oid: '507f1f77bcf86cd799439012' },
+    address: { city: 'Berlin', zip: '10115' },
+    tags: ['a', 'b'],
+    items: [{ sku: 'x', qty: { $numberInt: '1' } }]
+  },
+  { _id: { $oid: '507f1f77bcf86cd799439013' }, name: 'Bob', tags: [] }
+)
+
+const orders = schemaOf({
+  _id: { $oid: '507f1f77bcf86cd799439014' },
+  total: { $numberDouble: '3.5' }
+})
+
+const lookupSchema = (coll: string): CollectionSchema | null => (coll === 'orders' ? orders : null)
+
+const run = (pipeline: string, input: CollectionSchema | null = users) =>
+  applyStages(input, stages(pipeline), lookupSchema)
+
+const paths = (schema: CollectionSchema | null) => schema?.fields.map((f) => f.path)
+
+const typeOf = (schema: CollectionSchema | null, path: string) =>
+  dominantType(schema?.fields.find((f) => f.path === path)?.types)
+
+describe('applyStages: $project', () => {
+  it('keeps _id and the included fields with their subtrees', () => {
+    expect(paths(run('{ $project: { name: 1, address: 1 } }'))).toEqual([
+      '_id',
+      'address',
+      'address.city',
+      'address.zip',
+      'name'
+    ])
+  })
+
+  it('drops _id when it is excluded in an inclusion', () => {
+    expect(paths(run('{ $project: { _id: 0, name: 1 } }'))).toEqual(['name'])
+  })
+
+  it('keeps the parent of an included subfield', () => {
+    expect(paths(run('{ $project: { "address.city": 1 } }'))).toEqual([
+      '_id',
+      'address',
+      'address.city'
+    ])
+  })
+
+  it('removes excluded fields', () => {
+    expect(paths(run('{ $project: { address: 0, items: 0, tags: 0, price: 0 } }'))).toEqual([
+      '_id',
+      'age',
+      'name',
+      'userId'
+    ])
+  })
+
+  it('treats _id: 0 alone as an exclusion of _id only', () => {
+    const result = run('{ $project: { _id: 0 } }')
+    expect(paths(result)).not.toContain('_id')
+    expect(paths(result)).toContain('name')
+  })
+
+  it('types computed fields', () => {
+    const result = run('{ $project: { label: { $toUpper: "$name" }, n: "$age" } }')
+    expect(typeOf(result, 'label')).toBe('string')
+    expect(typeOf(result, 'n')).toBe('int')
+  })
+})
+
+describe('applyStages: $addFields / $set', () => {
+  it('copies a referenced field with its type and subtree', () => {
+    const result = run('{ $addFields: { home: "$address" } }')
+    expect(typeOf(result, 'home')).toBe('object')
+    expect(typeOf(result, 'home.city')).toBe('string')
+    expect(paths(result)).toContain('address')
+  })
+
+  it('infers operator result types', () => {
+    const result = run(
+      '{ $set: { s: { $toString: "$age" }, d: { $dateFromString: { dateString: "$name" } } } }'
+    )
+    expect(typeOf(result, 's')).toBe('string')
+    expect(typeOf(result, 'd')).toBe('date')
+  })
+
+  it('types literals', () => {
+    const result = run(
+      '{ $set: { flag: true, n: 5, x: 1.5, at: ISODate("2024-01-01"), id: ObjectId("507f1f77bcf86cd799439011") } }'
+    )
+    expect([
+      typeOf(result, 'flag'),
+      typeOf(result, 'n'),
+      typeOf(result, 'x'),
+      typeOf(result, 'at'),
+      typeOf(result, 'id')
+    ]).toEqual(['bool', 'int', 'double', 'date', 'objectId'])
+  })
+
+  it('adds fields to an embedded document instead of replacing it', () => {
+    const result = run('{ $addFields: { address: { country: "DE" } } }')
+    expect(paths(result)).toEqual(expect.arrayContaining(['address.city', 'address.country']))
+  })
+})
+
+describe('applyStages: $unset', () => {
+  it('removes a single field with its subtree', () => {
+    expect(paths(run('{ $unset: "address" }'))).not.toContain('address.city')
+  })
+
+  it('removes a list of fields', () => {
+    const result = paths(run('{ $unset: ["name", "age"] }'))
+    expect(result).not.toContain('name')
+    expect(result).not.toContain('age')
+    expect(result).toContain('_id')
+  })
+})
+
+describe('applyStages: $group', () => {
+  it('keeps the type and values of a referenced _id', () => {
+    const result = run('{ $group: { _id: "$userId", total: { $sum: "$price" }, n: { $sum: 1 } } }')
+    expect(paths(result)).toEqual(['_id', 'n', 'total'])
+    expect(typeOf(result, '_id')).toBe('objectId')
+    expect(result?.fields.find((f) => f.path === '_id')?.values).toHaveLength(1)
+    expect(['int', 'long', 'double', 'decimal']).toContain(typeOf(result, 'total'))
+    expect(typeOf(result, 'n')).toBe('int')
+  })
+
+  it('makes $push an array of the argument type', () => {
+    const result = run(
+      '{ $group: { _id: null, names: { $push: "$name" }, cities: { $addToSet: "$address" } } }'
+    )
+    expect(typeOf(result, '_id')).toBe('null')
+    expect(result?.fields.find((f) => f.path === 'names')).toMatchObject({
+      types: { array: 2 },
+      elementTypes: { string: 2 }
+    })
+    expect(typeOf(result, 'cities.city')).toBe('string')
+  })
+
+  it('types other accumulators', () => {
+    const result = run(
+      '{ $group: { _id: "$name", avg: { $avg: "$age" }, first: { $first: "$address" }, c: { $count: {} } } }'
+    )
+    expect(typeOf(result, 'avg')).toBe('double')
+    expect(typeOf(result, 'first.zip')).toBe('string')
+    expect(typeOf(result, 'c')).toBe('int')
+  })
+})
+
+describe('applyStages: $unwind', () => {
+  it('replaces an array with its element types', () => {
+    const result = run('{ $unwind: "$tags" }')
+    const tags = result?.fields.find((f) => f.path === 'tags')
+    expect(tags?.types).toEqual({ string: 2 })
+    expect(tags?.elementTypes).toBeUndefined()
+  })
+
+  it('keeps element subfields and adds includeArrayIndex', () => {
+    const result = run('{ $unwind: { path: "$items", includeArrayIndex: "idx" } }')
+    expect(typeOf(result, 'items')).toBe('object')
+    expect(typeOf(result, 'items.sku')).toBe('string')
+    expect(typeOf(result, 'idx')).toBe('long')
+  })
+})
+
+describe('applyStages: $lookup / $graphLookup', () => {
+  it('adds `as` as an array of foreign documents', () => {
+    const result = run(
+      '{ $lookup: { from: "orders", localField: "_id", foreignField: "userId", as: "orders" } }'
+    )
+    expect(result?.fields.find((f) => f.path === 'orders')).toMatchObject({
+      types: { array: 2 },
+      elementTypes: { object: 2 }
+    })
+    expect(typeOf(result, 'orders.total')).toBe('double')
+  })
+
+  it('applies a lookup pipeline to the foreign schema', () => {
+    const result = run(
+      '{ $lookup: { from: "orders", pipeline: [{ $project: { _id: 0, total: 1 } }], as: "o" } }'
+    )
+    expect(paths(result)?.filter((p) => p.startsWith('o.'))).toEqual(['o.total'])
+  })
+
+  it('adds the depth field of a graph lookup', () => {
+    const result = run('{ $graphLookup: { from: "orders", as: "chain", depthField: "depth" } }')
+    expect(typeOf(result, 'chain.depth')).toBe('long')
+    expect(typeOf(result, 'chain.total')).toBe('double')
+  })
+})
+
+describe('applyStages: re-rooting and reshaping stages', () => {
+  it('re-roots at an embedded document', () => {
+    expect(paths(run('{ $replaceRoot: { newRoot: "$address" } }'))).toEqual(['city', 'zip'])
+    expect(paths(run('{ $replaceWith: "$address" }'))).toEqual(['city', 'zip'])
+  })
+
+  it('re-roots at an object literal and at merged objects', () => {
+    expect(paths(run('{ $replaceWith: { n: "$name" } }'))).toEqual(['n'])
+    expect(paths(run('{ $replaceWith: { $mergeObjects: ["$address", { extra: 1 }] } }'))).toEqual([
+      'city',
+      'extra',
+      'zip'
+    ])
+  })
+
+  it('leaves only the count field after $count', () => {
+    const result = run('{ $match: {} }, { $count: "total" }')
+    expect(paths(result)).toEqual(['total'])
+    expect(typeOf(result, 'total')).toBe('int')
+  })
+
+  it('groups and counts with $sortByCount', () => {
+    const result = run('{ $sortByCount: "$name" }')
+    expect(paths(result)).toEqual(['_id', 'count'])
+    expect(typeOf(result, '_id')).toBe('string')
+  })
+
+  it('outputs count by default in $bucket', () => {
+    const result = run('{ $bucket: { groupBy: "$age", boundaries: [0, 18, 65] } }')
+    expect(paths(result)).toEqual(['_id', 'count'])
+    expect(typeOf(result, '_id')).toBe('int')
+  })
+
+  it('uses the output accumulators of $bucketAuto', () => {
+    const result = run(
+      '{ $bucketAuto: { groupBy: "$price", buckets: 4, output: { names: { $push: "$name" } } } }'
+    )
+    expect(paths(result)).toEqual(['_id', '_id.max', '_id.min', 'names'])
+    expect(typeOf(result, '_id.min')).toBe('double')
+  })
+
+  it('runs every $facet branch on the same input', () => {
+    const result = run(
+      '{ $facet: { byName: [{ $group: { _id: "$name" } }], total: [{ $count: "n" }] } }'
+    )
+    expect(paths(result)).toEqual(['byName', 'byName._id', 'total', 'total.n'])
+    expect(typeOf(result, 'byName')).toBe('array')
+  })
+
+  it('adds window outputs', () => {
+    const result = run(
+      '{ $setWindowFields: { sortBy: { age: 1 }, output: { rank: { $rank: {} }, running: { $sum: "$price", window: { documents: ["unbounded", "current"] } } } } }'
+    )
+    expect(typeOf(result, 'rank')).toBe('int')
+    expect(typeOf(result, 'running')).toBe('double')
+    expect(paths(result)).toContain('name')
+  })
+
+  it('merges the fields of a $unionWith collection', () => {
+    expect(paths(run('{ $unionWith: "orders" }'))).toContain('total')
+  })
+})
+
+describe('applyStages: pass-through and unknown input', () => {
+  it('passes the input through filtering and unknown stages', () => {
+    expect(
+      paths(
+        run('{ $match: { a: 1 } }, { $sort: { a: 1 } }, { $limit: 5 }, { $someFutureStage: {} }')
+      )
+    ).toEqual(paths(users))
+  })
+
+  it('returns null for stages whose output is not collection documents', () => {
+    expect(run('{ $collStats: {} }')).toBeNull()
+  })
+
+  it('stays unknown through pass-through stages and derives computed fields', () => {
+    expect(run('{ $match: {} }', null)).toBeNull()
+    expect(paths(run('{ $group: { _id: "$x", n: { $sum: 1 } } }', null))).toEqual(['_id', 'n'])
+  })
+})
diff --git a/src/renderer/src/lib/completion/pipelineFlow.ts b/src/renderer/src/lib/completion/pipelineFlow.ts
new file mode 100644
index 0000000..0ffbdd2
--- /dev/null
+++ b/src/renderer/src/lib/completion/pipelineFlow.ts
@@ -0,0 +1,650 @@
+/**
+ * Field set of a collection after pipeline stages, derived from its sampled schema and the
+ * stage ASTs; expression result types are inferred where the expression makes them evident.
+ */
+import type { BsonTypeName, CollectionSchema, SchemaField, TypeCounts } from '@shared/types'
+import { addCounts, compareText, dominantType, resolveField } from '@shared/collectionSchema'
+import { ACCUMULATOR_DEFS, CONSTRUCTOR_TYPES, EXPRESSIONS, NUMERIC_TYPES } from './catalog'
+import {
+  entryValue,
+  stringValue,
+  toStages,
+  type AstNode,
+  type ObjectNode,
+  type StageAst
+} from './scanner'
+
+type SchemaOf = (coll: string) => CollectionSchema | null
+
+export type ProjectionMode = 'include' | 'exclude' | null
+
+/**
+ * Field set after `stages` run on documents shaped like `input`.
+ * @param input sampled schema of the pipeline's collection; null when unknown
+ * @param schemaOf schemas of `$lookup`, `$graphLookup` and `$unionWith` targets
+ * @returns null when the output shape is unknown
+ */
+export function applyStages(
+  input: CollectionSchema | null,
+  stages: readonly StageAst[],
+  schemaOf: SchemaOf
+): CollectionSchema | null {
+  const shape = runStages(input ? toShape(input) : null, stages, schemaOf)
+  return shape ? toSchema(shape) : null
+}
+
+/**
+ * Inclusion or exclusion of a projection object, decided by its non-`_id` entries.
+ * @returns null while no entry decides it
+ */
+export function projectionMode(node: ObjectNode): ProjectionMode {
+  let include = false
+  for (const entry of node.entries) {
+    if (entry.key === '_id' || !entry.value) continue
+    if (isFalsyFlag(entry.value)) return 'exclude'
+    include = true
+  }
+  return include ? 'include' : null
+}
+
+/**
+ * Path of a `"$path"` field reference.
+ * @returns '' for a bare `$`; null for a `$$variable`, any other string and null
+ */
+export function fieldRefPath(value: string | null): string | null {
+  return value !== null && value.startsWith('$') && !value.startsWith('$$') ? value.slice(1) : null
+}
+
+/**
+ * Collection a `$lookup`, `$graphLookup` or `$unionWith` stage reads.
+ * @returns null when the stage names none
+ */
+export function foreignCollection(stage: StageAst): string | null {
+  if (stage.name === '$unionWith') {
+    return stringValue(stage.body) ?? stringValue(entryValue(stage.body, 'coll'))
+  }
+  return stringValue(entryValue(stage.body, 'from'))
+}
+
+type Shape = { sampleSize: number; truncated: boolean; fields: Map<string, SchemaField> }
+
+type ExprInfo = {
+  types: TypeCounts
+  elementTypes?: TypeCounts
+  /** Path of a plain field reference whose subtree is copied; '' for `$$ROOT`. */
+  ref?: string
+  /** The reference becomes the elements of an array (`$push: "$x"`). */
+  refAsElements?: boolean
+  /** Fields of an object literal. */
+  children?: [string, ExprInfo][]
+}
+
+const UNKNOWN: ExprInfo = { types: {} }
+const IDENT_TYPES: Readonly<Record<string, BsonTypeName>> = {
+  true: 'bool',
+  false: 'bool',
+  null: 'null',
+  undefined: 'undefined',
+  MinKey: 'minKey',
+  MaxKey: 'maxKey'
+}
+/** Stages whose output is not documents of the input collection. */
+const FOREIGN_OUTPUT = new Set([
+  '$collStats',
+  '$indexStats',
+  '$documents',
+  '$changeStream',
+  '$currentOp',
+  '$listSessions',
+  '$listSearchIndexes',
+  '$planCacheStats',
+  '$searchMeta'
+])
+
+function runStages(
+  input: Shape | null,
+  stages: readonly StageAst[],
+  schemaOf: SchemaOf
+): Shape | null {
+  let shape = input
+  for (const stage of stages) shape = applyStage(shape, stage, schemaOf)
+  return shape
+}
+
+function applyStage(input: Shape | null, stage: StageAst, schemaOf: SchemaOf): Shape | null {
+  const body = stage.body
+  if (FOREIGN_OUTPUT.has(stage.name)) return null
+  // Stages that compute fields still yield those fields when the input is unknown.
+  const shape = input ?? emptyShape(null)
+  switch (stage.name) {
+    case '$project':
+      return body?.n === 'object' ? project(shape, body) : input
+    case '$addFields':
+    case '$set':
+      return body?.n === 'object' ? addFields(shape, body) : input
+    case '$unset':
+      return input && unset(input, body)
+    case '$group':
+      return body?.n === 'object' ? group(shape, body) : input
+    case '$unwind':
+      return input && unwind(input, body)
+    case '$lookup':
+      return lookup(shape, body, foreignCollection(stage), schemaOf)
+    case '$graphLookup':
+      return graphLookup(shape, body, foreignCollection(stage), schemaOf)
+    case '$replaceRoot':
+      return reroot(shape, entryValue(body, 'newRoot'))
+    case '$replaceWith':
+      return reroot(shape, body)
+    case '$count': {
+      const name = stringValue(body)
+      return name ? derivedShape(shape, [[name, { types: one('int', weight(shape)) }]]) : null
+    }
+    case '$sortByCount':
+      return derivedShape(shape, [
+        ['_id', inferExpr(body, shape) ?? UNKNOWN],
+        ['count', { types: one('int', weight(shape)) }]
+      ])
+    case '$bucket':
+    case '$bucketAuto':
+      return bucket(shape, body, stage.name === '$bucketAuto')
+    case '$facet':
+      return body?.n === 'object' ? facet(shape, body, schemaOf) : null
+    case '$unionWith':
+      return unionWith(input, body, foreignCollection(stage), schemaOf)
+    case '$setWindowFields':
+      return windowFields(shape, entryValue(body, 'output'))
+    case '$geoNear': {
+      const distance = stringValue(entryValue(body, 'distanceField'))
+      if (!distance) return input
+      const out = cloneShape(shape)
+      setDerived(out, distance, { types: one('double', weight(shape)) }, shape)
+      return out
+    }
+    default:
+      return input
+  }
+}
+
+function project(shape: Shape, body: ObjectNode): Shape {
+  const id = body.entries.find((entry) => entry.key === '_id')
+  const idExcluded = !!id?.value && isFalsyFlag(id.value)
+  const mode = projectionMode(body)
+  if (mode === 'exclude' || (mode === null && idExcluded)) {
+    const out = cloneShape(shape)
+    exclude(out, body, '')
+    return out
+  }
+  const out = emptyShape(shape)
+  if (!idExcluded) copySubtree(shape, '_id', '_id', out)
+  include(out, shape, body, '')
+  return out
+}
+
+function exclude(out: Shape, node: ObjectNode, prefix: string): void {
+  for (const entry of node.entries) {
+    if (!entry.value) continue
+    const path = join(prefix, entry.key)
+    if (isFalsyFlag(entry.value)) removeSubtree(out, path)
+    else if (isObjectLiteral(entry.value)) exclude(out, entry.value, path)
+  }
+}
+
+function include(out: Shape, shape: Shape, node: ObjectNode, prefix: string): void {
+  for (const entry of node.entries) {
+    const value = entry.value
+    if (!value) continue
+    const path = join(prefix, entry.key)
+    if (isFalsyFlag(value)) continue
+    if (isTruthyFlag(value)) {
+      ensurePath(out, shape, path.slice(0, Math.max(0, path.lastIndexOf('.'))))
+      copySubtree(shape, canonical(shape, path), path, out)
+    } else if (isObjectLiteral(value)) {
+      ensurePath(out, shape, path)
+      include(out, shape, value, path)
+    } else setDerived(out, path, inferExpr(value, shape) ?? UNKNOWN, shape)
+  }
+}
+
+function addFields(shape: Shape, body: ObjectNode): Shape {
+  const out = cloneShape(shape)
+  const assign = (node: ObjectNode, prefix: string): void => {
+    for (const entry of node.entries) {
+      if (!entry.value) continue
+      const path = join(prefix, entry.key)
+      // An embedded object literal adds fields to the existing subdocument instead of replacing it.
+      if (isObjectLiteral(entry.value)) {
+        if (!out.fields.has(path)) {
+          out.fields.set(path, {
+            path,
+            docCount: shape.sampleSize,
+            types: one('object', weight(shape))
+          })
+        }
+        assign(entry.value, path)
+      } else setDerived(out, path, inferExpr(entry.value, shape) ?? UNKNOWN, shape)
+    }
+  }
+  assign(body, '')
+  return out
+}
+
+function unset(shape: Shape, body: AstNode | null): Shape {
+  const names = body?.n === 'array' ? body.items.map(stringValue) : [stringValue(body)]
+  const out = cloneShape(shape)
+  for (const name of names) if (name) removeSubtree(out, name)
+  return out
+}
+
+function group(shape: Shape, body: ObjectNode): Shape {
+  const fields: [string, ExprInfo][] = []
+  for (const entry of body.entries) {
+    if (!entry.value) continue
+    fields.push([
+      entry.key,
+      entry.key === '_id'
+        ? (inferExpr(entry.value, shape) ?? UNKNOWN)
+        : accumulatorInfo(entry.value, shape)
+    ])
+  }
+  return derivedShape(shape, fields)
+}
+
+function unwind(shape: Shape, body: AstNode | null): Shape {
+  const path = fieldRefPath(stringValue(body?.n === 'string' ? body : entryValue(body, 'path')))
+  if (path === null) return shape
+  const out = cloneShape(shape)
+  const field = lookupField(shape, path)
+  if (field) {
+    const types = field.elementTypes ?? withoutType(field.types, 'array')
+    const unwound: SchemaField = { ...field, types }
+    delete unwound.elementTypes
+    out.fields.set(field.path, unwound)
+  }
+  const index = stringValue(entryValue(body, 'includeArrayIndex'))
+  if (index) setDerived(out, index, { types: one('long', weight(shape)) }, shape)
+  return out
+}
+
+function lookup(
+  shape: Shape,
+  body: AstNode | null,
+  from: string | null,
+  schemaOf: SchemaOf
+): Shape {
+  let foreign = from ? schemaOf(from) : null
+  const pipeline = entryValue(body, 'pipeline')
+  if (pipeline?.n === 'array') foreign = applyStages(foreign, toStages(pipeline.items), schemaOf)
+  return joined(shape, stringValue(entryValue(body, 'as')), foreign, null)
+}
+
+function graphLookup(
+  shape: Shape,
+  body: AstNode | null,
+  from: string | null,
+  schemaOf: SchemaOf
+): Shape {
+  const depth = stringValue(entryValue(body, 'depthField'))
+  return joined(shape, stringValue(entryValue(body, 'as')), from ? schemaOf(from) : null, depth)
+}
+
+/** Adds `as` as an array of foreign documents. */
+function joined(
+  shape: Shape,
+  as: string | null,
+  foreign: CollectionSchema | null,
+  depthField: string | null
+): Shape {
+  if (!as) return shape
+  const w = weight(shape)
+  const out = cloneShape(shape)
+  removeSubtree(out, as)
+  out.fields.set(as, {
+    path: as,
+    docCount: shape.sampleSize,
+    types: one('array', w),
+    elementTypes: one('object', w)
+  })
+  for (const field of foreign?.fields ?? []) {
+    out.fields.set(`${as}.${field.path}`, { ...field, path: `${as}.${field.path}` })
+  }
+  if (depthField) {
+    const path = `${as}.${depthField}`
+    out.fields.set(path, { path, docCount: shape.sampleSize, types: one('long', w) })
+  }
+  return out
+}
+
+function reroot(shape: Shape, node: AstNode | null | undefined): Shape | null {
+  if (!node) return null
+  if (node.n === 'string') {
+    if (node.value === '$$ROOT' || node.value === '$$CURRENT') return shape
+    const path = fieldRefPath(node.value)
+    if (path === null) return null
+    const field = lookupField(shape, path)
+    const out = emptyShape(shape)
+    if (!field) return out
+    const prefix = `${field.path}.`
+    for (const [path, child] of shape.fields) {
+      if (path.startsWith(prefix)) {
+        out.fields.set(path.slice(prefix.length), { ...child, path: path.slice(prefix.length) })
+      }
+    }
+    return out
+  }
+  if (node.n !== 'object') return null
+  const first = node.entries[0]
+  if (first?.key === '$mergeObjects') {
+    const args = first.value?.n === 'array' ? first.value.items : first.value ? [first.value] : []
+    const out = emptyShape(shape)
+    for (const arg of args) {
+      for (const [path, field] of reroot(shape, arg)?.fields ?? []) out.fields.set(path, field)
+    }
+    return out
+  }
+  if (first?.key.startsWith('$')) return null
+  return derivedShape(
+    shape,
+    node.entries.map((entry) => [entry.key, inferExpr(entry.value, shape) ?? UNKNOWN])
+  )
+}
+
+function bucket(shape: Shape, body: AstNode | null, auto: boolean): Shape {
+  const groupBy = inferExpr(entryValue(body, 'groupBy') ?? null, shape)
+  const boundaries = entryValue(body, 'boundaries')
+  const bound = boundaries?.n === 'array' ? inferExpr(boundaries.items[0] ?? null, shape) : null
+  const w = weight(shape)
+  const id: ExprInfo = auto
+    ? {
+        types: one('object', w),
+        children: [
+          ['min', { types: groupBy?.types ?? {} }],
+          ['max', { types: groupBy?.types ?? {} }]
+        ]
+      }
+    : { types: bound?.types ?? {} }
+  const output = entryValue(body, 'output')
+  const fields: [string, ExprInfo][] = [['_id', id]]
+  if (output?.n === 'object') {
+    for (const entry of output.entries) {
+      if (entry.value) fields.push([entry.key, accumulatorInfo(entry.value, shape)])
+    }
+  } else fields.push(['count', { types: one('int', w) }])
+  return derivedShape(shape, fields)
+}
+
+function facet(shape: Shape, body: ObjectNode, schemaOf: SchemaOf): Shape {
+  const w = weight(shape)
+  const out = emptyShape(shape)
+  for (const entry of body.entries) {
+    if (entry.value?.n !== 'array') continue
+    const branch = runStages(shape, toStages(entry.value.items), schemaOf)
+    out.fields.set(entry.key, {
+      path: entry.key,
+      docCount: shape.sampleSize,
+      types: one('array', w),
+      elementTypes: one('object', w)
+    })
+    for (const [path, field] of branch?.fields ?? []) {
+      out.fields.set(`${entry.key}.${path}`, { ...field, path: `${entry.key}.${path}` })
+    }
+  }
+  return out
+}
+
+function unionWith(
+  input: Shape | null,
+  body: AstNode | null,
+  coll: string | null,
+  schemaOf: SchemaOf
+): Shape | null {
+  const pipeline = entryValue(body, 'pipeline')
+  let other = coll ? schemaOf(coll) : null
+  if (pipeline?.n === 'array') other = applyStages(other, toStages(pipeline.items), schemaOf)
+  if (!other) return input
+  const out = cloneShape(input ?? emptyShape(null))
+  for (const field of other.fields)
+    if (!out.fields.has(field.path)) out.fields.set(field.path, field)
+  return out
+}
+
+function windowFields(shape: Shape, output: AstNode | null | undefined): Shape {
+  const out = cloneShape(shape)
+  if (output?.n !== 'object') return out
+  for (const entry of output.entries) {
+    if (entry.value) setDerived(out, entry.key, accumulatorInfo(entry.value, shape), shape)
+  }
+  return out
+}
+
+/** Result of `{ $acc: arg }`; window bounds next to the operator are ignored. */
+function accumulatorInfo(node: AstNode, shape: Shape): ExprInfo {
+  if (node.n !== 'object') return UNKNOWN
+  const entry = node.entries.find((e) => e.key !== 'window')
+  const def = entry && ACCUMULATOR_DEFS.get(entry.key)
+  if (!entry || !def) return UNKNOWN
+  const w = weight(shape)
+  switch (def.returns) {
+    case 'sum': {
+      const type = dominantType(inferExpr(entry.value, shape)?.types)
+      return { types: one(type && NUMERIC_TYPES.has(type) ? type : 'double', w) }
+    }
+    case 'arg':
+      return inferExpr(entry.value, shape) ?? UNKNOWN
+    case 'argArray': {
+      const arg = inferExpr(entry.value, shape)
+      if (arg?.ref !== undefined) return { ...arg, refAsElements: true }
+      return { types: one('array', w), elementTypes: arg?.types ?? {} }
+    }
+    case 'output':
+      return inferExpr(entryValue(entry.value, 'output') ?? null, shape) ?? UNKNOWN
+    default:
+      return { types: one(def.returns, w) }
+  }
+}
+
+function inferExpr(node: AstNode | null, shape: Shape): ExprInfo | null {
+  if (!node) return null
+  const w = weight(shape)
+  switch (node.n) {
+    case 'string': {
+      const value = node.value
+      if (value === '$$ROOT' || value === '$$CURRENT') return { types: one('object', w), ref: '' }
+      if (value.startsWith('$$')) return null
+      const path = fieldRefPath(value)
+      if (path !== null) {
+        const field = lookupField(shape, path)
+        if (!field) return UNKNOWN
+        return { types: field.types, elementTypes: field.elementTypes, ref: field.path }
+      }
+      return { types: one('string', w) }
+    }
+    case 'number':
+      return { types: one(numberType(node.raw), w) }
+    case 'ident': {
+      const type = IDENT_TYPES[node.name]
+      return type ? { types: one(type, w) } : null
+    }
+    case 'regex':
+      return { types: one('regex', w) }
+    case 'call': {
+      const type = CONSTRUCTOR_TYPES[node.callee]
+      return type ? { types: one(type, w) } : null
+    }
+    case 'array': {
+      const elementTypes = node.items.reduce<TypeCounts>(
+        (counts, item) => addCounts(counts, inferExpr(item, shape)?.types ?? {}),
+        {}
+      )
+      return { types: one('array', w), elementTypes }
+    }
+    case 'object': {
+      const first = node.entries[0]
+      if (first?.key.startsWith('$')) {
+        if (first.key === '$literal') return literalInfo(first.value, w)
+        const returns = EXPRESSIONS.get(first.key)?.returns
+        return returns ? { types: one(returns, w) } : UNKNOWN
+      }
+      return {
+        types: one('object', w),
+        children: node.entries.map((entry) => [entry.key, inferExpr(entry.value, shape) ?? UNKNOWN])
+      }
+    }
+  }
+}
+
+function literalInfo(node: AstNode | null, w: number): ExprInfo {
+  if (node?.n === 'string') return { types: one('string', w) }
+  if (node?.n === 'number') return { types: one(numberType(node.raw), w) }
+  return UNKNOWN
+}
+
+/** Writes `info` at `path` of `out`, replacing the subtree there. */
+function setDerived(out: Shape, path: string, info: ExprInfo, input: Shape): void {
+  removeSubtree(out, path)
+  const w = weight(input)
+  if (info.ref !== undefined) {
+    copySubtree(input, info.ref, path, out)
+    const root = out.fields.get(path)
+    const types = info.ref === '' ? one('object', w) : (root?.types ?? info.types)
+    out.fields.set(
+      path,
+      info.refAsElements
+        ? {
+            path,
+            docCount: root?.docCount ?? input.sampleSize,
+            types: one('array', w),
+            elementTypes: types
+          }
+        : { ...root, path, docCount: root?.docCount ?? input.sampleSize, types }
+    )
+    return
+  }
+  const field: SchemaField = { path, docCount: input.sampleSize, types: info.types }
+  if (info.elementTypes && Object.keys(info.elementTypes).length > 0)
+    field.elementTypes = info.elementTypes
+  out.fields.set(path, field)
+  for (const [key, child] of info.children ?? []) setDerived(out, `${path}.${key}`, child, input)
+}
+
+function derivedShape(input: Shape, fields: readonly [string, ExprInfo][]): Shape {
+  const out = emptyShape(input)
+  for (const [path, info] of fields) setDerived(out, path, info, input)
+  return out
+}
+
+/** Copies the field at `from` and its descendants to `to`; `from === ''` copies every field below `to`. */
+function copySubtree(input: Shape, from: string, to: string, out: Shape): void {
+  for (const [path, field] of input.fields) {
+    let target: string
+    if (from === '') target = `${to}.${path}`
+    else if (path === from) target = to
+    else if (path.startsWith(`${from}.`)) target = to + path.slice(from.length)
+    else continue
+    out.fields.set(target, { ...field, path: target })
+  }
+}
+
+function removeSubtree(shape: Shape, path: string): void {
+  for (const key of [...shape.fields.keys()]) {
+    if (key === path || key.startsWith(`${path}.`)) shape.fields.delete(key)
+  }
+}
+
+/** Adds `path` and its ancestors as objects, which an inclusion projection keeps around included subfields. */
+function ensurePath(out: Shape, input: Shape, path: string): void {
+  if (path === '') return
+  const segments = path.split('.')
+  for (let i = 1; i <= segments.length; i++) {
+    const prefix = segments.slice(0, i).join('.')
+    if (out.fields.has(prefix)) continue
+    const field = lookupField(input, prefix)
+    out.fields.set(
+      prefix,
+      field
+        ? { ...field, path: prefix }
+        : { path: prefix, docCount: input.sampleSize, types: one('object', weight(input)) }
+    )
+  }
+}
+
+function lookupField(shape: Shape, path: string): SchemaField | undefined {
+  return shape.fields.get(path) ?? resolveField(shape.fields, path)
+}
+
+function canonical(shape: Shape, path: string): string {
+  return lookupField(shape, path)?.path ?? path
+}
+
+function isFalsyFlag(node: AstNode): boolean {
+  return (
+    (node.n === 'number' && Number(node.raw) === 0) || (node.n === 'ident' && node.name === 'false')
+  )
+}
+
+function isTruthyFlag(node: AstNode): boolean {
+  return (
+    (node.n === 'number' && Number(node.raw) !== 0) || (node.n === 'ident' && node.name === 'true')
+  )
+}
+
+function isObjectLiteral(node: AstNode): node is ObjectNode {
+  return node.n === 'object' && !node.entries[0]?.key.startsWith('$')
+}
+
+function numberType(raw: string): BsonTypeName {
+  const value = Number(raw)
+  return /[.eE]/.test(raw) || !Number.isInteger(value) || Math.abs(value) > 0x7fffffff
+    ? 'double'
+    : 'int'
+}
+
+function one(type: BsonTypeName, count: number): TypeCounts {
+  const counts: TypeCounts = {}
+  counts[type] = count
+  return counts
+}
+
+function withoutType(counts: TypeCounts, type: BsonTypeName): TypeCounts {
+  const out: TypeCounts = { ...counts }
+  delete out[type]
+  return out
+}
+
+/** Count used for derived types, so a derived field is never typeless. */
+function weight(shape: Shape): number {
+  return Math.max(1, shape.sampleSize)
+}
+
+function toShape(schema: CollectionSchema): Shape {
+  return {
+    sampleSize: schema.sampleSize,
+    truncated: schema.truncated,
+    fields: new Map(schema.fields.map((field) => [field.path, field]))
+  }
+}
+
+function toSchema(shape: Shape): CollectionSchema {
+  return {
+    sampleSize: shape.sampleSize,
+    truncated: shape.truncated,
+    fields: [...shape.fields.values()].sort((a, b) => compareText(a.path, b.path))
+  }
+}
+
+function emptyShape(like: Shape | null): Shape {
+  return {
+    sampleSize: like?.sampleSize ?? 0,
+    truncated: like?.truncated ?? false,
+    fields: new Map()
+  }
+}
+
+function cloneShape(shape: Shape): Shape {
+  return { ...shape, fields: new Map(shape.fields) }
+}
+
+/** Dot path of `key` below `base` ('' = the root). */
+export function join(base: string, key: string): string {
+  return base === '' ? key : `${base}.${key}`
+}
diff --git a/src/renderer/src/lib/completion/scanner.test.ts b/src/renderer/src/lib/completion/scanner.test.ts
new file mode 100644
index 0000000..076ff8a
--- /dev/null
+++ b/src/renderer/src/lib/completion/scanner.test.ts
@@ -0,0 +1,305 @@
+import { describe, expect, it } from 'vitest'
+import { lex, scan, toStages, type Frame } from './scanner'
+
+/** Scans `marked` at its `|` marker. */
+const at = (marked: string, root: 'value' | 'documents' | 'shell' = 'value') => {
+  const offset = marked.indexOf('|')
+  return scan(marked.slice(0, offset) + marked.slice(offset + 1), offset, root)
+}
+
+const shape = (frames: Frame[]) =>
+  frames.map((frame) => {
+    switch (frame.f) {
+      case 'object':
+        return `object:${frame.slot}${frame.key === null ? '' : `:${frame.key}`}`
+      case 'array':
+        return `array:${frame.slot}:${frame.index}`
+      case 'call':
+        return `call:${frame.callee}:${frame.argIndex}`
+      case 'chain':
+        return `chain:${frame.segments.join('.')}${frame.afterDot ? '.' : ''}`
+    }
+  })
+
+describe('lex', () => {
+  it.each(['{ a: "abc', "{ a: 'abc", '{ a: /ab', '{ a: 1 /* note', '"\\', '{ a: "x\\'])(
+    'never throws on %j',
+    (text) => {
+      expect(() => lex(text)).not.toThrow()
+    }
+  )
+
+  it('marks unterminated strings, regexes and comments as open', () => {
+    expect(lex('"abc')[0]).toMatchObject({ t: 'string', closed: false, value: 'abc' })
+    expect(lex('/ab')[0]).toMatchObject({ t: 'regex', closed: false })
+    expect(lex('/* x')[0]).toMatchObject({ t: 'comment', closed: false })
+  })
+
+  it('stops an unterminated string at the newline', () => {
+    const tokens = lex('"ab\n}')
+    expect(tokens[0]).toMatchObject({ t: 'string', closed: false, end: 3 })
+    expect(tokens[1]).toMatchObject({ t: 'punct', v: '}' })
+  })
+
+  it('reads / as a regex after ":" but not after a value', () => {
+    expect(lex('{ a: /x/i }')[3]).toMatchObject({ t: 'regex', closed: true, start: 5, end: 9 })
+    expect(lex('{ a: 1 /x/ }').map((t) => t.t)).not.toContain('regex')
+  })
+
+  it('decodes escapes in strings', () => {
+    expect(lex('"a\\"b\\u0041\\n"')[0]).toMatchObject({ value: 'a"bA\n', closed: true })
+  })
+
+  it('tokenizes shell chains with dots and keeps .5 a number', () => {
+    expect(lex('db.users.find({}).limit(.5);').map((t) => (t.t === 'punct' ? t.v : t.t))).toEqual([
+      'ident',
+      '.',
+      'ident',
+      '.',
+      'ident',
+      '(',
+      '{',
+      '}',
+      ')',
+      '.',
+      'ident',
+      '(',
+      'number',
+      ')',
+      ';'
+    ])
+  })
+})
+
+describe('scan: dead positions', () => {
+  it.each([
+    ['{ a: 1 // co|mment', 'line comment'],
+    ['{ a: 1 // comment|', 'end of a line comment'],
+    ['{ a: /* x| */ 1 }', 'block comment'],
+    ['{ a: /ab|c/ }', 'regex'],
+    ['{ a: /abc/|', 'right after a regex'],
+    ['{ a: 12|', 'number'],
+    ['{ a: "x"|', 'right after a string'],
+    ['{ a: {}|', 'right after a closing brace'],
+    ['{} |', 'after the root value'],
+    ['db.c.find()|', 'right after a call']
+  ])('%s (%s)', (marked) => {
+    expect(at(marked, marked.startsWith('db') ? 'shell' : 'value').dead).toBe(true)
+  })
+
+  it('is alive right after a closed block comment', () => {
+    expect(at('{ /* x */| }').dead).toBe(false)
+  })
+
+  it('treats a huge offset as dead', () => {
+    const text = `{ a: "${'x'.repeat(1_000_100)}" }`
+    expect(scan(text, 1_000_050, 'value').dead).toBe(true)
+  })
+})
+
+describe('scan: token span', () => {
+  it('starts after the opening quote and records the closing quote', () => {
+    const { token } = at('{ "na|" }')
+    expect(token).toMatchObject({ start: 3, cursor: 5, quote: '"', closeQuoteEnd: 6, prefix: 'na' })
+    expect(token.charBefore).toBe(' ')
+  })
+
+  it('has no closing quote for an unterminated string', () => {
+    expect(at('{ "na|').token).toMatchObject({ quote: '"', closeQuoteEnd: null, prefix: 'na' })
+  })
+
+  it('starts an unquoted dotted key at its first segment', () => {
+    const result = at('{ address.ci|')
+    expect(result.token).toMatchObject({ start: 2, prefix: 'address.ci' })
+    expect(shape(result.frames)).toEqual(['object:key'])
+  })
+
+  it('starts a dotted key that ends with a dot', () => {
+    expect(at('{ a.b.|').token.prefix).toBe('a.b.')
+  })
+
+  it('extends the word after the cursor and detects a following colon', () => {
+    const { token } = at('{ na|me: 1 }')
+    expect(token).toMatchObject({
+      start: 2,
+      wordEnd: 6,
+      prefix: 'na',
+      colonFollows: true,
+      nextChar: ':'
+    })
+  })
+
+  it('extends a key over the dotted segments after the cursor', () => {
+    const { token } = at('{ addr|ess.city: 1 }')
+    expect(token).toMatchObject({ wordEnd: 9, dottedEnd: 14, colonFollows: true, nextChar: '.' })
+  })
+
+  it('looks past the closing quote for the colon', () => {
+    expect(at('{ "na|me"  : 1 }').token).toMatchObject({ closeQuoteEnd: 8, colonFollows: true })
+  })
+
+  it('reports the char before the cursor and the last non-blank char', () => {
+    expect(at('{ "_id":|').token).toMatchObject({ charBefore: ':', prevNonBlank: ':', prefix: '' })
+    expect(at('{ "_id": |').token).toMatchObject({ charBefore: ' ', prevNonBlank: ':' })
+  })
+
+  it('takes a lone minus as the start of a word', () => {
+    expect(at('{ a: -|').token).toMatchObject({ start: 5, prefix: '-' })
+  })
+})
+
+describe('scan: frames', () => {
+  it('describes a pipeline stage key after a completed stage', () => {
+    const result = at('[{ $match: { x: 1 } }, { $gr|')
+    expect(shape(result.frames)).toEqual(['array:element:1', 'object:key'])
+    expect(result.token.prefix).toBe('$gr')
+    const pipeline = result.frames[0]
+    expect(pipeline?.f === 'array' && toStages(pipeline.node.items).map((s) => s.name)).toEqual([
+      '$match'
+    ])
+  })
+
+  it('describes a shell call argument', () => {
+    const result = at('db.c.find({}, { na|', 'shell')
+    expect(shape(result.frames)).toEqual(['chain:db.c', 'call:find:1', 'object:key'])
+    const call = result.frames[1]
+    expect(call?.f === 'call' && call.receiver).toEqual(['db', 'c'])
+  })
+
+  it('describes a constructor call', () => {
+    expect(shape(at('new Date(|').frames)).toEqual(['call:Date:0'])
+    expect(shape(at('{ _id: ObjectId("ab|').frames)).toEqual([
+      'object:value:_id',
+      'call:ObjectId:0'
+    ])
+    expect(at('{ _id: ObjectId("ab|').token).toMatchObject({ quote: '"', prefix: 'ab' })
+  })
+
+  it('accepts trailing commas', () => {
+    const result = at('{ a: 1, b: [1, 2,], |')
+    expect(shape(result.frames)).toEqual(['object:key'])
+    const root = result.frames[0]
+    expect(root?.f === 'object' && root.node.entries.map((e) => e.key)).toEqual(['a', 'b'])
+  })
+
+  it('handles CRLF line endings', () => {
+    const result = at('{\r\n  a: 1,\r\n  "b": {\r\n    c|')
+    expect(shape(result.frames)).toEqual(['object:value:b', 'object:key'])
+    expect(result.token.prefix).toBe('c')
+    expect(at('{ a: 1,\r\n  |\r\n}').token.nextChar).toBe('')
+  })
+
+  it('reaches the root slot of an empty or whitespace input', () => {
+    expect(at('|')).toMatchObject({ frames: [], dead: false })
+    expect(at('  tr|')).toMatchObject({ frames: [], dead: false })
+  })
+
+  it('continues a document sequence', () => {
+    expect(shape(at('{ a: 1 }, { |', 'documents').frames)).toEqual(['object:key'])
+    expect(at('{ a: 1 } |', 'documents')).toMatchObject({ frames: [], dead: false })
+  })
+
+  it('closes a mismatched bracket at the enclosing container', () => {
+    const result = at('{ a: { b: [1, 2 }, c: { |')
+    expect(shape(result.frames)).toEqual(['object:value:c', 'object:key'])
+  })
+
+  it('keeps the value slot after "new"', () => {
+    expect(shape(at('{ a: new |').frames)).toEqual(['object:value:a'])
+  })
+
+  it('tracks object keys while the cursor is in a later value', () => {
+    const result = at('[{ $lookup: { from: "orders", foreignField: "|')
+    const body = result.frames[2]
+    expect(
+      body?.f === 'object' && body.node.entries.map((e) => [e.key, e.value?.n ?? null])
+    ).toEqual([
+      ['from', 'string'],
+      ['foreignField', null]
+    ])
+  })
+})
+
+describe('scan: entries after the cursor', () => {
+  const keysOf = (frame: Frame | undefined) =>
+    frame?.f === 'object' ? frame.node.entries.map((e) => e.key) : null
+
+  it('adds the keys that follow the cursor to its object', () => {
+    expect(keysOf(at('{ a: 1, |, name: "x", "age": 2 }').frames[0])).toEqual(['a', 'name', 'age'])
+  })
+
+  it('finds following keys without a separating comma', () => {
+    const result = at('{ "|"\n  "_id": ObjectId("x"), "address": { "city": "B" } }', 'documents')
+    expect(keysOf(result.frames[0])).toEqual(['_id', 'address'])
+  })
+
+  it('completes every open object on the way out', () => {
+    const result = at(
+      '[{ $lookup: { pipeline: [{ $match: { | } }], from: "orders", let: { pid: "$uuid" } } }]'
+    )
+    const body = result.frames[2]
+    expect(keysOf(body)).toEqual(['pipeline', 'from', 'let'])
+    const from = body?.f === 'object' ? body.node.entries[1]?.value : null
+    expect(from).toMatchObject({ n: 'string', value: 'orders' })
+    const vars = body?.f === 'object' ? body.node.entries[2]?.value : null
+    expect(vars?.n === 'object' && vars.entries.map((e) => e.key)).toEqual(['pid'])
+  })
+
+  it('notes whether another element follows the cursor in an array', () => {
+    const more = (marked: string) => {
+      const frame = at(marked).frames[0]
+      return frame?.f === 'array' && frame.more
+    }
+    expect(more('[{ a: 1 }, { | }, { b: 2 }]')).toBe(true)
+    expect(more('[|, 2]')).toBe(true)
+    expect(more('[{ a: 1 }, { | }]')).toBe(false)
+    expect(more('[1, |, ]')).toBe(false)
+    expect(more('[{ x: [1, 2] }, { $| }')).toBe(false)
+  })
+
+  it('leaves the word at the cursor and values after it out', () => {
+    expect(keysOf(at('{ na|me: 1, other: "x" }').frames[0])).toEqual(['other'])
+    expect(keysOf(at('{ addr|ess.city: 1, other: 2 }').frames[0])).toEqual(['other'])
+    expect(keysOf(at('{ items|.0.name: 1, other: 2 }').frames[0])).toEqual(['other'])
+    expect(keysOf(at('{ a: Obj|ectId("x"), b: [1, 2], c: 3 }').frames[0])).toEqual(['a', 'b', 'c'])
+  })
+})
+
+describe('scan: shell chains', () => {
+  it.each([
+    ['|', ['chain:']],
+    ['d|', ['chain:']],
+    ['db.|', ['chain:db.']],
+    ['db.us|', ['chain:db.']],
+    ['db.users.|', ['chain:db.users.']],
+    ['db.a.b.|', ['chain:db.a.b.']],
+    ['db.users.find({}).|', ['chain:db.users.']],
+    ['db["my coll"].|', ['chain:db.my coll.']],
+    ['db.getCollection("x").|', ['chain:db.x.']],
+    ['db.getCollection("|', ['chain:db', 'call:getCollection:0']],
+    ['db["|', ['chain:db', 'call:getCollection:0']]
+  ])('%s', (marked, expected) => {
+    expect(shape(at(marked, 'shell').frames)).toEqual(expected)
+  })
+
+  it('records completed calls in order', () => {
+    const chain = at('db.users.find({}).limit(5).|', 'shell').frames[0]
+    expect(chain?.f === 'chain' && chain.calls.map((c) => c.name)).toEqual(['find', 'limit'])
+  })
+
+  it('is dead after a terminating semicolon', () => {
+    expect(at('db.users.find({}); |', 'shell').dead).toBe(true)
+  })
+})
+
+describe('scan: key styles', () => {
+  it('detects quoted and unquoted keys across the whole text', () => {
+    expect(at('{ "a": 1, | }')).toMatchObject({ quotedKeys: true, unquotedKeys: false })
+    expect(at('{ |, b: 1 }')).toMatchObject({ quotedKeys: false, unquotedKeys: true })
+    expect(at('{ "a": { $gt: 1 }, | }')).toMatchObject({ quotedKeys: true, unquotedKeys: true })
+  })
+
+  it('ignores the key being typed', () => {
+    expect(at('{ "a": 1, na|: 2 }')).toMatchObject({ quotedKeys: true, unquotedKeys: false })
+  })
+})
diff --git a/src/renderer/src/lib/completion/scanner.ts b/src/renderer/src/lib/completion/scanner.ts
new file mode 100644
index 0000000..2c98608
--- /dev/null
+++ b/src/renderer/src/lib/completion/scanner.ts
@@ -0,0 +1,784 @@
+/**
+ * Tolerant lexer and prefix parser for completion. Accepts the `mongoQueryLang` surface
+ * plus shell chains, never throws, and describes where the cursor sits: the open
+ * containers from the root to the cursor (frames) and the partial word at the cursor.
+ */
+
+export type Punct = '{' | '}' | '[' | ']' | '(' | ')' | ':' | ',' | '.' | ';'
+
+export type Token =
+  | { t: 'punct'; v: Punct; start: number; end: number }
+  | { t: 'string'; quote: '"' | "'"; value: string; closed: boolean; start: number; end: number }
+  | { t: 'number'; raw: string; start: number; end: number }
+  | { t: 'regex'; closed: boolean; start: number; end: number }
+  | { t: 'ident'; v: string; start: number; end: number }
+  | { t: 'comment'; closed: boolean; start: number; end: number }
+  | { t: 'unknown'; start: number; end: number }
+
+export type ObjectNode = { n: 'object'; entries: AstEntry[] }
+export type ArrayNode = { n: 'array'; items: AstNode[] }
+export type CallNode = { n: 'call'; callee: string; args: AstNode[] }
+export type AstNode =
+  | ObjectNode
+  | ArrayNode
+  | CallNode
+  | { n: 'string'; value: string }
+  | { n: 'number'; raw: string }
+  | { n: 'regex' }
+  /** true / false / null / MinKey / any other bare word. */
+  | { n: 'ident'; name: string }
+export type AstEntry = { key: string; value: AstNode | null }
+export type StageAst = { name: string; body: AstNode | null }
+
+export type Frame =
+  | {
+      f: 'object'
+      node: ObjectNode
+      slot: 'key' | 'afterKey' | 'value' | 'afterValue'
+      key: string | null
+    }
+  | {
+      f: 'array'
+      node: ArrayNode
+      slot: 'element' | 'afterElement'
+      index: number
+      /** Another element follows the cursor's one. */
+      more: boolean
+    }
+  | {
+      f: 'call'
+      callee: string
+      /** Chain segments the method is called on (`['db', 'users']`); empty for constructors. */
+      receiver: readonly string[]
+      argIndex: number
+      slot: 'arg' | 'afterArg'
+      args: AstNode[]
+    }
+  | {
+      f: 'chain'
+      /** `db` plus the collection-name segments. */
+      segments: string[]
+      calls: { name: string; args: AstNode[] }[]
+      afterDot: boolean
+    }
+
+export type TokenSpan = {
+  /** First char of the partial word; after the opening quote when inside a string. */
+  start: number
+  cursor: number
+  /** End of the word characters after the cursor on the same line. */
+  wordEnd: number
+  /** `wordEnd` extended over `.segment`s, the end of an unquoted dotted key; `wordEnd` inside quotes. */
+  dottedEnd: number
+  quote: '"' | "'" | null
+  /** Offset after the closing quote on the cursor line, if the string has one. */
+  closeQuoteEnd: number | null
+  /** The next non-blank char after the dotted word (or closing quote) is ':'. */
+  colonFollows: boolean
+  /** Next non-blank char on the cursor line after the word (or closing quote); '' at line end. */
+  nextChar: string
+  /** Char before `start`, or before the opening quote. */
+  charBefore: string
+  /** Last non-whitespace char before `start` (or the opening quote), across lines. */
+  prevNonBlank: string
+  prefix: string
+}
+
+export type ScanResult = {
+  frames: Frame[]
+  /** The cursor is in a comment, regex or number, right after a complete value, or after the input's grammar ended. */
+  dead: boolean
+  token: TokenSpan
+  quotedKeys: boolean
+  unquotedKeys: boolean
+}
+
+const MAX_SCAN_OFFSET = 1_000_000
+const PUNCT = '{}[]():,.;'
+const REGEX_AFTER = new Set<string>([':', ',', '[', '('])
+const NUMBER_RE = /[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/y
+const IDENT_RE = /[A-Za-z_$][\w$]*/y
+const WORD_CHAR = /[\w$]/
+const DOTTED_TAIL = /^(?:\.[A-Za-z_$][\w$]*)+/
+
+/**
+ * Tokenizes `text` like `mongoQueryLang`, plus `.` and `;`; unterminated strings, regexes and comments end the token.
+ * @returns tokens in source order, comments included; never throws
+ */
+export function lex(text: string): Token[] {
+  const out: Token[] = []
+  const n = text.length
+  let regexAllowed = true
+  let i = 0
+  while (i < n) {
+    const c = text[i]!
+    if (/\s/.test(c)) {
+      i++
+      continue
+    }
+    if (c === '/' && text[i + 1] === '/') {
+      const start = i
+      while (i < n && text[i] !== '\n') i++
+      out.push({ t: 'comment', closed: true, start, end: i })
+      continue
+    }
+    if (c === '/' && text[i + 1] === '*') {
+      const start = i
+      const close = text.indexOf('*/', i + 2)
+      i = close === -1 ? n : close + 2
+      out.push({ t: 'comment', closed: close !== -1, start, end: i })
+      continue
+    }
+    if (c === '"' || c === "'") {
+      const token = lexString(text, i, c)
+      out.push(token)
+      i = token.end
+      regexAllowed = false
+      continue
+    }
+    if (c === '/' && regexAllowed) {
+      const token = lexRegex(text, i)
+      out.push(token)
+      i = token.end
+      regexAllowed = false
+      continue
+    }
+    if ((c >= '0' && c <= '9') || c === '.' || c === '-' || c === '+') {
+      NUMBER_RE.lastIndex = i
+      const m = NUMBER_RE.exec(text)
+      if (m && /\d/.test(m[0])) {
+        out.push({ t: 'number', raw: m[0], start: i, end: i + m[0].length })
+        i += m[0].length
+        regexAllowed = false
+        continue
+      }
+    }
+    if (PUNCT.includes(c)) {
+      out.push({ t: 'punct', v: c as Punct, start: i, end: i + 1 })
+      regexAllowed = REGEX_AFTER.has(c)
+      i++
+      continue
+    }
+    IDENT_RE.lastIndex = i
+    const ident = IDENT_RE.exec(text)
+    if (ident) {
+      out.push({ t: 'ident', v: ident[0], start: i, end: i + ident[0].length })
+      i += ident[0].length
+      regexAllowed = false
+      continue
+    }
+    out.push({ t: 'unknown', start: i, end: i + 1 })
+    regexAllowed = false
+    i++
+  }
+  return out
+}
+
+function lexString(text: string, start: number, quote: '"' | "'"): Token {
+  let value = ''
+  let i = start + 1
+  while (i < text.length) {
+    const ch = text[i]!
+    if (ch === quote) return { t: 'string', quote, value, closed: true, start, end: i + 1 }
+    if (ch === '\n') break
+    if (ch === '\\') {
+      const escaped = text[i + 1]
+      if (escaped === undefined) {
+        i++
+        break
+      }
+      const hex = text.slice(i + 2, i + 6)
+      if (escaped === 'u' && /^[0-9a-fA-F]{4}$/.test(hex)) {
+        value += String.fromCharCode(parseInt(hex, 16))
+        i += 6
+        continue
+      }
+      value += ESCAPES[escaped] ?? escaped
+      i += 2
+      continue
+    }
+    value += ch
+    i++
+  }
+  return { t: 'string', quote, value, closed: false, start, end: i }
+}
+
+const ESCAPES: Record<string, string> = { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', '0': '\0' }
+
+function lexRegex(text: string, start: number): Token {
+  let i = start + 1
+  let inClass = false
+  let closed = false
+  while (i < text.length) {
+    const ch = text[i]!
+    if (ch === '\\' && i + 1 < text.length) {
+      i += 2
+      continue
+    }
+    if (ch === '\n') break
+    if (ch === '[') inClass = true
+    else if (ch === ']') inClass = false
+    else if (ch === '/' && !inClass) {
+      closed = true
+      i++
+      break
+    }
+    i++
+  }
+  if (closed) while (i < text.length && /[gimsuy]/.test(text[i]!)) i++
+  return { t: 'regex', closed, start, end: i }
+}
+
+/**
+ * Parses `text` up to `offset` tolerantly; `root` selects value, document-sequence or shell-chain grammar.
+ * @param offset cursor offset into `text`
+ * @returns the open frames at the cursor (empty = at the root slot), their objects completed with the entries after the cursor, and the partial token there
+ */
+export function scan(
+  text: string,
+  offset: number,
+  root: 'value' | 'documents' | 'shell'
+): ScanResult {
+  const cursor = Math.max(0, Math.min(offset, text.length))
+  if (cursor > MAX_SCAN_OFFSET) {
+    return {
+      frames: [],
+      dead: true,
+      token: span(text, cursor, cursor, null),
+      quotedKeys: false,
+      unquotedKeys: false
+    }
+  }
+  const tokens = lex(text)
+  let cut = tokens.findIndex((token) => token.start >= cursor)
+  if (cut === -1) cut = tokens.length
+  const prev = tokens[cut - 1]
+  let parseEnd = cut
+  let start = cursor
+  let quoted: Extract<Token, { t: 'string' }> | null = null
+  let dead = false
+  if (prev && prev.end >= cursor) {
+    switch (prev.t) {
+      case 'ident':
+        parseEnd = cut - 1
+        start = prev.start
+        break
+      case 'string':
+        if (cursor < prev.end || !prev.closed) {
+          parseEnd = cut - 1
+          quoted = prev
+          start = prev.start + 1
+        } else dead = true
+        break
+      case 'comment':
+        dead = cursor < prev.end || !prev.closed || text.startsWith('//', prev.start)
+        break
+      case 'number':
+      case 'regex':
+        dead = true
+        break
+      case 'punct':
+        dead = prev.v === '}' || prev.v === ']' || prev.v === ')'
+        break
+      case 'unknown':
+        // A lone `-` starts a negative number (`-1` in a sort spec).
+        if (text[prev.start] === '-') {
+          parseEnd = cut - 1
+          start = prev.start
+        }
+        break
+    }
+  }
+
+  let frames: Frame[] = []
+  if (!dead) {
+    const parser = new PrefixParser(
+      tokens.slice(0, parseEnd).filter((token) => token.t !== 'comment'),
+      quoted ? -1 : start
+    )
+    if (parser.run(root)) {
+      frames = parser.frames
+      if (parser.dottedStart !== null) start = parser.dottedStart
+      // The dotted tail of a word at the cursor (`addr|ess.city`) still belongs to that word.
+      const restStart = prev?.t === 'ident' && parseEnd < cut ? skipDottedTail(tokens, cut) : cut
+      const rest = tokens.slice(restStart).filter((token) => token.t !== 'comment')
+      new PrefixParser(rest, -1).completeObjects(frames)
+    } else dead = true
+  }
+  const keyStyles = detectKeyStyles(tokens, parseEnd < cut ? cut - 1 : -1)
+  return { frames, dead, token: span(text, start, cursor, quoted), ...keyStyles }
+}
+
+/**
+ * Stage list of a pipeline array's items; non-object and empty items are skipped.
+ * @returns one entry per stage object, named by its first key
+ */
+export function toStages(items: readonly AstNode[]): StageAst[] {
+  const stages: StageAst[] = []
+  for (const item of items) {
+    if (item.n !== 'object') continue
+    const first = item.entries[0]
+    if (first) stages.push({ name: first.key, body: first.value })
+  }
+  return stages
+}
+
+/**
+ * Value of the last entry named `key` of an object node.
+ * @returns undefined when `node` is not an object or has no such entry; null for an entry without value
+ */
+export function entryValue(
+  node: AstNode | null | undefined,
+  key: string
+): AstNode | null | undefined {
+  if (node?.n !== 'object') return undefined
+  for (let i = node.entries.length - 1; i >= 0; i--) {
+    const entry = node.entries[i]!
+    if (entry.key === key) return entry.value
+  }
+  return undefined
+}
+
+/**
+ * String content of a string node.
+ * @returns null for any other node
+ */
+export function stringValue(node: AstNode | null | undefined): string | null {
+  return node?.n === 'string' ? node.value : null
+}
+
+function span(
+  text: string,
+  start: number,
+  cursor: number,
+  quoted: Extract<Token, { t: 'string' }> | null
+): TokenSpan {
+  const newline = text.indexOf('\n', cursor)
+  const lineEnd = newline === -1 ? text.length : newline
+  let wordEnd = cursor
+  while (wordEnd < lineEnd && WORD_CHAR.test(text[wordEnd]!)) wordEnd++
+  const dotted = quoted ? null : DOTTED_TAIL.exec(text.slice(wordEnd, lineEnd))
+  const dottedEnd = wordEnd + (dotted?.[0].length ?? 0)
+  const closeQuoteEnd = quoted?.closed && quoted.end <= lineEnd ? quoted.end : null
+  const outer = quoted ? quoted.start : start
+  let before = outer - 1
+  while (before >= 0 && /\s/.test(text[before]!)) before--
+  return {
+    start,
+    cursor,
+    wordEnd,
+    dottedEnd,
+    quote: quoted?.quote ?? null,
+    closeQuoteEnd,
+    colonFollows: nextNonBlank(text, closeQuoteEnd ?? dottedEnd, lineEnd) === ':',
+    nextChar: nextNonBlank(text, closeQuoteEnd ?? wordEnd, lineEnd),
+    charBefore: outer > 0 ? text[outer - 1]! : '',
+    prevNonBlank: before >= 0 ? text[before]! : '',
+    prefix: text.slice(start, cursor)
+  }
+}
+
+/** Index after the `.segment`s from `i` on that directly continue the token before `i`. */
+function skipDottedTail(tokens: readonly Token[], i: number): number {
+  for (;;) {
+    const before = tokens[i - 1]
+    const next = tokens[i]
+    if (!before || !next || next.start !== before.end) return i
+    // `.0` lexes as one number token.
+    if (next.t === 'number' && /^\.\d+$/.test(next.raw)) {
+      i++
+      continue
+    }
+    const segment = tokens[i + 1]
+    if (!isPunct(next, '.') || segment?.t !== 'ident' || segment.start !== next.end) return i
+    i += 2
+  }
+}
+
+function nextNonBlank(text: string, from: number, lineEnd: number): string {
+  let i = from
+  while (i < lineEnd && /[ \t\r]/.test(text[i]!)) i++
+  return i < lineEnd ? text[i]! : ''
+}
+
+function detectKeyStyles(
+  tokens: readonly Token[],
+  cursorToken: number
+): { quotedKeys: boolean; unquotedKeys: boolean } {
+  let quotedKeys = false
+  let unquotedKeys = false
+  const significant = tokens.filter((token, i) => token.t !== 'comment' && i !== cursorToken)
+  for (let i = 0; i + 1 < significant.length; i++) {
+    const next = significant[i + 1]!
+    if (next.t !== 'punct' || next.v !== ':') continue
+    const token = significant[i]!
+    if (token.t === 'string') quotedKeys = true
+    else if (token.t === 'ident') unquotedKeys = true
+  }
+  return { quotedKeys, unquotedKeys }
+}
+
+/** Thrown when the parser runs out of tokens, i.e. reaches the cursor. */
+const CURSOR = { reached: true } as const
+
+class PrefixParser {
+  readonly frames: Frame[] = []
+  /** Start of an unquoted dotted key (`address.ci|`) that ends at the cursor. */
+  dottedStart: number | null = null
+  private pos = 0
+
+  constructor(
+    private readonly tokens: readonly Token[],
+    private readonly partialStart: number
+  ) {}
+
+  /** True when the cursor was reached inside the grammar; false when the input ended before it. */
+  run(root: 'value' | 'documents' | 'shell'): boolean {
+    try {
+      if (root === 'value') this.parseValue()
+      else if (root === 'documents') this.parseDocuments()
+      else this.parseChain()
+      return false
+    } catch (e) {
+      if (e === CURSOR) return true
+      throw e
+    }
+  }
+
+  /** Appends the entries after the cursor (this parser's tokens) to each open object of `frames` and marks open arrays with elements after it. */
+  completeObjects(frames: readonly Frame[]): void {
+    let level = frames.length - 1
+    let depth = 0
+    try {
+      for (;;) {
+        const frame = frames[level]
+        if (!frame || frame.f === 'chain') return
+        const token = this.need()
+        // Keys are found by their colon, so a key typed above others without a comma still sees them.
+        if (depth === 0 && frame.f === 'object' && isKeyToken(token)) {
+          const entry = this.parseKey()
+          if (isPunct(this.need(), ':')) {
+            this.advance()
+            frame.node.entries.push(entry)
+            entry.value = this.parseValue()
+          }
+          continue
+        }
+        this.advance()
+        if (token.t !== 'punct') continue
+        if (depth === 0 && frame.f === 'array' && token.v === ',') {
+          const next = this.peek()
+          if (next && !isPunct(next, ']')) frame.more = true
+        } else if (token.v === '{' || token.v === '[' || token.v === '(') depth++
+        else if (token.v === '}' || token.v === ']' || token.v === ')') {
+          if (depth > 0) depth--
+          else level--
+        }
+      }
+    } catch (e) {
+      if (e !== CURSOR) throw e
+    }
+  }
+
+  private peek(): Token | undefined {
+    return this.tokens[this.pos]
+  }
+
+  private need(): Token {
+    const token = this.tokens[this.pos]
+    if (!token) throw CURSOR
+    return token
+  }
+
+  private advance(): Token {
+    return this.tokens[this.pos++]!
+  }
+
+  private parseDocuments(): void {
+    for (;;) {
+      const token = this.need()
+      if (isPunct(token, ',')) {
+        this.advance()
+        continue
+      }
+      const before = this.pos
+      this.parseValue()
+      if (this.pos === before) this.advance()
+    }
+  }
+
+  private parseValue(): AstNode | null {
+    const token = this.need()
+    switch (token.t) {
+      case 'punct':
+        if (token.v === '{') return this.parseObject()
+        if (token.v === '[') return this.parseArray()
+        // Separators and closers belong to the enclosing container.
+        if (token.v === ',' || token.v === '}' || token.v === ']' || token.v === ')') return null
+        this.advance()
+        return null
+      case 'string':
+        this.advance()
+        return { n: 'string', value: token.value }
+      case 'number':
+        this.advance()
+        return { n: 'number', raw: token.raw }
+      case 'regex':
+        this.advance()
+        return { n: 'regex' }
+      case 'ident':
+        return this.parseIdentValue()
+      default:
+        this.advance()
+        return null
+    }
+  }
+
+  private parseIdentValue(): AstNode {
+    let token = this.advance() as Extract<Token, { t: 'ident' }>
+    if (token.v === 'new') {
+      const next = this.need()
+      if (next.t !== 'ident') return { n: 'ident', name: 'new' }
+      token = this.advance() as Extract<Token, { t: 'ident' }>
+    }
+    const next = this.peek()
+    if (next && isPunct(next, '(')) return this.parseCall(token.v, [])
+    return { n: 'ident', name: token.v }
+  }
+
+  private parseCall(callee: string, receiver: readonly string[]): CallNode {
+    this.advance()
+    const node: CallNode = { n: 'call', callee, args: [] }
+    const frame: Extract<Frame, { f: 'call' }> = {
+      f: 'call',
+      callee,
+      receiver,
+      argIndex: 0,
+      slot: 'arg',
+      args: node.args
+    }
+    this.parseItems(frame, ')', node.args, (index, after) => {
+      frame.argIndex = index
+      frame.slot = after ? 'afterArg' : 'arg'
+    })
+    return node
+  }
+
+  private parseArray(): ArrayNode {
+    this.advance()
+    const node: ArrayNode = { n: 'array', items: [] }
+    const frame: Extract<Frame, { f: 'array' }> = {
+      f: 'array',
+      node,
+      slot: 'element',
+      index: 0,
+      more: false
+    }
+    this.parseItems(frame, ']', node.items, (index, after) => {
+      frame.index = index
+      frame.slot = after ? 'afterElement' : 'element'
+    })
+    return node
+  }
+
+  /** Reads comma-separated values into `items` up to `close`; `slot` records the cursor's item index and whether it is past that item. */
+  private parseItems(
+    frame: Frame,
+    close: Punct,
+    items: AstNode[],
+    slot: (index: number, after: boolean) => void
+  ): void {
+    this.frames.push(frame)
+    let index = 0
+    let after = false
+    for (;;) {
+      const token = this.need()
+      if (this.leaveAt(token, close)) return
+      // A comma, or a value written without one, starts the next item.
+      if (after || isPunct(token, ',')) {
+        index++
+        after = false
+        slot(index, false)
+        if (isPunct(token, ',')) {
+          this.advance()
+          continue
+        }
+      }
+      const value = this.parseValue()
+      if (value) items.push(value)
+      after = true
+      slot(index, true)
+    }
+  }
+
+  /** Pops the innermost frame at a closing bracket; only `close` is consumed, any other closes an enclosing container. */
+  private leaveAt(token: Token, close: Punct): boolean {
+    if (token.t !== 'punct' || (token.v !== '}' && token.v !== ']' && token.v !== ')')) return false
+    if (token.v === close) this.advance()
+    this.frames.pop()
+    return true
+  }
+
+  private parseObject(): ObjectNode {
+    this.advance()
+    const node: ObjectNode = { n: 'object', entries: [] }
+    const frame: Extract<Frame, { f: 'object' }> = { f: 'object', node, slot: 'key', key: null }
+    this.frames.push(frame)
+    let entry: AstEntry | null = null
+    for (;;) {
+      const token = this.need()
+      if (this.leaveAt(token, '}')) return node
+      switch (frame.slot) {
+        case 'key':
+          if (isPunct(token, ',')) this.advance()
+          else if (token.t === 'string' || token.t === 'ident' || token.t === 'number') {
+            entry = this.parseKey()
+            node.entries.push(entry)
+            frame.key = entry.key
+            frame.slot = 'afterKey'
+          } else if (isPunct(token, '{') || isPunct(token, '[')) {
+            this.parseValue()
+            frame.slot = 'afterValue'
+          } else this.advance()
+          break
+        case 'afterKey':
+          if (isPunct(token, ':')) {
+            this.advance()
+            frame.slot = 'value'
+          } else if (isPunct(token, ',')) {
+            this.advance()
+            frame.slot = 'key'
+            frame.key = null
+          } else frame.slot = 'value'
+          break
+        case 'value': {
+          if (isPunct(token, ',')) {
+            this.advance()
+            frame.slot = 'key'
+            frame.key = null
+            break
+          }
+          const value = this.parseValue()
+          if (entry) entry.value = value
+          frame.slot = 'afterValue'
+          break
+        }
+        case 'afterValue':
+          if (isPunct(token, ',')) this.advance()
+          frame.slot = 'key'
+          frame.key = null
+          break
+      }
+    }
+  }
+
+  /** Reads a key; an unquoted dotted key running into the cursor stops the parse as a partial key. */
+  private parseKey(): AstEntry {
+    const first = this.advance()
+    if (first.t === 'string') return { key: first.value, value: null }
+    let key = first.t === 'ident' ? first.v : first.t === 'number' ? first.raw : ''
+    let end = first.end
+    if (first.t === 'ident') {
+      for (;;) {
+        const next = this.peek()
+        if (next?.t === 'number' && next.start === end && /^\.\d+$/.test(next.raw)) {
+          this.advance()
+          key += next.raw
+          end = next.end
+          continue
+        }
+        if (!next || !isPunct(next, '.') || next.start !== end) break
+        this.advance()
+        end = next.end
+        const segment = this.peek()
+        if (!segment) {
+          if (end === this.partialStart) {
+            this.dottedStart = first.start
+            throw CURSOR
+          }
+          break
+        }
+        if (segment.t !== 'ident' || segment.start !== end) break
+        this.advance()
+        key += `.${segment.v}`
+        end = segment.end
+      }
+    }
+    return { key, value: null }
+  }
+
+  /** `db (. name)* . method(args) (. method(args))* ;?` plus `db["name"]` and `db.getCollection("name")`. */
+  private parseChain(): void {
+    const frame: Extract<Frame, { f: 'chain' }> = {
+      f: 'chain',
+      segments: [],
+      calls: [],
+      afterDot: false
+    }
+    this.frames.push(frame)
+    const head = this.need()
+    if (head.t !== 'ident') return
+    this.advance()
+    frame.segments.push(head.v)
+    for (;;) {
+      const token = this.need()
+      if (isPunct(token, '.')) {
+        this.advance()
+        frame.afterDot = true
+        const name = this.need()
+        if (name.t !== 'ident') return
+        this.advance()
+        frame.afterDot = false
+        const open = this.peek()
+        if (open && isPunct(open, '(')) {
+          const call = this.parseCall(name.v, [...frame.segments])
+          const target = stringValue(call.args[0])
+          if (
+            name.v === 'getCollection' &&
+            frame.calls.length === 0 &&
+            frame.segments.length === 1 &&
+            target !== null
+          ) {
+            frame.segments.push(target)
+          } else frame.calls.push({ name: name.v, args: call.args })
+        } else if (frame.calls.length === 0) frame.segments.push(name.v)
+        continue
+      }
+      if (isPunct(token, '[') && frame.calls.length === 0) {
+        this.parseBracketAccess(frame)
+        continue
+      }
+      if (isPunct(token, ';')) this.advance()
+      return
+    }
+  }
+
+  /** `db["name"]` behaves like `db.getCollection("name")`. */
+  private parseBracketAccess(chain: Extract<Frame, { f: 'chain' }>): void {
+    this.advance()
+    const frame: Extract<Frame, { f: 'call' }> = {
+      f: 'call',
+      callee: 'getCollection',
+      receiver: [...chain.segments],
+      argIndex: 0,
+      slot: 'arg',
+      args: []
+    }
+    this.frames.push(frame)
+    const value = this.parseValue()
+    if (value) frame.args.push(value)
+    frame.slot = 'afterArg'
+    if (isPunct(this.need(), ']')) this.advance()
+    this.frames.pop()
+    const target = stringValue(value)
+    if (target !== null) chain.segments.push(target)
+  }
+}
+
+function isPunct(token: Token, value: Punct): boolean {
+  return token.t === 'punct' && token.v === value
+}
+
+function isKeyToken(token: Token): boolean {
+  return token.t === 'string' || token.t === 'ident' || token.t === 'number'
+}
diff --git a/src/renderer/src/lib/completion/suggest.test.ts b/src/renderer/src/lib/completion/suggest.test.ts
new file mode 100644
index 0000000..37655ae
--- /dev/null
+++ b/src/renderer/src/lib/completion/suggest.test.ts
@@ -0,0 +1,1060 @@
+import { describe, expect, it } from 'vitest'
+import { createSchemaBuilder } from '@shared/collectionSchema'
+import { WRITE_METHODS, type CollectionSchema } from '@shared/types'
+import { BULK_WRITE_OPERATIONS, UPDATE_PIPELINE_STAGES, WRITE_OPTIONS } from '@shared/writeOps'
+import {
+  SHELL_AGGREGATE_CURSOR_METHODS,
+  SHELL_COLLECTION_METHODS,
+  SHELL_CURSOR_METHODS,
+  shellCollectionAccessor
+} from '../shellParser'
+import { analyzeContext, type EditorKind } from './context'
+import {
+  suggest,
+  type SuggestEnv,
+  type SuggestResult,
+  type SuggestTrigger,
+  type Suggestion
+} from './suggest'
+
+const NOW = new Date('2024-01-15T12:00:00.000Z')
+
+const schemaOf = (...docs: unknown[]): CollectionSchema => {
+  const builder = createSchemaBuilder()
+  for (const doc of docs) builder.add(doc)
+  return builder.build()
+}
+
+const oid = (n: number) => ({ $oid: `507f1f77bcf86cd7994390${String(n).padStart(2, '0')}` })
+const scores = Object.fromEntries(
+  Array.from({ length: 70 }, (_, i) => [`k${i}z`, { $numberInt: '1' }])
+)
+
+const users = schemaOf(
+  ...Array.from({ length: 6 }, (_, i) => ({
+    _id: oid(i),
+    name: `user${i}`,
+    status: i < 4 ? 'active' : 'inactive',
+    age: { $numberInt: String(20 + i) },
+    createdAt: { $date: { $numberLong: String(1704067200000 + i) } },
+    uid: { $binary: { base64: 'VQ6EAOKbQdSnFkRmVUQAAA==', subType: '04' } },
+    legacy: { $binary: { base64: 'VQ6EAOKbQdSnFkRmVUQAAA==', subType: '03' } },
+    big: { $numberLong: '9007199254740993' },
+    ids: [oid(10), oid(11)],
+    tags: ['a', 'b'],
+    address: { city: 'Berlin', zip: '10115' },
+    note: 'price $5',
+    flag: i % 3 !== 0,
+    scores
+  }))
+)
+const orders = schemaOf({ _id: oid(20), userId: oid(1), total: { $numberDouble: '9.5' } })
+const places = schemaOf({
+  _id: oid(30),
+  items: [{ sku: 'a', qty: { $numberInt: '1' } }],
+  loc: { type: 'Point', coordinates: [{ $numberDouble: '13.4' }, { $numberDouble: '52.5' }] }
+})
+
+const makeEnv = (overrides: Partial<SuggestEnv> = {}): SuggestEnv => ({
+  coll: 'users',
+  collections: ['users', 'orders', 'my logs'],
+  schemaOf: (coll) => ({ users, orders, places })[coll] ?? null,
+  uuidEncoding: 'default',
+  timezone: 'UTC',
+  now: NOW,
+  shellMethods: SHELL_COLLECTION_METHODS,
+  cursorMethods: SHELL_CURSOR_METHODS,
+  aggregateCursorMethods: SHELL_AGGREGATE_CURSOR_METHODS,
+  collectionAccessor: shellCollectionAccessor,
+  ...overrides
+})
+
+const INVOKE: SuggestTrigger = { kind: 'invoke' }
+
+/** Suggestions at the `|` marker of `marked`. */
+const run = (
+  marked: string,
+  kind: EditorKind = 'filter',
+  options: { env?: Partial<SuggestEnv>; trigger?: SuggestTrigger } = {}
+): SuggestResult => {
+  const offset = marked.indexOf('|')
+  const env = makeEnv(options.env)
+  const ctx = analyzeContext(
+    marked.slice(0, offset) + marked.slice(offset + 1),
+    offset,
+    kind,
+    env.coll
+  )
+  return suggest(ctx, env, options.trigger ?? INVOKE)
+}
+
+const ordered = (result: SuggestResult): Suggestion[] =>
+  [...result.items].sort((a, b) => (a.sortText < b.sortText ? -1 : 1))
+const labels = (result: SuggestResult): string[] => ordered(result).map((item) => item.label)
+const item = (result: SuggestResult, label: string): Suggestion | undefined =>
+  result.items.find((i) => i.label === label)
+const preselected = (result: SuggestResult): Suggestion[] => result.items.filter((i) => i.preselect)
+const char = (c: string): SuggestTrigger => ({ kind: 'character', char: c })
+
+describe('suggest: value model', () => {
+  it('preselects ObjectId for an objectId field and spaces after a bare colon', () => {
+    const result = run('{ "_id":|')
+    const [first] = ordered(result)
+    expect(first).toMatchObject({ insertText: ' ObjectId("$0")', snippet: true, preselect: true })
+    expect(first?.description).toBe('objectId · 100%')
+    expect(preselected(result)).toHaveLength(1)
+    expect(ordered(run('{ "_id": |'))[0]?.insertText).toBe('ObjectId("$0")')
+  })
+
+  it('defaults ISODate to now in the connection timezone', () => {
+    const [first] = ordered(run('{ createdAt: |', 'filter', { env: { timezone: 'Europe/Berlin' } }))
+    expect(first?.insertText).toBe('ISODate("${0:2024-01-15T13:00:00.000+01:00}")')
+  })
+
+  it('picks UUID, JUUID / BinData(3) and NumberLong by type', () => {
+    expect(ordered(run('{ uid: |'))[0]?.insertText).toBe('UUID("$0")')
+    expect(
+      ordered(run('{ legacy: |', 'filter', { env: { uuidEncoding: 'java' } }))[0]?.insertText
+    ).toBe('JUUID("$0")')
+    expect(ordered(run('{ legacy: |'))[0]?.insertText).toBe('BinData(3, "$0")')
+    expect(ordered(run('{ big: |'))[0]?.insertText).toBe('NumberLong("${0:0}")')
+  })
+
+  it('offers no constructor for ints in a filter but NumberInt in a document', () => {
+    const filter = run('{ age: |')
+    expect(filter.items.some((i) => i.kind === 'constructor')).toBe(false)
+    expect(item(filter, '20')).toMatchObject({ insertText: '20', snippet: false })
+    const document = run('{ age: |', 'document')
+    expect(ordered(document)[0]).toMatchObject({ insertText: 'NumberInt(${0:0})', preselect: true })
+    expect(item(document, 'NumberInt(20)')).toBeDefined()
+  })
+
+  it('orders enum strings by count and preselects the most frequent', () => {
+    const result = run('{ status: |')
+    const values = ordered(result).filter((i) => i.kind === 'value')
+    expect(values.map((i) => i.label)).toEqual(['"active"', '"inactive"'])
+    expect(values[0]).toMatchObject({ preselect: true, sortText: 'b0000', filterText: 'active' })
+    expect(preselected(result)).toHaveLength(1)
+  })
+
+  it('shows three examples of a high-cardinality field at tier d', () => {
+    const examples = run('{ name: |').items.filter((i) => i.description === 'example')
+    expect(examples).toHaveLength(3)
+    expect(examples.every((i) => i.sortText.startsWith('d'))).toBe(true)
+  })
+
+  it('uses the element type of an array field', () => {
+    expect(ordered(run('{ ids: |'))[0]?.insertText).toBe('ObjectId("$0")')
+  })
+
+  it('excludes values already in the $in array', () => {
+    const result = run('{ status: { $in: ["active", |')
+    expect(item(result, '"active"')).toBeUndefined()
+    expect(item(result, '"inactive"')).toBeDefined()
+  })
+
+  it('wraps the constructor in an array for $in before the array is typed', () => {
+    expect(ordered(run('{ _id: { $in: |'))[0]).toMatchObject({
+      insertText: '[ObjectId("$0")]',
+      retrigger: true
+    })
+  })
+
+  it('offers only string contents inside quotes', () => {
+    const result = run('{ status: "ac|" }')
+    expect(result.items.map((i) => i.insertText)).toEqual(['active', 'inactive'])
+    expect(run('{ age: "|" }').items).toEqual([])
+  })
+
+  it('keeps the more frequent boolean preselected', () => {
+    const result = run('{ flag: |')
+    expect(preselected(result).map((i) => i.label)).toEqual(['true'])
+  })
+
+  it('offers null in filters', () => {
+    expect(item(run('{ status: |'), 'null')?.sortText.startsWith('d')).toBe(true)
+  })
+
+  it('falls back to every constructor at tier e for an unknown field', () => {
+    const result = run('{ missing: |')
+    expect(result.items.length).toBeGreaterThan(5)
+    expect(result.items.every((i) => i.sortText.startsWith('e') && !i.preselect)).toBe(true)
+  })
+
+  it('suggests constructor arguments from samples', () => {
+    const result = run('{ _id: ObjectId("|") }')
+    expect(result.items[0]).toMatchObject({
+      label: '507f1f77bcf86cd799439000',
+      insertText: '507f1f77bcf86cd799439000'
+    })
+  })
+
+  it('replaces a whole string value up to its closing quote', () => {
+    const name = run('{ name: "us|er-1" }')
+    expect('{ name: "user-1" }'.slice(name.range.start, name.range.end)).toBe('user-1')
+    const date = run('{ createdAt: ISODate("2024-05|-07") }')
+    const dateText = '{ createdAt: ISODate("2024-05-07") }'
+    expect(dateText.slice(date.range.start, date.range.end)).toBe('2024-05-07')
+  })
+
+  it('closes an unterminated string around an inserted value', () => {
+    expect(item(run('{ status: "ac|, age: 5 }'), '"active"')?.insertText).toBe('active"')
+    expect(item(run('{ status: "ac|" }'), '"active"')?.insertText).toBe('active')
+  })
+
+  it('adds one space before an array template after a bare colon', () => {
+    expect(ordered(run('{ _id: { $in:|'))[0]?.insertText).toBe(' [ObjectId("$0")]')
+  })
+
+  it('lists observed type aliases first', () => {
+    expect(labels(run('{ age: { $type: |'))[0]).toBe('int')
+    expect(item(run('{ age: { $type: |'), 'int')?.insertText).toBe('"int"')
+  })
+})
+
+describe('suggest: escaping', () => {
+  const unescapedDollar = /(^|[^\\])\$(?![0-9{])/
+  const positions: [string, EditorKind][] = [
+    ['{ |', 'filter'],
+    ['{ "|', 'filter'],
+    ['{ "a": 1, |', 'filter'],
+    ['{ age: { |', 'filter'],
+    ['{ name: { |', 'filter'],
+    ['{ tags: { $elemMatch: { |', 'filter'],
+    ['{ _id: |', 'filter'],
+    ['{ missing: |', 'filter'],
+    ['{ $text: { |', 'filter'],
+    ['{ a: { $near: { |', 'filter'],
+    ['[ |', 'pipeline'],
+    ['[{ |', 'pipeline'],
+    ['[{ "|', 'pipeline'],
+    ['[{ $group: { _id: null, n: { |', 'pipeline'],
+    ['[{ $setWindowFields: { output: { r: { |', 'pipeline'],
+    ['[{ $project: { x: { |', 'pipeline'],
+    ['[{ $lookup: { |', 'pipeline'],
+    ['[{ $unwind: { |', 'pipeline'],
+    ['{ tags: |', 'projection'],
+    ['{ name: |', 'sort'],
+    ['|', 'shell'],
+    ['db.users.|', 'shell'],
+    ['db.users.find({}).|', 'shell'],
+    ['db.users.insertOne({ |', 'shell'],
+    ['db.users.updateOne({}, { |', 'shell'],
+    ['db.users.updateOne({}, { $currentDate: { createdAt: |', 'shell'],
+    ['db.users.updateOne({}, { $bit: { flags: |', 'shell'],
+    ['db.users.updateOne({}, { $push: { tags: |', 'shell'],
+    ['db.users.updateOne({}, { $push: { tags: { |', 'shell'],
+    ['db.users.updateOne({}, [|', 'shell'],
+    ['db.users.updateMany({}, {}, { |', 'shell'],
+    ['db.users.aggregate([{ $match: {} }, { |', 'shell'],
+    ['db.users.bulkWrite([|', 'shell'],
+    ['db.users.bulkWrite([{ updateOne: { |', 'shell'],
+    ['{ a: |', 'document']
+  ]
+
+  it.each(positions)('escapes literal $ in snippets at %s (%s)', (marked, kind) => {
+    for (const suggestion of run(marked, kind).items) {
+      if (suggestion.snippet) expect(suggestion.insertText).not.toMatch(unescapedDollar)
+    }
+  })
+
+  it('escapes $ in quoted operator keys', () => {
+    expect(item(run('{ "a": 1, | }'), '$and')?.insertText).toBe('"\\$and": [{ $0 }]')
+  })
+
+  it('inserts sample values containing $ as plain text', () => {
+    expect(item(run('{ note: |'), '"price $5"')).toMatchObject({
+      insertText: '"price $5"',
+      snippet: false
+    })
+  })
+})
+
+describe('suggest: keys', () => {
+  it('lists _id first, then fields by presence and depth', () => {
+    const result = labels(run('{ |'))
+    expect(result[0]).toBe('_id')
+    expect(result.indexOf('name')).toBeLessThan(result.indexOf('address.city'))
+    expect(result).toContain('scores')
+    expect(result).not.toContain('scores.*')
+  })
+
+  it('inserts key, colon and space and re-opens suggestions', () => {
+    expect(item(run('{ |'), 'name')).toMatchObject({
+      insertText: 'name: ',
+      snippet: false,
+      retrigger: true
+    })
+  })
+
+  it('inserts only the key when a colon follows', () => {
+    const name = item(run('{ na|me: 1 }'), 'name')
+    expect(name).toMatchObject({ insertText: 'name' })
+    expect(name?.retrigger).toBeUndefined()
+  })
+
+  it('quotes dotted paths and keys in quoted documents', () => {
+    expect(item(run('{ ad|'), 'address.city')?.insertText).toBe('"address.city": ')
+    expect(item(run('{ "age": 1, |'), 'name')?.insertText).toBe('"name": ')
+  })
+
+  it('completes inside quotes and replaces through the closing quote', () => {
+    const result = run('{ "na|" }')
+    expect(item(result, 'name')?.insertText).toBe('name": ')
+    expect(result.range).toEqual({ start: 3, end: 6 })
+  })
+
+  it('excludes present keys', () => {
+    expect(item(run('{ name: 1, |'), 'name')).toBeUndefined()
+  })
+
+  it('narrows to children after a dotted prefix', () => {
+    const result = run('{ address.|')
+    expect(labels(result)).toEqual(['address.city', 'address.zip'])
+    expect(result.range.start).toBe(2)
+  })
+
+  it('does not expand a map-like object', () => {
+    expect(run('{ scores.|').items).toEqual([])
+  })
+
+  it('offers top-level operators at tier c, or tier a after $', () => {
+    expect(item(run('{ |'), '$or')?.sortText.startsWith('c')).toBe(true)
+    expect(item(run('{ $|'), '$or')?.sortText.startsWith('a')).toBe(true)
+  })
+
+  it('ranks operators by the field type', () => {
+    const name = run('{ name: { |')
+    expect(item(name, '$regex')?.sortText.startsWith('c')).toBe(true)
+    expect(item(name, '$size')?.sortText.startsWith('e')).toBe(true)
+    const tags = run('{ tags: { |')
+    for (const op of ['$size', '$all', '$elemMatch'])
+      expect(item(tags, op)?.sortText.startsWith('c')).toBe(true)
+  })
+
+  it('offers $options only next to $regex', () => {
+    expect(item(run('{ name: { |'), '$options')).toBeUndefined()
+    expect(item(run('{ name: { $regex: /a/, |'), '$options')).toBeDefined()
+  })
+
+  it('inserts operator templates', () => {
+    const result = run('{ _id: { |')
+    expect(item(result, '$in')).toMatchObject({
+      insertText: '\\$in: [$0]',
+      snippet: true,
+      retrigger: true
+    })
+    expect(item(result, '$gt')).toMatchObject({
+      insertText: '$gt: ',
+      snippet: false,
+      retrigger: true
+    })
+    expect(item(result, '$oid')?.sortText.startsWith('e')).toBe(true)
+  })
+
+  it('excludes keys that follow the cursor', () => {
+    expect(item(run('{ |, name: "x" }'), 'name')).toBeUndefined()
+    expect(item(run('{\n  "|"\n  "name": "x"\n}', 'document'), 'name')).toBeUndefined()
+  })
+
+  it('replaces a whole dotted key from its first segment', () => {
+    const result = run('{ addr|ess.city: 1 }')
+    expect('{ address.city: 1 }'.slice(result.range.start, result.range.end)).toBe('address.city')
+    expect(item(result, 'address')?.insertText).toBe('address')
+  })
+
+  it('offers only direct children as $jsonSchema property names', () => {
+    const root = labels(run('{ $jsonSchema: { properties: { | } } }'))
+    expect(root).toContain('address')
+    expect(root).not.toContain('address.city')
+    expect(
+      labels(run('{ $jsonSchema: { properties: { address: { properties: { | } } } } }'))
+    ).toEqual(['city', 'zip'])
+  })
+
+  it('treats only GeoJSON objects as geo fields', () => {
+    expect(item(run('{ address: { | } }'), '$geoWithin')?.sortText.startsWith('e')).toBe(true)
+    const loc = run('{ loc: { | } }', 'filter', { env: { coll: 'places' } })
+    expect(item(loc, '$near')?.sortText.startsWith('c')).toBe(true)
+  })
+
+  it('leaves non-fitting operators out once a letter is typed', () => {
+    expect(item(run('{ address: { | } }'), '$bitsAllClear')).toBeDefined()
+    expect(item(run('{ address: { c| } }'), '$bitsAllClear')).toBeUndefined()
+  })
+
+  it('suggests document keys of the nested path and nothing below a map', () => {
+    expect(labels(run('{ address: { |', 'document'))).toEqual(['city', 'zip'])
+    expect(run('{ scores: { |', 'document').items).toEqual([])
+  })
+
+  it('documents sample values in the editor kind and display settings of each request', () => {
+    const doc = (label: string, kind: EditorKind, env: Partial<SuggestEnv> = {}) =>
+      item(run('{ |', kind, { env }), label)?.documentation
+    expect(doc('createdAt', 'filter')).toContain('`ISODate("2024-01-01T00:00:00.000Z")` ×1')
+    expect(doc('createdAt', 'filter', { timezone: 'Europe/Berlin' })).toContain(
+      '`ISODate("2024-01-01T01:00:00.000+01:00")` ×1'
+    )
+    expect(doc('age', 'filter')).toContain('`20` ×1')
+    expect(doc('age', 'document')).toContain('`NumberInt(20)` ×1')
+    expect(doc('legacy', 'filter', { uuidEncoding: 'java' })).toContain('`JUUID("')
+    expect(doc('legacy', 'filter')).toContain('`BinData(3, "')
+  })
+})
+
+describe('suggest: projection and sort', () => {
+  it('puts 1 first in include mode and 0 first in exclude mode', () => {
+    expect(preselected(run('{ name: 1, age: |', 'projection')).map((i) => i.label)).toEqual(['1'])
+    expect(preselected(run('{ name: 0, age: |', 'projection')).map((i) => i.label)).toEqual(['0'])
+    expect(preselected(run('{ _id: |', 'projection')).map((i) => i.label)).toEqual(['0'])
+  })
+
+  it('offers $slice and $elemMatch for arrays', () => {
+    expect(item(run('{ tags: |', 'projection'), '{ $slice: … }')).toBeDefined()
+    expect(item(run('{ name: |', 'projection'), '{ $slice: … }')).toBeUndefined()
+  })
+
+  it('preselects -1 for date fields and 1 otherwise', () => {
+    expect(preselected(run('{ createdAt: |', 'sort')).map((i) => i.label)).toEqual(['-1'])
+    expect(preselected(run('{ name: |', 'sort')).map((i) => i.label)).toEqual(['1'])
+  })
+})
+
+describe('suggest: pipelines', () => {
+  it('offers first-stage-only stages only at index 0', () => {
+    expect(item(run('[ |', 'pipeline'), '$geoNear')).toBeDefined()
+    const second = run('[{ $match: {} }, { |', 'pipeline')
+    expect(item(second, '$geoNear')).toBeUndefined()
+    expect(item(second, '$match')).toBeDefined()
+  })
+
+  it('never offers stages that cannot run here', () => {
+    const main = labels(run('[ |', 'pipeline'))
+    for (const stage of ['$out', '$merge', '$changeStream', '$documents', '$currentOp'])
+      expect(main).not.toContain(stage)
+    expect(main).toContain('$geoNear')
+  })
+
+  it('offers only the stages a $facet branch allows', () => {
+    const facet = labels(run('[{ $facet: { a: [{ | }] } }]', 'pipeline'))
+    for (const stage of ['$facet', '$geoNear', '$collStats', '$indexStats', '$search'])
+      expect(facet).not.toContain(stage)
+    expect(facet).toContain('$match')
+  })
+
+  it('offers $documents first in a $lookup pipeline', () => {
+    const sub = labels(run('[{ $lookup: { as: "o", pipeline: [ | ] } }]', 'pipeline'))
+    expect(sub).toContain('$documents')
+    expect(sub).not.toContain('$merge')
+  })
+
+  it('does not call $group outputs overwrites', () => {
+    const group = run('[{ $group: { _id: "$status", | } }]', 'pipeline')
+    expect(group.items.some((i) => i.description === 'overwrite')).toBe(false)
+    expect(item(run('[{ $set: { | } }]', 'pipeline'), 'name')?.description).toBe('overwrite')
+  })
+
+  it('pins _id only where the stage input can have it', () => {
+    expect(
+      labels(run('[{ $replaceRoot: { newRoot: "$address" } }, { $project: { | } }]', 'pipeline'))
+    ).toEqual(['city', 'zip'])
+    expect(labels(run('{ | }', 'projection'))[0]).toBe('_id')
+    expect(labels(run('{ | }', 'projection', { env: { schemaOf: () => null } }))).toEqual(['_id'])
+  })
+
+  it('ranks expressions over array projection operators for a computed field', () => {
+    const computed = run('[{ $project: { x: { | } } }]', 'pipeline')
+    expect(item(computed, '$abs')?.sortText.startsWith('c')).toBe(true)
+    expect(item(computed, '$meta')?.sortText.startsWith('c')).toBe(true)
+    expect(item(computed, '$elemMatch')?.sortText.startsWith('e')).toBe(true)
+    expect(item(computed, '$slice')).toMatchObject({ insertText: '\\$slice: [$0]' })
+    const array = run('[{ $project: { tags: { | } } }]', 'pipeline')
+    expect(item(array, '$slice')?.sortText.startsWith('c')).toBe(true)
+    expect(item(array, '$abs')?.sortText.startsWith('e')).toBe(true)
+  })
+
+  it('offers subfields as keys of a $set object literal', () => {
+    const result = run('[{ $set: { address: { | } } }]', 'pipeline')
+    expect(labels(result).slice(0, 2)).toEqual(['city', 'zip'])
+    expect(item(result, 'city')?.insertText).toBe('city: ')
+    expect(item(result, '$concat')?.sortText.startsWith('c')).toBe(true)
+  })
+
+  it('offers root fields as keys of a compound $group key', () => {
+    const result = run('[{ $group: { _id: { | } } }]', 'pipeline')
+    expect(item(result, 'status')?.sortText.startsWith('b')).toBe(true)
+    expect(item(result, 'address.city')).toBeUndefined()
+  })
+
+  it('wraps stage templates in an element', () => {
+    expect(item(run('[ |', 'pipeline'), '$match')?.insertText).toBe('{ \\$match: { $0 } }')
+    expect(item(run('[{ |', 'pipeline'), '$group')?.insertText).toBe('\\$group: { _id: $0 }')
+  })
+
+  it('suggests field references inside expression strings', () => {
+    const result = run('[{ $group: { _id: "$|" } }]', 'pipeline')
+    expect(item(result, '$name')).toMatchObject({ insertText: '$name', snippet: false })
+    expect(item(result, '$$ROOT')).toBeDefined()
+  })
+
+  it('suggests fields of the stage input', () => {
+    const result = run('[{ $project: { label: "$name" } }, { $match: { |', 'pipeline')
+    expect(labels(result)).toContain('label')
+    expect(labels(result)).not.toContain('age')
+  })
+
+  it('suggests foreign fields from the $lookup target', () => {
+    expect(labels(run('[{ $lookup: { from: "orders", foreignField: "|', 'pipeline'))).toEqual([
+      '_id',
+      'total',
+      'userId'
+    ])
+  })
+
+  it('lists other collections first and the current one last', () => {
+    expect(labels(run('[{ $lookup: { from: "|', 'pipeline'))).toEqual([
+      'orders',
+      'my logs',
+      'users'
+    ])
+  })
+
+  it('lists required stage arguments first', () => {
+    const result = labels(run('[{ $lookup: { |', 'pipeline'))
+    expect(result.slice(0, 2)).toEqual(['from', 'as'])
+  })
+
+  it('offers accumulators and window functions', () => {
+    expect(item(run('[{ $group: { _id: null, n: { |', 'pipeline'), '$sum')?.insertText).toBe(
+      '\\$sum: ${0:1}'
+    )
+    expect(item(run('[{ $group: { _id: null, n: { |', 'pipeline'), '$rank')).toBeUndefined()
+    expect(item(run('[{ $setWindowFields: { output: { r: { |', 'pipeline'), '$rank')).toBeDefined()
+  })
+})
+
+describe('suggest: expected types', () => {
+  it('ranks numeric fields first for a numeric accumulator', () => {
+    expect(labels(run('[{ $group: { _id: null, t: { $sum: "$|" } } }]', 'pipeline'))[0]).toBe(
+      '$age'
+    )
+  })
+
+  it('ranks date fields first for a date argument', () => {
+    const marked = '[{ $project: { d: { $dateToString: { date: "$|" } } } }]'
+    expect(labels(run(marked, 'pipeline'))[0]).toBe('$createdAt')
+  })
+
+  it('ranks fields like the other side of a comparison first', () => {
+    expect(labels(run('{ $expr: { $gt: ["$big", "$|"] } }')).slice(0, 2)).toEqual(['$age', '$big'])
+  })
+
+  it('ranks bool-returning operators first under $expr', () => {
+    const result = run('{ $expr: { | } }')
+    expect(item(result, '$gt')?.sortText.startsWith('b')).toBe(true)
+    expect(item(result, '$abs')?.sortText.startsWith('c')).toBe(true)
+  })
+
+  it('ranks foreign fields of the local field type first', () => {
+    const marked = '[{ $lookup: { from: "orders", localField: "age", foreignField: "|" } }]'
+    expect(labels(run(marked, 'pipeline'))[0]).toBe('total')
+  })
+})
+
+describe('suggest: variables', () => {
+  it('completes subfields of a variable bound to a field', () => {
+    const marked = '{ $expr: { $let: { vars: { home: "$address" }, in: "$$home.|" } } }'
+    const result = run(marked, 'filter', { trigger: char('.') })
+    expect(labels(result)).toEqual(['$$home.city', '$$home.zip'])
+    expect(item(result, '$$home.city')).toMatchObject({
+      insertText: '$$home.city',
+      filterText: '$$home.city'
+    })
+  })
+
+  it('completes element subfields of $map and $filter variables', () => {
+    const env = { coll: 'places' }
+    const map = '[{ $project: { s: { $map: { input: "$items", as: "it", in: "$$it.|" } } } }]'
+    expect(labels(run(map, 'pipeline', { env }))).toEqual(['$$it.qty', '$$it.sku'])
+    const filter = '[{ $project: { s: { $filter: { input: "$items", cond: "$$this.|" } } } }]'
+    expect(labels(run(filter, 'pipeline', { env }))).toEqual(['$$this.qty', '$$this.sku'])
+  })
+
+  it('offers nothing below a variable that holds no field', () => {
+    const marked = '{ $expr: { $reduce: { input: "$tags", initialValue: 0, in: "$$value.|" } } }'
+    expect(run(marked).items).toEqual([])
+  })
+})
+
+describe('suggest: shell', () => {
+  it('starts with a find on the tab collection', () => {
+    expect(ordered(run('|', 'shell'))[0]).toMatchObject({
+      insertText: 'db.users.find({ $0 })',
+      preselect: true
+    })
+    expect(ordered(run('|', 'shell', { env: { coll: 'my logs' } }))[0]?.insertText).toBe(
+      'db.getCollection("my logs").find({ $0 })'
+    )
+  })
+
+  it('lists dot-addressable collections first, current first', () => {
+    expect(labels(run('db.|', 'shell'))).toEqual(['users', 'orders', 'my logs'])
+    expect(item(run('db.|', 'shell'), 'orders')).toMatchObject({
+      insertText: 'orders.',
+      retrigger: true
+    })
+  })
+
+  it('reaches other collection names through getCollection', () => {
+    expect(item(run('db.|', 'shell'), 'my logs')).toMatchObject({
+      insertText: 'getCollection("my logs").',
+      filterText: 'my logs',
+      retrigger: true
+    })
+    expect(item(run('db.|', 'shell'), 'my logs')?.sortText.startsWith('c')).toBe(true)
+  })
+
+  it('continues a dotted collection name before the methods', () => {
+    const result = run('db.game.|', 'shell', { env: { collections: ['users', 'game.events'] } })
+    expect(item(result, 'events')).toMatchObject({ insertText: 'events.', retrigger: true })
+    expect(item(result, 'events')?.sortText.startsWith('b')).toBe(true)
+    expect(item(result, 'find')).toBeDefined()
+  })
+
+  it('addresses the tab collection through the injected accessor', () => {
+    const env = {
+      collectionAccessor: (coll: string) => `db.getCollection(${JSON.stringify(coll)})`
+    }
+    expect(ordered(run('|', 'shell', { env }))[0]?.insertText).toBe(
+      'db.getCollection("users").find({ $0 })'
+    )
+  })
+
+  it('takes the calls allowed after aggregate from the environment', () => {
+    const env = { aggregateCursorMethods: ['toArray'] }
+    expect(labels(run('db.users.aggregate([]).|', 'shell', { env }))).toEqual(['toArray'])
+  })
+
+  it('keeps the chain when replacing a collection segment', () => {
+    expect(item(run('db.us|ers.find({})', 'shell'), 'orders')).toMatchObject({
+      insertText: 'orders'
+    })
+  })
+
+  it('lists exactly the supported collection methods', () => {
+    expect(labels(run('db.users.|', 'shell'))).toEqual([...SHELL_COLLECTION_METHODS])
+  })
+
+  it('lists the cursor methods not used yet', () => {
+    expect(labels(run('db.users.find({}).limit(5).|', 'shell'))).toEqual(
+      SHELL_CURSOR_METHODS.filter((m) => m !== 'limit')
+    )
+    expect(labels(run('db.users.aggregate([]).|', 'shell'))).toEqual(['toArray', 'pretty'])
+    expect(run('db.users.findOne({}).|', 'shell').items).toEqual([])
+  })
+
+  it('keeps an existing argument list when renaming a method', () => {
+    expect(item(run('db.users.fi|({})', 'shell'), 'find')).toMatchObject({
+      insertText: 'find',
+      snippet: false
+    })
+  })
+})
+
+describe('suggest: shell writes', () => {
+  const shell = (
+    marked: string,
+    options: { env?: Partial<SuggestEnv>; trigger?: SuggestTrigger } = {}
+  ) => run(marked, 'shell', options)
+
+  it('inserts call templates for the write methods', () => {
+    const result = shell('db.users.|', { env: { shellMethods: WRITE_METHODS } })
+    expect(labels(result)).toEqual([...WRITE_METHODS])
+    expect(item(result, 'updateOne')).toMatchObject({
+      insertText: 'updateOne({ $0 })',
+      snippet: true,
+      retrigger: true
+    })
+    expect(item(result, 'insertMany')?.insertText).toBe('insertMany([{ $0 }])')
+    expect(item(result, 'bulkWrite')?.insertText).toBe('bulkWrite([$0])')
+    for (const method of WRITE_METHODS) expect(item(result, method)?.documentation).toBeTruthy()
+  })
+
+  it('completes inserted documents with document fidelity', () => {
+    expect(ordered(shell('db.users.insertOne({ age: |'))[0]).toMatchObject({
+      insertText: 'NumberInt(${0:0})',
+      preselect: true
+    })
+    expect(ordered(shell('db.users.insertOne({ big: |'))[0]?.insertText).toBe(
+      'NumberLong("${0:0}")'
+    )
+    expect(labels(shell('db.users.insertOne({ address: { |'))).toEqual(['city', 'zip'])
+    expect(labels(shell('db.users.insertMany([{ name: "x" }, { |'))).toContain('name')
+    expect(ordered(shell('db.users.find({ age: |'))[0]?.kind).not.toBe('constructor')
+  })
+
+  it('lists the update operators at the root of an update', () => {
+    const result = shell('db.users.updateOne({}, { |')
+    expect(labels(result)).toEqual([
+      '$set',
+      '$unset',
+      '$inc',
+      '$mul',
+      '$rename',
+      '$min',
+      '$max',
+      '$currentDate',
+      '$setOnInsert',
+      '$push',
+      '$addToSet',
+      '$pop',
+      '$pull',
+      '$pullAll',
+      '$bit'
+    ])
+    expect(item(result, '$set')).toMatchObject({
+      insertText: '\\$set: { $0 }',
+      snippet: true,
+      retrigger: true
+    })
+    expect(item(shell('db.users.updateOne({}, { $set: {}, | })'), '$set')).toBeUndefined()
+  })
+
+  it('offers updatable fields under an update operator', () => {
+    const set = shell('db.users.updateOne({}, { $set: { |')
+    expect(labels(set)).not.toContain('_id')
+    expect(item(set, 'address.city')?.insertText).toBe('"address.city": ')
+    expect(labels(shell('db.users.updateOne({}, { $setOnInsert: { |'))).toContain('_id')
+    expect(labels(shell('db.users.updateOne({}, { $set: { address.|'))).toEqual([
+      'address.city',
+      'address.zip'
+    ])
+  })
+
+  it('addresses fields inside array elements through $[]', () => {
+    const set = labels(shell('db.places.updateOne({}, { $set: { | } })'))
+    expect(set).toEqual(expect.arrayContaining(['items', 'items.$[].qty', 'items.$[].sku']))
+    expect(set).not.toContain('items.qty')
+    expect(
+      item(shell('db.places.updateOne({}, { $inc: { | } })'), 'items.$[].qty')?.insertText
+    ).toBe('"items.$[].qty": ')
+    expect(labels(shell('db.places.updateOne({}, { $set: { items.| } })'))).toEqual([
+      'items.$[].qty',
+      'items.$[].sku'
+    ])
+    expect(labels(shell('db.places.updateOne({}, { $set: { "items.$[it].|" } })'))).toEqual([
+      'items.$[it].qty',
+      'items.$[it].sku'
+    ])
+  })
+
+  it('renames only fields outside array elements, never onto _id or its own path', () => {
+    const keys = labels(shell('db.places.updateOne({}, { $rename: { | } })'))
+    expect(keys).toEqual(expect.arrayContaining(['items', 'loc', 'loc.type']))
+    expect(keys.some((key) => key.includes('$'))).toBe(false)
+    expect(labels(shell('db.places.updateOne({}, { $rename: { loc: |'))).toEqual(['items'])
+    expect(labels(shell('db.places.updateOne({}, { $rename: { "loc.type": |'))).toEqual([
+      'items',
+      'loc.coordinates'
+    ])
+  })
+
+  it('ranks the fields an operator applies to first', () => {
+    expect(labels(shell('db.users.updateOne({}, { $inc: { |')).slice(0, 2)).toEqual(['age', 'big'])
+    expect(labels(shell('db.users.updateOne({}, { $push: { |')).slice(0, 2)).toEqual([
+      'ids',
+      'tags'
+    ])
+    expect(labels(shell('db.users.updateOne({}, { $currentDate: { |'))[0]).toBe('createdAt')
+  })
+
+  it('excludes fields other operators of the update already change', () => {
+    const result = shell('db.users.updateOne({}, { $set: { name: "x" }, $unset: { | } })')
+    expect(item(result, 'name')).toBeUndefined()
+    expect(item(result, 'status')).toBeDefined()
+  })
+
+  it('suggests the values each update operator takes', () => {
+    const inc = shell('db.users.updateOne({}, { $inc: { age: |')
+    expect(labels(inc)).toEqual(['1', '-1'])
+    expect(preselected(inc).map((i) => i.label)).toEqual(['1'])
+    expect(labels(shell('db.users.updateOne({}, { $mul: { age: |'))).toEqual(['2', '-1'])
+    expect(ordered(shell('db.users.updateOne({}, { $unset: { age: |'))[0]).toMatchObject({
+      insertText: '""',
+      preselect: true
+    })
+    expect(labels(shell('db.users.updateOne({}, { $pop: { tags: |'))).toEqual(['1', '-1'])
+    expect(ordered(shell('db.users.updateOne({}, { $set: { age: |'))[0]?.insertText).toBe(
+      'NumberInt(${0:0})'
+    )
+    expect(ordered(shell('db.users.updateOne({}, { $max: { createdAt: |'))[0]?.label).toBe(
+      'ISODate("…")'
+    )
+    expect(
+      item(shell('db.users.updateOne({}, { $rename: { name: |'), 'address.city')
+    ).toMatchObject({ insertText: '"address.city"' })
+    expect(ordered(shell('db.users.updateOne({}, { $pullAll: { tags: |'))[0]).toMatchObject({
+      insertText: '[$0]',
+      preselect: true
+    })
+  })
+
+  it('sets the current date as true or a typed $type', () => {
+    const result = shell('db.users.updateOne({}, { $currentDate: { createdAt: |')
+    expect(labels(result)).toEqual(['true', '{ $type: "date" }', '{ $type: "timestamp" }'])
+    expect(preselected(result).map((i) => i.label)).toEqual(['true'])
+    expect(item(result, '{ $type: "date" }')).toMatchObject({
+      insertText: '{ \\$type: "date" }',
+      snippet: true
+    })
+    const env = { schemaOf: () => schemaOf({ ts: { $timestamp: { t: 1, i: 1 } } }) }
+    const timestamp = shell('db.users.updateOne({}, { $currentDate: { ts: |', { env })
+    expect(preselected(timestamp).map((i) => i.label)).toEqual(['{ $type: "timestamp" }'])
+    expect(
+      item(shell('db.users.updateOne({}, { $currentDate: { createdAt: { |'), '$type')
+    ).toMatchObject({ insertText: '$type: ', retrigger: true })
+    expect(labels(shell('db.users.updateOne({}, { $currentDate: { createdAt: { $type: |'))).toEqual(
+      ['"date"', '"timestamp"']
+    )
+  })
+
+  it('offers the bitwise operations of $bit', () => {
+    expect(labels(shell('db.users.updateOne({}, { $bit: { age: |'))).toEqual([
+      '{ and: … }',
+      '{ or: … }',
+      '{ xor: … }'
+    ])
+    expect(labels(shell('db.users.updateOne({}, { $bit: { age: { |'))).toEqual(['and', 'or', 'xor'])
+  })
+
+  it('suggests element values and modifiers for $push and $addToSet', () => {
+    const value = shell('db.users.updateOne({}, { $push: { tags: |')
+    expect(preselected(value).map((i) => i.label)).toEqual(['"a"'])
+    expect(item(value, '{ $each: [ … ] }')).toMatchObject({
+      insertText: '{ \\$each: [$0] }',
+      retrigger: true
+    })
+    expect(labels(shell('db.users.updateOne({}, { $push: { tags: { |'))).toEqual([
+      '$each',
+      '$position',
+      '$slice',
+      '$sort'
+    ])
+    expect(labels(shell('db.users.updateOne({}, { $addToSet: { tags: { |'))).toEqual(['$each'])
+    const each = shell('db.users.updateOne({}, { $addToSet: { ids: { $each: [|')
+    expect(ordered(each)[0]?.insertText).toBe('ObjectId("$0")')
+  })
+
+  it('offers element fields beside the modifiers until one kind is used', () => {
+    expect(labels(shell('db.places.updateOne({}, { $push: { items: { |'))).toEqual([
+      'qty',
+      'sku',
+      '$each',
+      '$position',
+      '$slice',
+      '$sort'
+    ])
+    expect(
+      labels(shell('db.places.updateOne({}, { $push: { items: { $each: [], | } } })'))
+    ).toEqual(['$position', '$slice', '$sort'])
+    expect(labels(shell('db.places.updateOne({}, { $push: { items: { sku: "a", | } } })'))).toEqual(
+      ['qty']
+    )
+    expect(labels(shell('db.places.updateOne({}, { $push: { items: { $sort: { |'))).toEqual([
+      'qty',
+      'sku'
+    ])
+  })
+
+  it('reads $pull values as conditions on the array elements', () => {
+    expect(item(shell('db.users.updateOne({}, { $pull: { tags: |'), '"a"')).toBeDefined()
+    const keys = labels(shell('db.places.updateOne({}, { $pull: { items: { |'))
+    expect(keys.slice(0, 2)).toEqual(['qty', 'sku'])
+    expect(keys).toContain('$or')
+  })
+
+  it('lists the options of each write method', () => {
+    const update = labels(shell('db.users.updateOne({}, { $set: {} }, { |'))
+    expect(update[0]).toBe('upsert')
+    expect([...update].sort()).toEqual(Object.keys(WRITE_OPTIONS.updateOne).sort())
+    expect(labels(shell('db.users.insertMany([], { |'))).toEqual([
+      'ordered',
+      'bypassDocumentValidation'
+    ])
+    expect(item(shell('db.users.updateOne({}, {}, { |'), 'upsert')).toMatchObject({
+      insertText: 'upsert: ',
+      retrigger: true
+    })
+    expect(item(shell('db.users.updateMany({}, {}, { |'), 'arrayFilters')?.insertText).toBe(
+      'arrayFilters: [{ $0 }]'
+    )
+  })
+
+  it('offers no arrayFilters next to an update pipeline', () => {
+    expect(item(shell('db.users.updateOne({}, [{ $set: { a: 1 } }], { |'), 'arrayFilters')).toBe(
+      undefined
+    )
+    expect(
+      item(shell('db.users.updateOne({}, { $set: { a: 1 } }, { |'), 'arrayFilters')
+    ).toBeDefined()
+    const bulk = 'db.users.bulkWrite([{ updateMany: { filter: {}, | update: [{ $unset: "a" }] } }])'
+    expect(item(shell(bulk), 'arrayFilters')).toBeUndefined()
+    expect(item(shell(bulk), 'upsert')).toBeDefined()
+  })
+
+  it('offers only one of returnDocument and returnNewDocument', () => {
+    const options = (rest: string) =>
+      labels(shell(`db.users.findOneAndUpdate({}, {}, { ${rest}| })`))
+    expect(options('')).toEqual(expect.arrayContaining(['returnDocument', 'returnNewDocument']))
+    expect(options('returnDocument: "after", ')).not.toContain('returnNewDocument')
+    expect(options('returnNewDocument: true, ')).not.toContain('returnDocument')
+  })
+
+  it('completes option values by kind', () => {
+    expect(labels(shell('db.users.updateOne({}, {}, { upsert: |'))).toEqual(['true', 'false'])
+    expect(labels(shell('db.users.findOneAndUpdate({}, {}, { returnDocument: |'))).toEqual([
+      '"after"',
+      '"before"'
+    ])
+    expect(labels(shell('db.users.findOneAndDelete({}, { sort: { createdAt: |'))[0]).toBe('-1')
+    expect(labels(shell('db.users.findOneAndReplace({}, {}, { projection: { |'))[0]).toBe('_id')
+  })
+
+  it('completes arrayFilters keys from the identifiers of the update', () => {
+    const update = '{ $set: { "items.$[it].qty": 1 } }'
+    const result = shell(`db.places.updateMany({}, ${update}, { arrayFilters: [{ |`)
+    expect(labels(result)).toEqual(['it', 'it.qty', 'it.sku'])
+    expect(item(result, 'it.qty')).toMatchObject({ insertText: '"it.qty": ', retrigger: true })
+    expect(item(result, 'it')?.insertText).toBe('it: ')
+    expect(
+      labels(shell(`db.places.updateMany({}, ${update}, { arrayFilters: [{ it.| }] })`))
+    ).toEqual(['it.qty', 'it.sku'])
+  })
+
+  it('wraps bulkWrite operations as array elements', () => {
+    const result = shell('db.users.bulkWrite([|')
+    expect(labels(result)).toEqual([...BULK_WRITE_OPERATIONS])
+    expect(item(result, 'updateOne')).toMatchObject({
+      insertText: '{ updateOne: { $0 } }',
+      snippet: true,
+      retrigger: true
+    })
+    expect(item(shell('db.users.bulkWrite([{ |'), 'deleteMany')).toMatchObject({
+      insertText: 'deleteMany: { $0 }',
+      retrigger: true
+    })
+    expect(labels(shell('db.users.bulkWrite([{ updateOne: { |')).slice(0, 2)).toEqual([
+      'filter',
+      'update'
+    ])
+    expect(labels(shell('db.users.bulkWrite([{ insertOne: { |'))).toEqual(['document'])
+  })
+
+  it('offers $out and $merge only at the end of a shell aggregate', () => {
+    const last = shell('db.users.aggregate([{ $match: {} }, { |')
+    expect(item(last, '$out')?.sortText.startsWith('e')).toBe(true)
+    expect(item(last, '$merge')?.sortText.startsWith('e')).toBe(true)
+    expect(item(shell('db.users.aggregate([|'), '$out')).toBeDefined()
+    expect(item(shell('db.users.aggregate([{ | }, { $limit: 1 }])'), '$out')).toBeUndefined()
+    expect(
+      item(shell('db.users.aggregate([{ $lookup: { from: "orders", pipeline: [{ |'), '$merge')
+    ).toBeUndefined()
+  })
+
+  it('offers only the update pipeline stages in an update pipeline', () => {
+    const stages = [...UPDATE_PIPELINE_STAGES].sort()
+    expect(labels(shell('db.users.updateOne({}, [|')).sort()).toEqual(stages)
+    expect(labels(shell('db.users.updateOne({}, [{ $set: {} }, { |')).sort()).toEqual(stages)
+  })
+
+  it('opens on the trigger characters of update and bulkWrite slots', () => {
+    const opens = (marked: string, c: string) =>
+      shell(marked, { trigger: char(c) }).items.length > 0
+    expect(opens('db.users.updateOne({}, {|', '{')).toBe(true)
+    expect(opens('db.users.bulkWrite([|', '[')).toBe(true)
+    expect(opens('db.users.updateOne({}, { $inc: { age: | } })', ' ')).toBe(true)
+    expect(opens('db.users.updateOne({}, { $inc: { age: |1 } })', ' ')).toBe(false)
+    expect(opens('db.users.insertOne({ status: | })', ' ')).toBe(true)
+    expect(opens('db.users.insertOne({ missing: | })', ' ')).toBe(false)
+  })
+})
+
+describe('suggest: trigger gating', () => {
+  it('ignores a space that does not follow a colon', () => {
+    expect(run('{ a: 1, |', 'filter', { trigger: char(' ') }).items).toEqual([])
+  })
+
+  it('responds to a space or colon after a colon at a value position', () => {
+    expect(run('{ _id: |', 'filter', { trigger: char(' ') }).items.length).toBeGreaterThan(0)
+    expect(run('{ _id:|', 'filter', { trigger: char(':') }).items.length).toBeGreaterThan(0)
+  })
+
+  it('stays quiet on a typed colon or space when a value already follows', () => {
+    expect(run('{ status: |"active" }', 'filter', { trigger: char(' ') }).items).toEqual([])
+    expect(run('{ age: { $gt: |5 } }', 'filter', { trigger: char(' ') }).items).toEqual([])
+    expect(run('{ age:|-1 }', 'sort', { trigger: char(':') }).items).toEqual([])
+    expect(run('{ "age": |5 }', 'document', { trigger: char(' ') }).items).toEqual([])
+    expect(run('{ "flag": |true }', 'document', { trigger: char(' ') }).items).toEqual([])
+  })
+
+  it('opens on a typed colon or space in an empty value slot', () => {
+    const fits = (marked: string, kind: EditorKind, c: string) =>
+      run(marked, kind, { trigger: char(c) }).items.length > 0
+    expect(fits('{ status: | }', 'filter', ' ')).toBe(true)
+    expect(fits('{ status:|}', 'filter', ':')).toBe(true)
+    expect(fits('{\n  status: |\n}', 'filter', ' ')).toBe(true)
+    expect(fits('db.users.find({ status: | })', 'shell', ' ')).toBe(true)
+    expect(fits('{ age: { $exists: | } }', 'filter', ' ')).toBe(true)
+    expect(fits('{ age: | }', 'sort', ' ')).toBe(true)
+  })
+
+  it('does not pop up constructors of an unknown field on a typed colon or space', () => {
+    expect(run('{ missing: | }', 'filter', { trigger: char(' ') }).items).toEqual([])
+    expect(run('db.users.find({ missing: | })', 'shell', { trigger: char(' ') }).items).toEqual([])
+    expect(run('{ missing: | }').items.length).toBeGreaterThan(0)
+  })
+
+  it('never triggers on commas or letters', () => {
+    expect(run('{ a: 1,|', 'filter', { trigger: char(',') }).items).toEqual([])
+    expect(run('{ n|', 'filter', { trigger: char('n') }).items).toEqual([])
+  })
+
+  it('triggers $ at keys and expression values', () => {
+    expect(run('{ $|', 'filter', { trigger: char('$') }).items.length).toBeGreaterThan(0)
+    expect(run('{ a: $|', 'filter', { trigger: char('$') }).items).toEqual([])
+    expect(
+      run('[{ $group: { _id: "$|" } }]', 'pipeline', { trigger: char('$') }).items.length
+    ).toBeGreaterThan(0)
+  })
+
+  it('triggers quotes at keys and string-valued positions only', () => {
+    expect(run('{ "|" }', 'filter', { trigger: char('"') }).items.length).toBeGreaterThan(0)
+    expect(run('{ status: "|" }', 'filter', { trigger: char('"') }).items.length).toBeGreaterThan(0)
+    expect(run('{ age: "|" }', 'filter', { trigger: char('"') }).items).toEqual([])
+  })
+
+  it('triggers dots after dotted keys and in shell chains', () => {
+    expect(run('{ address.|', 'filter', { trigger: char('.') }).items.length).toBeGreaterThan(0)
+    expect(run('db.users.|', 'shell', { trigger: char('.') }).items.length).toBeGreaterThan(0)
+  })
+
+  it('triggers [ only for stage elements and array values', () => {
+    expect(run('[|]', 'pipeline', { trigger: char('[') }).items.length).toBeGreaterThan(0)
+    expect(
+      run('{ _id: { $in: [|] } }', 'filter', { trigger: char('[') }).items.length
+    ).toBeGreaterThan(0)
+    expect(run('{ a: [|] }', 'filter', { trigger: char('{') }).items).toEqual([])
+  })
+
+  it('limits the document editor to quotes at keys and colons at known empty values', () => {
+    expect(run('{ $|', 'document', { trigger: char('$') }).items).toEqual([])
+    expect(run('{ "|" }', 'document', { trigger: char('"') }).items.length).toBeGreaterThan(0)
+    expect(run('{ status:|', 'document', { trigger: char(':') }).items.length).toBeGreaterThan(0)
+    expect(run('{ missing:|', 'document', { trigger: char(':') }).items).toEqual([])
+    expect(run('{ status: | 5 }', 'document', { trigger: char(' ') }).items).toEqual([])
+  })
+
+  it('always responds to an explicit invoke', () => {
+    expect(run('{ missing: |', 'document').items.length).toBeGreaterThan(0)
+  })
+})
diff --git a/src/renderer/src/lib/completion/suggest.ts b/src/renderer/src/lib/completion/suggest.ts
new file mode 100644
index 0000000..dba3483
--- /dev/null
+++ b/src/renderer/src/lib/completion/suggest.ts
@@ -0,0 +1,1787 @@
+/**
+ * Ranked completion items for a classified cursor position: field paths from the sampled
+ * schema, typed constructors and sample values, operators, stages and shell methods.
+ */
+import type {
+  BsonTypeName,
+  CollectionSchema,
+  SchemaField,
+  TypeCounts,
+  UuidEncoding
+} from '@shared/types'
+import {
+  addCounts,
+  addressableFields,
+  childFields,
+  classifyCanonical,
+  compareText,
+  dominantType,
+  resolveSchemaField
+} from '@shared/collectionSchema'
+import { UNSUPPORTED_STAGES, WRITE_STAGES } from '@shared/pipeline'
+import { BULK_WRITE_OPERATIONS, UPDATE_PIPELINE_STAGES } from '@shared/writeOps'
+import { formatIsoInZone } from '../dateZone'
+import { isBareKey, serializeMongoValue } from '../mongoQuerySerialize'
+import {
+  ACCUMULATORS,
+  ARG_SPECS,
+  ARRAY_MODIFIERS,
+  CONSTRUCTOR_TYPES,
+  EJSON_WRAPPERS,
+  EXPRESSION_OPERATORS,
+  FIELD_OPERATORS,
+  GEO_KEYS,
+  JSON_SCHEMA_KEYS,
+  NUMERIC_TYPES,
+  POSITIONAL_SEGMENT,
+  PROJECTION_OPERATORS,
+  QUERY_TOP_OPERATORS,
+  SHELL_METHODS,
+  STAGES,
+  SYSTEM_VARIABLES,
+  TEXT_KEYS,
+  TYPE_ALIASES,
+  UPDATE_OPERATORS,
+  WINDOW_KEY,
+  typeAlias,
+  withoutPositional,
+  type ArgKind,
+  type ArrayModifierOwner,
+  type KeyDef,
+  type OperatorFit,
+  type OperatorForm,
+  type StageDef,
+  type TypeClass
+} from './catalog'
+import type {
+  ArrayIdentifier,
+  CompletionContext,
+  FieldSource,
+  Nesting,
+  Position,
+  Prefer,
+  Variable
+} from './context'
+import { applyStages, join } from './pipelineFlow'
+
+export type SuggestionKind =
+  | 'field'
+  | 'operator'
+  | 'stage'
+  | 'expression'
+  | 'accumulator'
+  | 'constructor'
+  | 'value'
+  | 'literal'
+  | 'enum'
+  | 'typeAlias'
+  | 'collection'
+  | 'method'
+  | 'variable'
+
+export type Suggestion = {
+  label: string
+  description?: string
+  /** Markdown. */
+  documentation?: string
+  kind: SuggestionKind
+  insertText: string
+  /** `insertText` is Monaco snippet syntax; otherwise plain text. */
+  snippet: boolean
+  filterText: string
+  /** `<tier a-e><4-digit rank>`. */
+  sortText: string
+  preselect?: boolean
+  /** Re-open suggestions after inserting. */
+  retrigger?: boolean
+}
+
+export type SuggestEnv = {
+  coll: string
+  collections: readonly string[]
+  /** Effective schema of a collection; null when unknown or not loaded. */
+  schemaOf: (coll: string) => CollectionSchema | null
+  uuidEncoding: UuidEncoding
+  timezone: string
+  now: Date
+  shellMethods: readonly string[]
+  cursorMethods: readonly string[]
+  /** Cursor methods allowed after `aggregate(…)`. */
+  aggregateCursorMethods: readonly string[]
+  /** `db.`-prefixed shell accessor of a collection, e.g. `db.users` or `db.getCollection("my logs")`. */
+  collectionAccessor: (coll: string) => string
+}
+
+export type SuggestTrigger = { kind: 'invoke' } | { kind: 'character'; char: string }
+
+/** `range` is the text offsets the chosen item replaces. */
+export type SuggestResult = { items: Suggestion[]; range: { start: number; end: number } }
+
+/**
+ * Ranked suggestions for a classified cursor position; empty when `trigger` does not fit the position.
+ * @param env collection names, schemas and display settings of the editor
+ * @returns items plus the replace range; the range is valid even when items are empty
+ */
+export function suggest(
+  ctx: CompletionContext,
+  env: SuggestEnv,
+  trigger: SuggestTrigger
+): SuggestResult {
+  const range = replaceRange(ctx)
+  if (ctx.position.at === 'none') return { items: [], range }
+  const char = trigger.kind === 'character' ? trigger.char : null
+  if (char !== null && !triggerFits(ctx, char)) return { items: [], range }
+  const builder = new Builder(ctx, env)
+  const items = builder.build()
+  // The generic constructors of an unsampled field are not worth opening for a typed colon or space.
+  if ((char === ':' || char === ' ') && builder.unknownField) return { items: [], range }
+  return { items, range }
+}
+
+type At = Position['at']
+type Tier = 'a' | 'b' | 'c' | 'd' | 'e'
+type Item = Omit<Suggestion, 'sortText'>
+type Ctor = Pick<
+  Suggestion,
+  'label' | 'insertText' | 'snippet' | 'filterText' | 'kind' | 'retrigger' | 'preselect'
+>
+type Sample = { value: unknown; text: string; filter: string; count: number }
+type FieldInfo = Pick<Item, 'description' | 'documentation'>
+
+const KEY_POSITIONS = new Set<At>([
+  'queryKey',
+  'operatorKey',
+  'elemMatchKey',
+  'textKey',
+  'jsonSchemaKey',
+  'geoKey',
+  'projectionKey',
+  'projectionOperatorKey',
+  'sortKey',
+  'stageKey',
+  'stageArgKey',
+  'newFieldKey',
+  'accumulatorKey',
+  'expressionKey',
+  'operatorArgKey',
+  'documentKey',
+  'updateKey',
+  'updateFieldKey',
+  'arrayFilterKey',
+  'bulkOperationKey'
+])
+const VALUE_POSITIONS = new Set<At>([
+  'rootValue',
+  'queryValue',
+  'ctorArg',
+  'typeAlias',
+  'literal',
+  'projectionValue',
+  'sortValue',
+  'expressionValue',
+  'fieldName',
+  'collectionName',
+  'documentValue',
+  'updateValue'
+])
+const DOCUMENT_POSITIONS = new Set<At>(['documentKey', 'documentValue'])
+const SHELL_DOT_POSITIONS = new Set<At>(['shellCollection', 'shellMethod', 'shellCursorMethod'])
+const DOTTED_VALUE_POSITIONS = new Set<At>(['expressionValue', 'fieldName', 'projectionValue'])
+const EMPTY_SLOT_FOLLOWERS = new Set(['', ',', '}', ']'])
+const ARRAY_OPERATORS = new Set(['$in', '$nin', '$all'])
+const COMPARABLE = new Set<BsonTypeName>([
+  'int',
+  'long',
+  'double',
+  'decimal',
+  'date',
+  'string',
+  'objectId',
+  'timestamp',
+  'uuid'
+])
+const DESCENDING_SORT = new Set<BsonTypeName>(['date', 'objectId', 'timestamp'])
+const UNKNOWN_FIELD_TYPES: readonly BsonTypeName[] = [
+  'objectId',
+  'date',
+  'uuid',
+  'uuidLegacy',
+  'long',
+  'decimal',
+  'int',
+  'timestamp',
+  'regex',
+  'string',
+  'bool',
+  'null',
+  'object',
+  'array',
+  'binData',
+  'minKey',
+  'maxKey'
+]
+const VARIABLE_PATH = /^\$\$(\w+)\.(.*)$/
+// Schemas and their fields never change once built, so work derived from them is kept with them.
+const FIELD_INFOS = new WeakMap<SchemaField, Map<string, FieldInfo>>()
+const RANKED_FIELDS = new WeakMap<CollectionSchema, [string, SchemaField][]>()
+
+function replaceRange(ctx: CompletionContext): { start: number; end: number } {
+  const { token } = ctx
+  const isKey = KEY_POSITIONS.has(ctx.position.at)
+  // Keys re-insert the closing quote they replace; values insert content only and keep it.
+  if (token.closeQuoteEnd !== null) {
+    return { start: token.start, end: isKey ? token.closeQuoteEnd : token.closeQuoteEnd - 1 }
+  }
+  return { start: token.start, end: isKey && !token.quote ? token.dottedEnd : token.wordEnd }
+}
+
+function triggerFits(ctx: CompletionContext, char: string): boolean {
+  const { position, token } = ctx
+  const at = position.at
+  const isKey = KEY_POSITIONS.has(at)
+  // Enter accepts the preselected item, so a typed colon or space must not offer to replace a value.
+  const emptySlot =
+    token.prevNonBlank === ':' &&
+    token.wordEnd === token.cursor &&
+    EMPTY_SLOT_FOLLOWERS.has(token.nextChar)
+  if (ctx.kind === 'document') {
+    if (char === '"' || char === "'") return at === 'documentKey'
+    if (char === ':' || char === ' ') return at === 'documentValue' && emptySlot
+    return false
+  }
+  switch (char) {
+    case '"':
+    case "'":
+      return isKey || VALUE_POSITIONS.has(at)
+    case '$':
+      return isKey || at === 'expressionValue' || (at === 'projectionValue' && token.quote !== null)
+    case ':':
+    case ' ':
+      return VALUE_POSITIONS.has(at) && emptySlot
+    case '.':
+      return (
+        SHELL_DOT_POSITIONS.has(at) ||
+        ((isKey || DOTTED_VALUE_POSITIONS.has(at)) && token.prefix.includes('.'))
+      )
+    case '{':
+      return isKey
+    case '[':
+      return (
+        at === 'stageElement' ||
+        at === 'bulkOperationElement' ||
+        (position.at === 'queryValue' && position.inArray)
+      )
+    default:
+      return false
+  }
+}
+
+class Builder {
+  /** The value items are only the generic constructors of an unsampled field. */
+  unknownField = false
+  private readonly items: Suggestion[] = []
+  private readonly labels = new Set<string>()
+  private readonly ranks: Record<Tier, number> = { a: 0, b: 0, c: 0, d: 0, e: 0 }
+  private readonly flows = new Map<FieldSource, CollectionSchema | null>()
+  private readonly inString: boolean
+  /** Queries compare numbers across types; documents (the document editor, inserts, update values) keep exact types. */
+  private readonly query: boolean
+
+  constructor(
+    private readonly ctx: CompletionContext,
+    private readonly env: SuggestEnv
+  ) {
+    this.inString = ctx.token.quote !== null
+    this.query = ctx.kind !== 'document' && !DOCUMENT_POSITIONS.has(ctx.position.at)
+  }
+
+  build(): Suggestion[] {
+    const p = this.ctx.position
+    switch (p.at) {
+      case 'rootValue':
+        this.rootValue(p.expect)
+        break
+      case 'queryKey':
+        this.fieldKeys(p.source, p.present, p.base, { childrenOnly: p.childrenOnly })
+        if (p.topLevel && !this.ctx.token.prefix.includes('.')) {
+          const tier = this.ctx.token.prefix.startsWith('$') ? 'a' : 'c'
+          this.keyDefs(QUERY_TOP_OPERATORS, p.present, tier, 'operator')
+        }
+        break
+      case 'operatorKey':
+        this.operatorKeys(p.source, p.field, p.present)
+        break
+      case 'elemMatchKey':
+        this.elemMatchKeys(p.source, p.field, p.present)
+        break
+      case 'queryValue':
+        this.queryValue(p)
+        break
+      case 'ctorArg':
+        this.ctorArg(p.source, p.field, p.ctor)
+        break
+      case 'typeAlias':
+        this.typeAliases(p.source, p.field)
+        break
+      case 'literal':
+        this.literals(p.values, p.preferred)
+        break
+      case 'textKey':
+        this.keyDefs(TEXT_KEYS, p.present, 'c', 'operator')
+        break
+      case 'jsonSchemaKey':
+        this.keyDefs(JSON_SCHEMA_KEYS, p.present, 'c', 'literal')
+        break
+      case 'geoKey':
+        this.keyDefs(GEO_KEYS, p.present, 'c', 'operator')
+        break
+      case 'projectionKey':
+      case 'sortKey':
+        this.fieldKeys(p.source, p.present, '', { pinId: true })
+        break
+      case 'projectionValue':
+        this.projectionValue(p.source, p.field, p.mode)
+        break
+      case 'projectionOperatorKey':
+        this.projectionOperatorKeys(p.source, p.field, p.present)
+        break
+      case 'sortValue':
+        this.sortValue(p.source, p.field)
+        break
+      case 'stageElement':
+        this.stageElements(p.stageIndex, p.nested, p.finalWrite === true)
+        break
+      case 'stageKey':
+        if (p.present.length === 0) this.stageKeys(p.stageIndex, p.nested, p.finalWrite === true)
+        break
+      case 'stageArgKey':
+        this.argKeys(p.stage, p.present)
+        break
+      case 'operatorArgKey':
+        this.argKeys(p.operator, p.present)
+        break
+      case 'newFieldKey':
+        this.newFieldKeys(p.source, p.present, p.group)
+        break
+      case 'accumulatorKey':
+        this.accumulatorKeys(p.window, p.present)
+        break
+      case 'expressionKey':
+        if (p.present.some((key) => key.startsWith('$'))) break
+        if (p.literalBase !== undefined) {
+          this.fieldKeys(p.source, p.present, p.literalBase, { childrenOnly: true })
+        }
+        this.expressionKeys(p.present, 'c', this.preferredClass(p.prefer))
+        break
+      case 'expressionValue':
+        this.expressionValue(p.source, p.vars, p.prefer)
+        break
+      case 'fieldName':
+        this.fieldNames(p.source, p.prefer, p.renaming)
+        break
+      case 'collectionName':
+        this.collectionNames()
+        break
+      case 'shellRoot':
+        this.shellRoot()
+        break
+      case 'shellCollection':
+        this.shellCollections()
+        break
+      case 'shellMethod':
+        this.collectionSegments(p.coll)
+        this.methods(this.env.shellMethods)
+        break
+      case 'shellCursorMethod': {
+        const allowed =
+          p.head === 'find'
+            ? this.env.cursorMethods
+            : p.head === 'aggregate'
+              ? this.env.aggregateCursorMethods
+              : []
+        this.methods(allowed.filter((m) => !p.used.includes(m)))
+        break
+      }
+      case 'documentKey':
+        this.documentKeys(p.coll, p.path, p.present, p.modifiersOf)
+        break
+      case 'documentValue': {
+        const schema = this.env.schemaOf(p.coll)
+        this.valueModel(
+          schema ? resolveSchemaField(schema, p.path) : undefined,
+          schema,
+          [],
+          p.element
+        )
+        if (p.modifiersOf && !this.inString) {
+          this.addTemplate(
+            'c',
+            '{ $each: [ … ] }',
+            `{ ${this.innerKey('$each')}: [$0] }`,
+            '$each',
+            true
+          )
+        }
+        break
+      }
+      case 'updateKey':
+        this.keyDefs(UPDATE_OPERATORS, p.present, 'c', 'operator')
+        break
+      case 'updateFieldKey':
+        this.updateFieldKeys(p.source, p.op, p.present)
+        break
+      case 'updateValue':
+        this.updateValue(p.source, p.op, p.field)
+        break
+      case 'arrayFilterKey':
+        this.arrayFilterKeys(p.source, p.identifiers, p.present)
+        break
+      case 'bulkOperationElement':
+        if (!this.inString) this.bulkOperations(true)
+        break
+      case 'bulkOperationKey':
+        this.bulkOperations(false)
+        break
+    }
+    return this.items
+  }
+
+  private add(tier: Tier, item: Item): void {
+    if (this.labels.has(item.label)) return
+    this.labels.add(item.label)
+    const suggestion: Suggestion = {
+      ...item,
+      sortText: `${tier}${String(this.ranks[tier]++).padStart(4, '0')}`
+    }
+    if (!item.preselect || this.items.some((i) => i.preselect)) delete suggestion.preselect
+    if (!item.retrigger) delete suggestion.retrigger
+    this.items.push(suggestion)
+  }
+
+  private flow(source: FieldSource): CollectionSchema | null {
+    if (!this.flows.has(source)) {
+      const base = this.env.schemaOf(source.coll)
+      this.flows.set(
+        source,
+        source.stages.length === 0 ? base : applyStages(base, source.stages, this.env.schemaOf)
+      )
+    }
+    return this.flows.get(source) ?? null
+  }
+
+  private field(
+    source: FieldSource,
+    path: string
+  ): { field: SchemaField | undefined; schema: CollectionSchema | null } {
+    const schema = this.flow(source)
+    return { field: schema ? resolveSchemaField(schema, path) : undefined, schema }
+  }
+
+  /** Type class `prefer` asks for; a referenced field stands for its own (element) type. */
+  private preferredClass(prefer: Prefer | undefined): TypeClass | null {
+    if (prefer === undefined) return null
+    if (typeof prefer === 'string') return prefer
+    const { field } = this.field(prefer.source, prefer.path)
+    const type = field ? queryType(field) : null
+    // Numbers compare across numeric types.
+    return type !== null && NUMERIC_TYPES.has(type) ? 'number' : type
+  }
+
+  /** A key in the editor's style, then `: ` and `template` unless a colon already follows. */
+  private keyInsert(
+    name: string,
+    template: string | null,
+    retrigger: boolean
+  ): Pick<Item, 'insertText' | 'snippet' | 'retrigger'> {
+    const { token, keyQuote } = this.ctx
+    const withValue = !token.colonFollows
+    const snippet = withValue && template !== null
+    const text = token.quote
+      ? escapeInQuotes(name, token.quote) + token.quote
+      : keyQuote === '"' || !isBareKey(name)
+        ? JSON.stringify(name)
+        : name
+    const head = snippet ? snippetEscape(text) : text
+    if (!withValue) return { insertText: head, snippet: false, retrigger: false }
+    return { insertText: `${head}: ${template ?? ''}`, snippet, retrigger }
+  }
+
+  /** Renders a key inside a template in the same style as the key being inserted. */
+  private readonly innerKey = (key: string): string => {
+    const quote = this.ctx.token.quote ?? this.ctx.keyQuote
+    return snippetEscape(quote ? `${quote}${escapeInQuotes(key, quote)}${quote}` : key)
+  }
+
+  private keyItem(def: KeyDef, kind: SuggestionKind): Item {
+    const template = def.template ? def.template(this.innerKey) : null
+    return {
+      label: def.name,
+      kind,
+      ...this.keyInsert(def.name, template, def.retrigger ?? template === null),
+      filterText: def.name,
+      documentation: def.doc
+    }
+  }
+
+  private keyDefs(
+    defs: readonly KeyDef[],
+    present: readonly string[],
+    tier: Tier,
+    kind: SuggestionKind
+  ): void {
+    for (const def of defs) if (!present.includes(def.name)) this.add(tier, this.keyItem(def, kind))
+  }
+
+  /** Field paths of `source` as keys relative to `base`; a dotted prefix narrows to that parent's children. */
+  private fieldKeys(
+    source: FieldSource,
+    present: readonly string[],
+    base: string,
+    options: { pinId?: boolean; childrenOnly?: boolean } = {}
+  ): void {
+    const schema = this.flow(source)
+    const prefix = this.ctx.token.prefix
+    const dot = prefix.lastIndexOf('.')
+    let entries: [string, SchemaField | undefined][] = []
+    if (schema && options.childrenOnly) {
+      if (dot === -1) entries = childFields(schema, base).map((f) => [lastSegment(f.path), f])
+    } else if (schema && dot !== -1) {
+      const parent = prefix.slice(0, dot)
+      entries = childFields(schema, join(base, parent)).map((f) => [
+        `${parent}.${lastSegment(f.path)}`,
+        f
+      ])
+    } else if (schema) {
+      const under = base === '' ? '' : `${base}.`
+      entries = addressableFields(schema)
+        .filter((f) => f.path.startsWith(under))
+        .map((f) => [f.path.slice(under.length), f])
+    }
+    // Stored documents always have an _id; a known stage output has one only if it lists it.
+    const idPossible = source.stages.length === 0 || !schema
+    if (options.pinId && idPossible && dot === -1 && !entries.some(([name]) => name === '_id'))
+      entries.push(['_id', undefined])
+    this.addFieldKeys(entries, present, schema)
+  }
+
+  /** Field paths an update operator changes; fields inside array elements are addressed through `$[]`. */
+  private updateFieldKeys(source: FieldSource, op: string, present: readonly string[]): void {
+    const schema = this.flow(source)
+    if (!schema) return
+    const prefix = this.ctx.token.prefix
+    const dot = prefix.lastIndexOf('.')
+    let entries: [string, SchemaField][]
+    if (dot === -1) {
+      entries = addressableFields(schema).map((f) => [elementPath(schema, f.path), f])
+    } else {
+      const parent = prefix.slice(0, dot)
+      const path = withoutPositional(parent)
+      // Updates do not reach into array elements on their own; a typed positional segment does.
+      const through = isArrayField(schema, path) && !POSITIONAL_SEGMENT.test(lastSegment(parent))
+      entries = childFields(schema, path).map((f) => [
+        `${parent}${through ? '.$[]' : ''}.${lastSegment(f.path)}`,
+        f
+      ])
+    }
+    entries = entries.filter(([name]) => {
+      // Updates cannot change _id; only the insert of an upsert sets it.
+      if (op !== '$setOnInsert' && (name === '_id' || name.startsWith('_id.'))) return false
+      // $rename cannot move fields of array elements.
+      return op !== '$rename' || withoutPositional(name) === name
+    })
+    const prefer = UPDATE_OPERATORS.find((def) => def.name === op)?.fields ?? null
+    this.addFieldKeys(entries, present, schema, prefer)
+  }
+
+  /** Field keys ranked by presence, `prefer`-typed fields first; present ones are left out. */
+  private addFieldKeys(
+    entries: [string, SchemaField | undefined][],
+    present: readonly string[],
+    schema: CollectionSchema | null,
+    prefer: TypeClass | null = null
+  ): void {
+    for (const [name, field] of preferred(rankFields(entries), prefer)) {
+      if (present.includes(name)) continue
+      this.add('b', {
+        label: name,
+        kind: 'field',
+        ...this.keyInsert(name, null, true),
+        filterText: name,
+        ...this.fieldInfo(field, schema)
+      })
+    }
+  }
+
+  /** `name` and `name.<subfield>` keys for the array each `$[name]` of the update stands for. */
+  private arrayFilterKeys(
+    source: FieldSource,
+    identifiers: readonly ArrayIdentifier[],
+    present: readonly string[]
+  ): void {
+    const schema = this.flow(source)
+    const prefix = this.ctx.token.prefix
+    const dot = prefix.lastIndexOf('.')
+    for (const { name, path } of identifiers) {
+      const entries: [string, SchemaField | undefined][] = []
+      if (dot === -1) {
+        entries.push([name, schema ? resolveSchemaField(schema, path) : undefined])
+        const under = `${path}.`
+        for (const field of schema ? addressableFields(schema) : []) {
+          if (field.path.startsWith(under)) {
+            entries.push([`${name}.${field.path.slice(under.length)}`, field])
+          }
+        }
+      } else {
+        const parent = prefix.slice(0, dot)
+        const [head, ...rest] = parent.split('.')
+        if (head !== name || !schema) continue
+        const parentPath = rest.length === 0 ? path : join(path, rest.join('.'))
+        for (const field of childFields(schema, parentPath)) {
+          entries.push([`${parent}.${lastSegment(field.path)}`, field])
+        }
+      }
+      this.addFieldKeys(entries, present, schema)
+    }
+  }
+
+  private operatorKeys(source: FieldSource, path: string, present: readonly string[]): void {
+    const { field, schema } = this.field(source, path)
+    const { prefix } = this.ctx.token
+    // A typed letter matches inside operator names; only fitting operators are worth that.
+    const fittingOnly = prefix !== '' && !prefix.startsWith('$')
+    for (const op of FIELD_OPERATORS) {
+      if (present.includes(op.name)) continue
+      if (op.fits === 'regexOption' && !present.includes('$regex')) continue
+      const fit = !field || fits(op.fits, field, schema)
+      if (fit || !fittingOnly) this.add(fit ? 'c' : 'e', this.keyItem(op, 'operator'))
+    }
+    const type = field ? queryType(field) : null
+    const wrapper = type ? EJSON_WRAPPERS[type] : undefined
+    if (wrapper && !present.includes(wrapper.name))
+      this.add('e', this.keyItem(wrapper, 'constructor'))
+  }
+
+  private elemMatchKeys(source: FieldSource, path: string, present: readonly string[]): void {
+    this.fieldKeys(source, present, path)
+    const { field, schema } = this.field(source, path)
+    const element = field
+      ? { ...field, types: field.elementTypes ?? {}, elementTypes: undefined }
+      : undefined
+    for (const op of FIELD_OPERATORS) {
+      if (present.includes(op.name)) continue
+      if (op.fits === 'regexOption' && !present.includes('$regex')) continue
+      if (!element || fits(op.fits, element, schema)) this.add('c', this.keyItem(op, 'operator'))
+    }
+    this.keyDefs(
+      QUERY_TOP_OPERATORS.filter((op) => ['$and', '$or', '$nor'].includes(op.name)),
+      present,
+      'c',
+      'operator'
+    )
+  }
+
+  private stageKeys(stageIndex: number, nested: Nesting | undefined, finalWrite: boolean): void {
+    for (const stage of STAGES) {
+      if (stageRuns(stage, stageIndex, nested, finalWrite)) {
+        this.add(stageTier(stage), this.keyItem(stage, 'stage'))
+      }
+    }
+  }
+
+  private argKeys(owner: string, present: readonly string[]): void {
+    for (const spec of ARG_SPECS[owner] ?? []) {
+      if (present.includes(spec.name)) continue
+      if (spec.excludes !== undefined && present.includes(spec.excludes)) continue
+      const { template, retrigger } = argTemplate(spec.kind)
+      this.add(spec.required ? 'b' : 'c', {
+        label: spec.name,
+        kind: 'field',
+        ...this.keyInsert(spec.name, template, retrigger),
+        filterText: spec.name,
+        description: spec.required ? 'required' : undefined
+      })
+    }
+  }
+
+  private newFieldKeys(source: FieldSource, present: readonly string[], group: boolean): void {
+    if (group && !present.includes('_id')) {
+      this.add('b', {
+        label: '_id',
+        kind: 'field',
+        ...this.keyInsert('_id', null, true),
+        filterText: '_id'
+      })
+    }
+    const schema = this.flow(source)
+    if (!schema) return
+    for (const [name, field] of rankedFields(schema)) {
+      if (present.includes(name)) continue
+      this.add('e', {
+        label: name,
+        kind: 'field',
+        ...this.keyInsert(name, null, true),
+        filterText: name,
+        ...this.fieldInfo(field, schema),
+        // A $group outputs only its _id and accumulators, so nothing of the input is overwritten.
+        ...(group ? {} : { description: 'overwrite' })
+      })
+    }
+  }
+
+  private accumulatorKeys(window: boolean, present: readonly string[]): void {
+    // An accumulator object holds one operator, plus the window bounds in a window function.
+    if (!present.some((key) => key !== 'window')) {
+      for (const def of ACCUMULATORS) {
+        if (def.windowOnly && !window) continue
+        this.add('c', this.keyItem(def, 'accumulator'))
+      }
+    }
+    if (window && !present.includes('window')) this.add('d', this.keyItem(WINDOW_KEY, 'literal'))
+  }
+
+  /** Expression operators at `tier`, those returning the `preferred` type class at tier `b`. */
+  private expressionKeys(
+    present: readonly string[],
+    tier: Tier,
+    preferred: TypeClass | null = null
+  ): void {
+    const operators = [...EXPRESSION_OPERATORS].sort((a, b) => compareText(a.name, b.name))
+    for (const op of operators) {
+      if (present.includes(op.name)) continue
+      const { template, retrigger } = formTemplate(op.form)
+      this.add(preferred !== null && inClass(op.returns, preferred) ? 'b' : tier, {
+        label: op.name,
+        kind: 'expression',
+        ...this.keyInsert(op.name, template, retrigger),
+        filterText: op.name,
+        description: op.returns,
+        documentation: op.doc
+      })
+    }
+  }
+
+  private projectionOperatorKeys(
+    source: FieldSource,
+    path: string,
+    present: readonly string[]
+  ): void {
+    this.fieldKeys(source, present, path)
+    const { field } = this.field(source, path)
+    if (field && dominantType(field.types) === 'array') {
+      this.keyDefs(PROJECTION_OPERATORS, present, 'c', 'operator')
+      this.expressionKeys(present, 'e')
+      return
+    }
+    // Any other field is computed; expressions go first, so `$slice` keeps its expression form.
+    const meta = PROJECTION_OPERATORS.filter((def) => def.name === '$meta')
+    this.keyDefs(meta, present, 'c', 'operator')
+    this.expressionKeys(present, 'c')
+    this.keyDefs(PROJECTION_OPERATORS, present, 'e', 'operator')
+  }
+
+  private documentKeys(
+    coll: string,
+    path: string,
+    present: readonly string[],
+    modifiersOf: ArrayModifierOwner | undefined
+  ): void {
+    if (modifiersOf) {
+      // The object holds either modifiers or the fields of a pushed element document.
+      const modifiers = present.some((key) => key.startsWith('$'))
+      if (modifiers || present.length === 0) {
+        this.keyDefs(ARRAY_MODIFIERS[modifiersOf], present, 'c', 'operator')
+      }
+      if (modifiers) return
+    }
+    const schema = this.env.schemaOf(coll)
+    if (!schema) return
+    // Keys of a map-like object are data, not a fixed set worth suggesting.
+    if (path !== '' && resolveSchemaField(schema, path)?.mapLike) return
+    const entries = childFields(schema, path).map((f): [string, SchemaField] => [
+      lastSegment(f.path),
+      f
+    ])
+    this.addFieldKeys(entries, present, schema)
+  }
+
+  /** A literal in a value slot; a space follows a colon typed without one. */
+  private valueText(literal: string): string {
+    return (this.ctx.token.charBefore === ':' ? ' ' : '') + literal
+  }
+
+  private quotedContent(text: string): string {
+    const { quote, closeQuoteEnd } = this.ctx.token
+    const content = escapeInQuotes(text, quote ?? '"')
+    // Strings never span lines, so no closing quote on the cursor line means none at all.
+    return quote !== null && closeQuoteEnd === null ? content + quote : content
+  }
+
+  /** `text` as a string literal in a value slot, or as the content of the string the cursor is in. */
+  private stringText(text: string): string {
+    return this.inString ? this.quotedContent(text) : this.valueText(JSON.stringify(text))
+  }
+
+  private rootValue(expect: 'object' | 'array'): void {
+    if (this.inString) return
+    const object = expect === 'object'
+    this.add('a', {
+      label: object ? '{ … }' : '[ … ]',
+      kind: 'value',
+      insertText: this.valueText(object ? '{ $0 }' : '[$0]'),
+      snippet: true,
+      filterText: object ? '{' : '[',
+      preselect: true,
+      retrigger: true
+    })
+  }
+
+  private queryValue(p: Extract<Position, { at: 'queryValue' }>): void {
+    if (p.operator === '$size') return
+    const { field, schema } = this.field(p.source, p.field)
+    if (p.operator === '$regex') {
+      if (!this.inString)
+        for (const ctor of this.constructors('regex', field))
+          this.add('a', { ...ctor, preselect: true })
+      return
+    }
+    if (p.operator !== null && ARRAY_OPERATORS.has(p.operator) && !p.inArray) {
+      this.arrayOfValues(field)
+      return
+    }
+    this.valueModel(field, schema, p.siblings, true)
+  }
+
+  /** `[<constructor>]` for `$in` / `$nin` / `$all` before the array is typed. */
+  private arrayOfValues(field: SchemaField | undefined): void {
+    if (this.inString) return
+    if (!field) this.unknownField = true
+    const type = field ? queryType(field) : null
+    const ctor = type ? this.constructors(type, field).find((c) => c.snippet) : undefined
+    this.add('a', {
+      label: ctor ? `[${ctor.label}]` : '[ … ]',
+      kind: ctor ? 'constructor' : 'value',
+      // The array, not the constructor inside it, follows the colon.
+      insertText: this.valueText(ctor ? `[${ctor.insertText.trimStart()}]` : '[$0]'),
+      snippet: true,
+      filterText: '[',
+      preselect: true,
+      retrigger: true
+    })
+  }
+
+  /** Constructor for the field's type, sample values, minor-type constructors and null. */
+  private valueModel(
+    field: SchemaField | undefined,
+    schema: CollectionSchema | null,
+    siblings: readonly string[],
+    element: boolean
+  ): void {
+    if (!field) {
+      if (!this.inString) this.unknownValues()
+      return
+    }
+    const counts =
+      (this.query || element) && dominantType(field.types) === 'array'
+        ? (field.elementTypes ?? {})
+        : field.types
+    const type = dominantType(counts)
+    // Tracked values of an array field are its elements, not candidates for the whole value.
+    const samples = type === 'array' ? [] : this.samples(field, siblings)
+    if (this.inString) {
+      for (const sample of samples) {
+        if (typeof sample.value !== 'string') continue
+        this.add('b', {
+          label: sample.text,
+          kind: 'value',
+          insertText: this.quotedContent(sample.value),
+          snippet: false,
+          filterText: sample.value,
+          description: `${sample.count}×`
+        })
+      }
+      return
+    }
+    const total = sumCounts(counts)
+    const info = this.fieldInfo(field, schema)
+    const ctors = type ? this.constructors(type, field) : []
+    const share = type ? percent(counts[type] ?? 0, total) : 0
+    const values = field.values ?? []
+    const enumLike =
+      !field.valuesTruncated && values.length > 0 && sumValueCounts(values) >= 2 * values.length
+    // A string enum's most frequent value fits better than the empty "…" constructor.
+    const sampleFirst = enumLike && (ctors.length === 0 || type === 'string')
+    for (const ctor of ctors) {
+      this.add('a', {
+        ...ctor,
+        preselect: !sampleFirst && (ctor.preselect ?? true),
+        description: `${type} · ${share}%`,
+        documentation: info.documentation
+      })
+    }
+    const shown = enumLike ? samples : samples.slice(0, 3)
+    shown.forEach((sample, i) => {
+      this.add(enumLike ? 'b' : 'd', {
+        label: sample.text,
+        kind: 'value',
+        insertText: this.valueText(sample.text),
+        snippet: false,
+        filterText: sample.filter,
+        description: enumLike ? `${sample.count}×` : 'example',
+        preselect: sampleFirst && i === 0
+      })
+    })
+    for (const [minor, count] of sortedTypes(counts)) {
+      if (minor === type || minor === 'null' || minor === 'undefined') continue
+      for (const ctor of this.constructors(minor, field)) {
+        this.add('d', {
+          ...ctor,
+          preselect: false,
+          description: `${minor} · ${percent(count, total)}%`
+        })
+      }
+    }
+    if (type !== 'null' && (this.query || (counts.null ?? 0) > 0)) {
+      this.add('d', {
+        label: 'null',
+        kind: 'literal',
+        insertText: this.valueText('null'),
+        snippet: false,
+        filterText: 'null'
+      })
+    }
+  }
+
+  private unknownValues(): void {
+    this.unknownField = true
+    for (const type of UNKNOWN_FIELD_TYPES) {
+      if (type === 'uuidLegacy' && this.env.uuidEncoding !== 'java') continue
+      for (const ctor of this.constructors(type, undefined))
+        this.add('e', { ...ctor, preselect: false })
+    }
+  }
+
+  private constructors(type: BsonTypeName, field: SchemaField | undefined): Ctor[] {
+    const snippet = (label: string, text: string, filterText: string, retrigger = false): Ctor => ({
+      label,
+      insertText: this.valueText(text),
+      snippet: true,
+      filterText,
+      kind: 'constructor',
+      retrigger
+    })
+    const plain = (text: string, kind: SuggestionKind, preselect?: boolean): Ctor => ({
+      label: text,
+      insertText: this.valueText(text),
+      snippet: false,
+      filterText: text,
+      kind,
+      preselect
+    })
+    switch (type) {
+      case 'objectId':
+        return [snippet('ObjectId("…")', 'ObjectId("$0")', 'ObjectId')]
+      case 'date': {
+        const now = snippetEscape(formatIsoInZone(this.env.now, this.env.timezone))
+        return [snippet('ISODate("…")', `ISODate("\${0:${now}}")`, 'ISODate')]
+      }
+      case 'uuid':
+        return [snippet('UUID("…")', 'UUID("$0")', 'UUID')]
+      case 'uuidLegacy':
+        return this.env.uuidEncoding === 'java'
+          ? [snippet('JUUID("…")', 'JUUID("$0")', 'JUUID')]
+          : [snippet('BinData(3, "…")', 'BinData(3, "$0")', 'BinData')]
+      case 'binData':
+        return [snippet('BinData(0, "…")', 'BinData(0, "$0")', 'BinData')]
+      case 'long':
+        return [snippet('NumberLong("…")', 'NumberLong("${0:0}")', 'NumberLong')]
+      case 'decimal':
+        return [snippet('NumberDecimal("…")', 'NumberDecimal("${0:0}")', 'NumberDecimal')]
+      case 'int':
+        // Numbers compare across numeric types in queries, so only the document editor needs NumberInt.
+        return this.query ? [] : [snippet('NumberInt(…)', 'NumberInt(${0:0})', 'NumberInt')]
+      case 'timestamp': {
+        const seconds = Math.floor(this.env.now.getTime() / 1000)
+        return [snippet('Timestamp(…)', `Timestamp(\${1:${seconds}}, \${2:1})`, 'Timestamp')]
+      }
+      case 'regex':
+        return [snippet('/…/', '/$0/', '/')]
+      case 'string':
+        return [snippet('"…"', '"$0"', '"')]
+      case 'bool': {
+        const trues = valueCount(field, 'true')
+        const falses = valueCount(field, 'false')
+        return [
+          plain('true', 'literal', trues >= falses),
+          plain('false', 'literal', falses > trues)
+        ]
+      }
+      case 'null':
+        return [plain('null', 'literal')]
+      case 'object':
+        return [snippet('{ … }', '{ $0 }', '{', true)]
+      case 'array':
+        return [snippet('[ … ]', '[$0]', '[', true)]
+      case 'minKey':
+        return [plain('MinKey', 'constructor')]
+      case 'maxKey':
+        return [plain('MaxKey', 'constructor')]
+      case 'javascript':
+        return [snippet('Code("…")', 'Code("$0")', 'Code')]
+      default:
+        return []
+    }
+  }
+
+  /** Tracked values of `field` rendered as literals, minus those already in the enclosing array. */
+  private samples(field: SchemaField, siblings: readonly string[]): Sample[] {
+    const out: Sample[] = []
+    for (const { ejson, count } of field.values ?? []) {
+      const value = parseJson(ejson)
+      if (value === undefined) continue
+      const text = this.render(value)
+      if (siblings.includes(text)) continue
+      out.push({ value, text, filter: typeof value === 'string' ? value : text, count })
+    }
+    return out
+  }
+
+  private render(value: unknown): string {
+    if (this.query) {
+      const number = plainNumber(value)
+      if (number !== null) return number
+    }
+    return serializeMongoValue(value, {
+      uuidEncoding: this.env.uuidEncoding,
+      timezone: this.env.timezone,
+      indent: 0
+    })
+  }
+
+  private ctorArg(source: FieldSource, path: string | null, ctor: string): void {
+    const type = CONSTRUCTOR_TYPES[ctor]
+    if (path === null || !type) return
+    const { field } = this.field(source, path)
+    for (const { ejson } of field?.values ?? []) {
+      const value = parseJson(ejson)
+      if (classifyCanonical(value) !== type) continue
+      const arg = this.constructorArgument(value, type)
+      if (!arg || (this.inString && !arg.quoted)) continue
+      this.add('b', {
+        label: arg.text,
+        kind: 'value',
+        insertText: this.inString
+          ? this.quotedContent(arg.text)
+          : arg.quoted
+            ? JSON.stringify(arg.text)
+            : arg.text,
+        snippet: false,
+        filterText: arg.text,
+        description: 'example'
+      })
+    }
+  }
+
+  /** The single argument of a value's shell-helper rendering, e.g. the hex of `ObjectId("…")`. */
+  private constructorArgument(
+    value: unknown,
+    type: BsonTypeName
+  ): { text: string; quoted: boolean } | null {
+    const rendered = serializeMongoValue(value, {
+      uuidEncoding: this.env.uuidEncoding,
+      timezone: this.env.timezone,
+      indent: 0
+    })
+    const match = /^(\w+)\((.*)\)$/s.exec(rendered)
+    if (!match || CONSTRUCTOR_TYPES[match[1]!] !== type) return null
+    const inner = match[2]!
+    if (/^-?[\d.]+$/.test(inner)) return { text: inner, quoted: false }
+    const text = parseJson(inner)
+    return typeof text === 'string' ? { text, quoted: true } : null
+  }
+
+  private typeAliases(source: FieldSource, path: string): void {
+    const { field } = this.field(source, path)
+    const observed = field
+      ? sortedTypes(addCounts(field.types, field.elementTypes ?? {})).map(([type]) =>
+          typeAlias(type)
+        )
+      : []
+    observed.forEach((alias) => this.add('b', this.aliasItem(alias)))
+    TYPE_ALIASES.forEach((alias) => this.add('c', this.aliasItem(alias)))
+  }
+
+  private aliasItem(alias: string): Item {
+    return {
+      label: alias,
+      kind: 'typeAlias',
+      insertText: this.stringText(alias),
+      snippet: false,
+      filterText: alias
+    }
+  }
+
+  private literals(values: readonly string[], preferred: string | undefined): void {
+    for (const value of values) {
+      const quoted = value.startsWith('"')
+      if (this.inString && !quoted) continue
+      const content = quoted ? String(parseJson(value)) : value
+      this.add(value === preferred ? 'a' : 'b', {
+        label: value,
+        kind: quoted ? 'enum' : 'literal',
+        insertText: this.inString ? this.quotedContent(content) : this.valueText(value),
+        snippet: false,
+        filterText: content,
+        preselect: value === preferred
+      })
+    }
+  }
+
+  private projectionValue(
+    source: FieldSource,
+    path: string,
+    mode: 'include' | 'exclude' | null
+  ): void {
+    if (this.inString) {
+      this.fieldRefs(source, null, 'b')
+      return
+    }
+    const first = path === '_id' || mode === 'exclude' ? '0' : '1'
+    this.addLiteral('a', first, true)
+    this.addLiteral('b', first === '1' ? '0' : '1')
+    this.addLiteral('c', 'true')
+    this.addLiteral('c', 'false')
+    const { field } = this.field(source, path)
+    if (field && dominantType(field.types) === 'array') {
+      this.addTemplate(
+        'c',
+        `{ $slice: … }`,
+        `{ ${this.innerKey('$slice')}: \${0:10} }`,
+        '$slice',
+        false
+      )
+      this.addTemplate(
+        'c',
+        `{ $elemMatch: … }`,
+        `{ ${this.innerKey('$elemMatch')}: { $0 } }`,
+        '$elemMatch',
+        true
+      )
+    }
+    this.addTemplate(
+      'd',
+      '{ $meta: "textScore" }',
+      `{ ${this.innerKey('$meta')}: "textScore" }`,
+      '$meta',
+      false
+    )
+    this.fieldRefs(source, null, 'e')
+  }
+
+  private sortValue(source: FieldSource, path: string): void {
+    if (this.inString) return
+    const { field } = this.field(source, path)
+    const type = field ? queryType(field) : null
+    const descending = type !== null && DESCENDING_SORT.has(type)
+    this.addLiteral('a', descending ? '-1' : '1', true)
+    this.addLiteral('b', descending ? '1' : '-1')
+    this.addTemplate(
+      'd',
+      '{ $meta: "textScore" }',
+      `{ ${this.innerKey('$meta')}: "textScore" }`,
+      '$meta',
+      false
+    )
+  }
+
+  private addLiteral(tier: Tier, text: string, preselect = false): void {
+    this.add(tier, {
+      label: text,
+      kind: 'literal',
+      insertText: this.valueText(text),
+      snippet: false,
+      filterText: text,
+      preselect
+    })
+  }
+
+  private addTemplate(
+    tier: Tier,
+    label: string,
+    text: string,
+    filterText: string,
+    retrigger: boolean
+  ): void {
+    this.add(tier, {
+      label,
+      kind: 'value',
+      insertText: this.valueText(text),
+      snippet: true,
+      filterText,
+      retrigger
+    })
+  }
+
+  private stageElements(
+    stageIndex: number,
+    nested: Nesting | undefined,
+    finalWrite: boolean
+  ): void {
+    if (this.inString) return
+    for (const stage of STAGES) {
+      if (!stageRuns(stage, stageIndex, nested, finalWrite)) continue
+      const value = stage.template ? stage.template(this.innerKey) : '{ $0 }'
+      this.add(stageTier(stage), {
+        label: stage.name,
+        kind: 'stage',
+        insertText: this.valueText(`{ ${this.innerKey(stage.name)}: ${value} }`),
+        snippet: true,
+        filterText: stage.name,
+        documentation: stage.doc,
+        retrigger: stage.retrigger
+      })
+    }
+  }
+
+  /** Values of the update operators whose values are not documents. */
+  private updateValue(source: FieldSource, op: string, path: string): void {
+    if (this.inString) return
+    switch (op) {
+      case '$inc':
+        this.addLiteral('a', '1', true)
+        this.addLiteral('b', '-1')
+        break
+      case '$mul':
+        this.addLiteral('a', '2', true)
+        this.addLiteral('b', '-1')
+        break
+      case '$unset':
+        // The value is ignored; an empty string is the convention.
+        this.addLiteral('a', '""', true)
+        break
+      case '$pop':
+        for (const [tier, text, description] of [
+          ['a', '1', 'last element'],
+          ['b', '-1', 'first element']
+        ] as const) {
+          this.add(tier, {
+            label: text,
+            kind: 'literal',
+            insertText: this.valueText(text),
+            snippet: false,
+            filterText: text,
+            description,
+            preselect: tier === 'a'
+          })
+        }
+        break
+      case '$currentDate': {
+        const { field } = this.field(source, path)
+        const timestamp = field !== undefined && queryType(field) === 'timestamp'
+        this.addLiteral(timestamp ? 'b' : 'a', 'true', !timestamp)
+        for (const type of ['date', 'timestamp']) {
+          const preselect = timestamp && type === 'timestamp'
+          this.add(preselect ? 'a' : 'b', {
+            label: `{ $type: "${type}" }`,
+            kind: 'value',
+            insertText: this.valueText(`{ ${this.innerKey('$type')}: "${type}" }`),
+            snippet: true,
+            filterText: type,
+            preselect
+          })
+        }
+        break
+      }
+      case '$bit':
+        for (const operation of ['and', 'or', 'xor']) {
+          this.addTemplate(
+            'c',
+            `{ ${operation}: … }`,
+            `{ ${this.innerKey(operation)}: $0 }`,
+            operation,
+            false
+          )
+        }
+        break
+    }
+  }
+
+  /** The `bulkWrite` operations, as wrapped array elements or as the key of one. */
+  private bulkOperations(element: boolean): void {
+    for (const name of BULK_WRITE_OPERATIONS) {
+      const documentation = SHELL_METHODS[name]?.doc
+      this.add(
+        'c',
+        element
+          ? {
+              label: name,
+              kind: 'method',
+              insertText: this.valueText(`{ ${this.innerKey(name)}: { $0 } }`),
+              snippet: true,
+              filterText: name,
+              documentation,
+              retrigger: true
+            }
+          : {
+              label: name,
+              kind: 'method',
+              ...this.keyInsert(name, '{ $0 }', true),
+              filterText: name,
+              documentation
+            }
+      )
+    }
+  }
+
+  private expressionValue(
+    source: FieldSource,
+    vars: readonly Variable[],
+    prefer: Prefer | undefined
+  ): void {
+    const variablePath = VARIABLE_PATH.exec(this.ctx.token.prefix)
+    if (variablePath) {
+      this.variableFields(vars, variablePath[1]!, variablePath[2]!)
+      return
+    }
+    this.fieldRefs(source, this.preferredClass(prefer), 'b')
+    for (const name of [...vars.map((v) => v.name), ...SYSTEM_VARIABLES]) {
+      const ref = `$$${name}`
+      this.add('c', {
+        label: ref,
+        kind: 'variable',
+        insertText: this.stringText(ref),
+        snippet: false,
+        filterText: ref
+      })
+    }
+    if (this.inString) return
+    for (const literal of ['true', 'false', 'null']) this.addLiteral('d', literal)
+    this.add('d', {
+      label: '{ $operator }',
+      kind: 'expression',
+      insertText: this.valueText('{ $0 }'),
+      snippet: true,
+      filterText: '{',
+      retrigger: true
+    })
+  }
+
+  /** `$$name.<subfield>` references below the field variable `name` holds; `rest` is the path typed after it. */
+  private variableFields(vars: readonly Variable[], name: string, rest: string): void {
+    // An inner binding of a name shadows the outer ones.
+    const field = [...vars].reverse().find((v) => v.name === name)?.field
+    const schema = field ? this.flow(field.source) : null
+    if (!field || !schema) return
+    const dot = rest.lastIndexOf('.')
+    const path = dot === -1 ? field.path : join(field.path, rest.slice(0, dot))
+    const head = `$$${name}.${rest.slice(0, dot + 1)}`
+    const children = childFields(schema, path).map((f): [string, SchemaField] => [
+      lastSegment(f.path),
+      f
+    ])
+    for (const [child, info] of rankFields(children)) {
+      this.addFieldText('b', head + child, info, schema)
+    }
+  }
+
+  /** `"$path"` references to the fields of `source`, `prefer`-typed fields first. */
+  private fieldRefs(source: FieldSource, prefer: TypeClass | null, tier: Tier): void {
+    const schema = this.flow(source)
+    if (!schema) return
+    for (const [path, field] of preferred(rankedFields(schema), prefer)) {
+      this.addFieldText(tier, `$${path}`, field, schema)
+    }
+  }
+
+  private fieldNames(
+    source: FieldSource,
+    prefer: Prefer | undefined,
+    renaming: string | undefined
+  ): void {
+    const schema = this.flow(source)
+    if (!schema) return
+    for (const [path, field] of preferred(rankedFields(schema), this.preferredClass(prefer))) {
+      if (renaming !== undefined && !renamesTo(schema, renaming, path)) continue
+      this.addFieldText('b', path, field, schema)
+    }
+  }
+
+  /** A field path or reference inserted as a string value. */
+  private addFieldText(
+    tier: Tier,
+    text: string,
+    field: SchemaField,
+    schema: CollectionSchema
+  ): void {
+    this.add(tier, {
+      label: text,
+      kind: 'field',
+      insertText: this.stringText(text),
+      snippet: false,
+      filterText: text,
+      ...this.fieldInfo(field, schema)
+    })
+  }
+
+  private collectionNames(): void {
+    const item = (name: string): Item => ({
+      label: name,
+      kind: 'collection',
+      insertText: this.stringText(name),
+      snippet: false,
+      filterText: name
+    })
+    for (const name of this.env.collections) if (name !== this.env.coll) this.add('b', item(name))
+    this.add('c', item(this.env.coll))
+  }
+
+  private shellRoot(): void {
+    if (this.inString) return
+    const accessor = this.env.collectionAccessor(this.env.coll)
+    const escaped = snippetEscape(accessor)
+    this.add('a', {
+      label: `${accessor}.find({ … })`,
+      kind: 'method',
+      insertText: `${escaped}.find({ $0 })`,
+      snippet: true,
+      filterText: `${accessor}.find`,
+      preselect: true,
+      retrigger: true
+    })
+    this.add('b', {
+      label: 'db',
+      kind: 'variable',
+      insertText: 'db.',
+      snippet: false,
+      filterText: 'db',
+      retrigger: true
+    })
+    this.add('c', {
+      label: `${accessor}.aggregate([ … ])`,
+      kind: 'method',
+      insertText: `${escaped}.aggregate([$0])`,
+      snippet: true,
+      filterText: `${accessor}.aggregate`,
+      retrigger: true
+    })
+  }
+
+  private shellCollections(): void {
+    // Renaming the collection of an existing chain keeps its `.method(…)`.
+    const keepDot = this.ctx.token.nextChar === '.'
+    for (const name of [this.env.coll, ...this.env.collections]) {
+      const member = this.env.collectionAccessor(name).slice('db.'.length)
+      this.add(member === name ? 'b' : 'c', {
+        label: name,
+        kind: 'collection',
+        insertText: keepDot ? member : `${member}.`,
+        snippet: false,
+        filterText: name,
+        retrigger: !keepDot
+      })
+    }
+  }
+
+  /** Next name segments of dot-addressable collections below `coll`, e.g. `events` after `db.game.`. */
+  private collectionSegments(coll: string): void {
+    const keepDot = this.ctx.token.nextChar === '.'
+    const prefix = `${coll}.`
+    for (const name of this.env.collections) {
+      if (!name.startsWith(prefix) || this.env.collectionAccessor(name) !== `db.${name}`) continue
+      const segment = name.slice(prefix.length).split('.')[0]!
+      this.add('b', {
+        label: segment,
+        kind: 'collection',
+        insertText: keepDot ? segment : `${segment}.`,
+        snippet: false,
+        filterText: segment,
+        retrigger: !keepDot
+      })
+    }
+  }
+
+  private methods(names: readonly string[]): void {
+    // Renaming a method in front of its existing argument list keeps that list.
+    const keepArgs = this.ctx.token.nextChar === '('
+    for (const name of names) {
+      const def = SHELL_METHODS[name]
+      this.add('c', {
+        label: name,
+        kind: 'method',
+        insertText: keepArgs ? name : (def?.template ?? `${name}($0)`),
+        snippet: !keepArgs,
+        filterText: name,
+        documentation: def?.doc,
+        retrigger: !keepArgs && def?.retrigger
+      })
+    }
+  }
+
+  private fieldInfo(field: SchemaField | undefined, schema: CollectionSchema | null): FieldInfo {
+    if (!field) return {}
+    const sampleSize = schema?.sampleSize ?? 0
+    // Sample values render per editor kind and display settings.
+    const key = `${sampleSize} ${this.query} ${this.env.uuidEncoding} ${this.env.timezone}`
+    let infos = FIELD_INFOS.get(field)
+    if (!infos) {
+      infos = new Map()
+      FIELD_INFOS.set(field, infos)
+    }
+    let info = infos.get(key)
+    if (!info) {
+      info = this.describeField(field, sampleSize)
+      infos.set(key, info)
+    }
+    return info
+  }
+
+  private describeField(field: SchemaField, sampleSize: number): FieldInfo {
+    const type = dominantType(field.types) ?? 'unknown'
+    const presence = sampleSize > 0 ? ` · ${percent(field.docCount, sampleSize)}%` : ''
+    const lines = [`\`${field.path}\``, `types: ${typeBreakdown(field.types)}`]
+    if (field.elementTypes) lines.push(`elements: ${typeBreakdown(field.elementTypes)}`)
+    if (sampleSize > 0)
+      lines.push(`present in ${field.docCount} of ${sampleSize} sampled documents`)
+    const values = (field.values ?? []).slice(0, 5).map(({ ejson, count }) => {
+      const value = parseJson(ejson)
+      return value === undefined ? null : `\`${this.render(value)}\` ×${count}`
+    })
+    const shown = values.filter((v): v is string => v !== null)
+    if (shown.length > 0)
+      lines.push(`values: ${shown.join(', ')}${field.valuesTruncated ? ', …' : ''}`)
+    return {
+      description: field.mapLike ? 'map · keys vary' : `${type}${presence}`,
+      documentation: lines.join('\n\n')
+    }
+  }
+}
+
+function argTemplate(kind: ArgKind): { template: string | null; retrigger: boolean } {
+  if (typeof kind === 'object')
+    return 'enum' in kind
+      ? { template: null, retrigger: true }
+      : { template: '{ $0 }', retrigger: true }
+  switch (kind) {
+    case 'collection':
+    case 'fieldPath':
+      return { template: '"$0"', retrigger: true }
+    case 'string':
+      return { template: '"$0"', retrigger: false }
+    case 'fieldPaths':
+    case 'pipeline':
+      return { template: '[$0]', retrigger: true }
+    case 'array':
+      return { template: '[$0]', retrigger: false }
+    case 'arrayRef':
+      return { template: '"\\$$0"', retrigger: true }
+    case 'arrayFilters':
+      return { template: '[{ $0 }]', retrigger: true }
+    case 'query':
+    case 'sort':
+    case 'projection':
+    case 'update':
+    case 'document':
+    case 'accumulators':
+    case 'windowOutput':
+    case 'fillOutput':
+    case 'vars':
+    case 'object':
+      return { template: '{ $0 }', retrigger: true }
+    case 'expression':
+    case 'dateExpr':
+    case 'boolExpr':
+    case 'bool':
+      return { template: null, retrigger: true }
+    case 'number':
+    case 'any':
+      return { template: null, retrigger: false }
+  }
+}
+
+function formTemplate(form: OperatorForm): { template: string | null; retrigger: boolean } {
+  switch (form) {
+    case 'positional':
+      return { template: '[$0]', retrigger: true }
+    case 'single':
+      return { template: null, retrigger: true }
+    case 'named':
+      return { template: '{ $0 }', retrigger: true }
+    case 'none':
+      return { template: '{}', retrigger: false }
+  }
+}
+
+function fits(fit: OperatorFit, field: SchemaField, schema: CollectionSchema | null): boolean {
+  const top = dominantType(field.types)
+  const element = top === 'array' ? dominantType(field.elementTypes) : top
+  switch (fit) {
+    case 'always':
+      return true
+    case 'comparable':
+      return element !== null && COMPARABLE.has(element)
+    case 'string':
+    case 'regexOption':
+      return element === 'string'
+    case 'array':
+      return top === 'array'
+    case 'integer':
+      return element === 'int' || element === 'long'
+    case 'geo':
+      return top === 'object'
+        ? isGeoJson(field, schema)
+        : top === 'array' && element !== null && NUMERIC_TYPES.has(element)
+  }
+}
+
+/** A GeoJSON object has `type` and `coordinates`; any other embedded document is no geometry. */
+function isGeoJson(field: SchemaField, schema: CollectionSchema | null): boolean {
+  const names = schema ? childFields(schema, field.path).map((f) => lastSegment(f.path)) : []
+  return names.includes('type') && names.includes('coordinates')
+}
+
+/** Whether `stage` can run at `index` of a pipeline nested as `nested`; `finalWrite`: a write stage may end the pipeline there. */
+function stageRuns(
+  stage: StageDef,
+  index: number,
+  nested: Nesting | undefined,
+  finalWrite: boolean
+): boolean {
+  // A change stream never ends; only a shell aggregate may end with a write.
+  if (UNSUPPORTED_STAGES.has(stage.name)) return false
+  if (WRITE_STAGES.has(stage.name)) return finalWrite
+  if (nested === 'update') return UPDATE_PIPELINE_STAGES.has(stage.name)
+  if (stage.subPipelineOnly && nested !== 'sub') return false
+  // A $facet branch accepts no first-stage-only stage and no further $facet.
+  if (nested === 'facet') return !stage.firstOnly && stage.name !== '$facet'
+  return !stage.firstOnly || index === 0
+}
+
+/** Stages that write a collection rank last. */
+function stageTier(stage: StageDef): Tier {
+  return WRITE_STAGES.has(stage.name) ? 'e' : 'c'
+}
+
+function isArrayField(schema: CollectionSchema, path: string): boolean {
+  return dominantType(resolveSchemaField(schema, path)?.types) === 'array'
+}
+
+/** `path` with `$[]` after each array it passes through, the way an update reaches every element. */
+function elementPath(schema: CollectionSchema, path: string): string {
+  const segments = path.split('.')
+  return segments
+    .map((segment, i) =>
+      i < segments.length - 1 && isArrayField(schema, segments.slice(0, i + 1).join('.'))
+        ? `${segment}.$[]`
+        : segment
+    )
+    .join('.')
+}
+
+/** Whether `$rename` can move `from` to `to`: not onto _id, not along its own path, not into array elements. */
+function renamesTo(schema: CollectionSchema, from: string, to: string): boolean {
+  if (to === '_id' || to.startsWith('_id.')) return false
+  if (to === from || to.startsWith(`${from}.`) || from.startsWith(`${to}.`)) return false
+  return elementPath(schema, to) === to
+}
+
+function inClass(type: BsonTypeName | null | undefined, cls: TypeClass): boolean {
+  if (!type) return false
+  return cls === 'number' ? NUMERIC_TYPES.has(type) : type === cls
+}
+
+/** Type a query compares against: the element type of an array field. */
+function queryType(field: SchemaField): BsonTypeName | null {
+  const top = dominantType(field.types)
+  return top === 'array' ? (dominantType(field.elementTypes) ?? top) : top
+}
+
+/** `_id` first, then by presence, depth and name. */
+function rankFields<T extends SchemaField | undefined>(entries: [string, T][]): [string, T][] {
+  return [...entries].sort(([a, fa], [b, fb]) => {
+    if (a === '_id' || b === '_id') return a === '_id' ? (b === '_id' ? 0 : -1) : 1
+    return (
+      (fb?.docCount ?? 0) - (fa?.docCount ?? 0) ||
+      a.split('.').length - b.split('.').length ||
+      compareText(a, b)
+    )
+  })
+}
+
+/** `addressableFields` of `schema` by path, in `rankFields` order. */
+function rankedFields(schema: CollectionSchema): readonly [string, SchemaField][] {
+  let ranked = RANKED_FIELDS.get(schema)
+  if (!ranked) {
+    ranked = rankFields(addressableFields(schema).map((f) => [f.path, f]))
+    RANKED_FIELDS.set(schema, ranked)
+  }
+  return ranked
+}
+
+function preferred<T extends SchemaField | undefined>(
+  entries: readonly [string, T][],
+  prefer: TypeClass | null
+): readonly [string, T][] {
+  if (prefer === null) return entries
+  const matches = (field: SchemaField | undefined): boolean =>
+    field !== undefined && inClass(dominantType(field.types), prefer)
+  return [...entries.filter(([, f]) => matches(f)), ...entries.filter(([, f]) => !matches(f))]
+}
+
+function sortedTypes(counts: TypeCounts): [BsonTypeName, number][] {
+  return (Object.entries(counts) as [BsonTypeName, number][])
+    .filter(([, count]) => count > 0)
+    .sort(([a, ca], [b, cb]) => cb - ca || compareText(a, b))
+}
+
+function typeBreakdown(counts: TypeCounts): string {
+  const total = sumCounts(counts)
+  return sortedTypes(counts)
+    .map(([type, count]) => `${type} ${percent(count, total)}%`)
+    .join(' · ')
+}
+
+function sumCounts(counts: TypeCounts): number {
+  return Object.values(counts).reduce<number>((sum, count) => sum + (count ?? 0), 0)
+}
+
+function sumValueCounts(values: readonly { count: number }[]): number {
+  return values.reduce((sum, value) => sum + value.count, 0)
+}
+
+function valueCount(field: SchemaField | undefined, ejson: string): number {
+  return field?.values?.find((value) => value.ejson === ejson)?.count ?? 0
+}
+
+function percent(count: number, total: number): number {
+  return total > 0 ? Math.round((count * 100) / total) : 0
+}
+
+/** `$numberInt` and finite `$numberDouble` as plain numbers; null for anything else. */
+function plainNumber(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null) return null
+  const wrapper = value as Record<string, unknown>
+  const raw = wrapper['$numberInt'] ?? wrapper['$numberDouble']
+  if (typeof raw !== 'string' || Object.keys(wrapper).length !== 1) return null
+  const number = Number(raw)
+  return Number.isFinite(number) ? String(number) : null
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function snippetEscape(text: string): string {
+  return text.replace(/[\\$}]/g, '\\$&')
+}
+
+function escapeInQuotes(text: string, quote: '"' | "'"): string {
+  const json = JSON.stringify(text).slice(1, -1)
+  return quote === '"' ? json : json.replace(/\\"/g, '"').replace(/'/g, "\\'")
+}
+
+function lastSegment(path: string): string {
+  return path.slice(path.lastIndexOf('.') + 1)
+}
diff --git a/src/renderer/src/lib/completion/useCompletionAttachment.ts b/src/renderer/src/lib/completion/useCompletionAttachment.ts
new file mode 100644
index 0000000..99fe400
--- /dev/null
+++ b/src/renderer/src/lib/completion/useCompletionAttachment.ts
@@ -0,0 +1,25 @@
+import { useEffect, useRef } from 'react'
+import type * as monaco from 'monaco-editor'
+import { attachCompletion, type CompletionBinding } from './monacoAdapter'
+
+/**
+ * Binds completion to the editor mounted with the returned callback, until unmount or the next mount.
+ * @param binding read on every request; null at mount leaves that editor without completion
+ * @returns The editor's `onMount` (or a call from it).
+ */
+export function useCompletionAttachment(
+  binding: CompletionBinding | null
+): (editor: monaco.editor.IStandaloneCodeEditor) => void {
+  const bindingRef = useRef(binding)
+  const attachmentRef = useRef<monaco.IDisposable | null>(null)
+  useEffect(() => {
+    bindingRef.current = binding
+  }, [binding])
+  useEffect(() => () => attachmentRef.current?.dispose(), [])
+
+  return (editor) => {
+    attachmentRef.current?.dispose()
+    attachmentRef.current =
+      binding === null ? null : attachCompletion(editor, () => bindingRef.current)
+  }
+}
diff --git a/src/renderer/src/lib/completion/useCompletionEnv.test.ts b/src/renderer/src/lib/completion/useCompletionEnv.test.ts
new file mode 100644
index 0000000..abfa5af
--- /dev/null
+++ b/src/renderer/src/lib/completion/useCompletionEnv.test.ts
@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QueryClient, environmentManager } from '@tanstack/react-query'
+import { createSchemaBuilder, resolveSchemaField } from '@shared/collectionSchema'
+import type { CollectionSchema, DocumentEnvelope } from '@shared/types'
+import { api } from '../api'
+import { SCHEMA_STALE_MS, schemaAccess } from './useCompletionEnv'
+
+const REF = { connectionId: 'c1', db: 'app', coll: 'users' }
+
+const schemaOf = (...docs: unknown[]): CollectionSchema => {
+  const builder = createSchemaBuilder()
+  for (const doc of docs) builder.add(doc)
+  return builder.build()
+}
+
+const SAMPLED: Record<string, CollectionSchema> = {
+  users: schemaOf({ _id: { $oid: '507f1f77bcf86cd799439011' }, name: 'ada' }),
+  orders: schemaOf({ _id: { $oid: '507f1f77bcf86cd799439012' }, total: { $numberInt: '3' } })
+}
+
+const envelope = (canonical: unknown): DocumentEnvelope => ({
+  id: null,
+  hash: '',
+  data: {},
+  canonical: JSON.stringify(canonical)
+})
+
+const schemaCall = vi.spyOn(api.collections, 'schema')
+
+let queryClient: QueryClient
+
+beforeEach(() => {
+  queryClient = new QueryClient()
+  schemaCall.mockReset()
+  schemaCall.mockImplementation(async ({ coll }) => {
+    const schema = SAMPLED[coll]
+    if (!schema) throw new Error(`no sample for ${coll}`)
+    return schema
+  })
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+const access = (documents: readonly DocumentEnvelope[] | undefined = undefined) =>
+  schemaAccess(queryClient, REF, ['users', 'orders'], () => documents)
+
+describe('schemaAccess', () => {
+  it('never samples a name that is not a collection of the database', async () => {
+    await expect(access().loadSchema('typed_by_user')).resolves.toBeNull()
+    expect(schemaCall).not.toHaveBeenCalled()
+  })
+
+  it('samples each collection once and serves later requests from the cache', async () => {
+    const { loadSchema } = access()
+    const [first, concurrent] = await Promise.all([loadSchema('users'), loadSchema('users')])
+    const later = await loadSchema('users')
+    const other = await loadSchema('orders')
+
+    expect(first).toEqual(SAMPLED.users)
+    expect(concurrent).toEqual(SAMPLED.users)
+    expect(later).toEqual(SAMPLED.users)
+    expect(other).toEqual(SAMPLED.orders)
+    expect(schemaCall.mock.calls).toEqual([[{ ...REF }], [{ ...REF, coll: 'orders' }]])
+  })
+
+  it('prefetches the own collection', async () => {
+    access().prefetchSchema()
+    await vi.waitFor(() => expect(schemaCall).toHaveBeenCalledTimes(1))
+    expect(schemaCall).toHaveBeenCalledWith(REF)
+  })
+
+  it('folds loaded documents into the own collection only', async () => {
+    const docs = [envelope({ _id: { $oid: '507f1f77bcf86cd799439013' }, nickname: 'lin' })]
+    const { loadSchema } = access(docs)
+
+    const own = await loadSchema('users')
+    const other = await loadSchema('orders')
+
+    expect(own?.sampleSize).toBe(2)
+    expect(resolveSchemaField(own!, 'nickname')?.types).toEqual({ string: 1 })
+    expect(resolveSchemaField(own!, 'name')?.docCount).toBe(1)
+    expect(other).toEqual(SAMPLED.orders)
+  })
+
+  it('reuses the folded schema until the documents change', async () => {
+    let docs = [envelope({ nickname: 'lin' })]
+    const { loadSchema } = schemaAccess(queryClient, REF, [], () => docs)
+
+    const first = await loadSchema('users')
+    expect(await loadSchema('users')).toBe(first)
+
+    docs = [envelope({ nickname: 'kai' })]
+    const next = await loadSchema('users')
+    expect(next).not.toBe(first)
+    expect(resolveSchemaField(next!, 'nickname')?.values).toEqual([{ ejson: '"kai"', count: 1 }])
+  })
+
+  it('folds new documents into the cached sample ahead of the next request', async () => {
+    let docs = [envelope({ nickname: 'lin' })]
+    const { loadSchema, foldDocuments } = schemaAccess(queryClient, REF, [], () => docs)
+    foldDocuments()
+    expect(schemaCall).not.toHaveBeenCalled()
+
+    await loadSchema('users')
+    docs = [envelope({ nickname: 'kai' })]
+    const parse = vi.spyOn(JSON, 'parse')
+    try {
+      foldDocuments()
+      expect(parse).toHaveBeenCalledTimes(1)
+      const schema = await loadSchema('users')
+      expect(parse).toHaveBeenCalledTimes(1)
+      expect(resolveSchemaField(schema!, 'nickname')?.values).toEqual([
+        { ejson: '"kai"', count: 1 }
+      ])
+    } finally {
+      parse.mockRestore()
+    }
+  })
+
+  it('folds the documents once a prefetched sample arrives', async () => {
+    const { loadSchema, prefetchSchema } = access([envelope({ nickname: 'lin' })])
+    const parse = vi.spyOn(JSON, 'parse')
+    try {
+      prefetchSchema()
+      await vi.waitFor(() => expect(parse).toHaveBeenCalledTimes(1))
+      expect((await loadSchema('users'))?.sampleSize).toBe(2)
+      expect(parse).toHaveBeenCalledTimes(1)
+    } finally {
+      parse.mockRestore()
+    }
+  })
+
+  it('builds the schema from loaded documents when sampling fails', async () => {
+    schemaCall.mockRejectedValue(new Error('not authorized'))
+    const { loadSchema } = access([envelope({ nickname: 'lin' })])
+
+    const schema = await loadSchema('users')
+
+    expect(schema?.sampleSize).toBe(1)
+    expect(schema?.fields.map((f) => f.path)).toEqual(['nickname'])
+  })
+
+  it('does not retry a failed sample per request until it is refreshed', async () => {
+    schemaCall.mockRejectedValueOnce(new Error('not authorized'))
+    const { loadSchema, refreshSchema } = access()
+
+    await expect(loadSchema('users')).resolves.toBeNull()
+    await expect(loadSchema('users')).resolves.toBeNull()
+    expect(schemaCall).toHaveBeenCalledTimes(1)
+
+    refreshSchema()
+    await vi.waitFor(() => expect(schemaCall).toHaveBeenCalledTimes(2))
+    await expect(loadSchema('users')).resolves.toEqual(SAMPLED.users)
+  })
+
+  it('retries a failed sample once it is older than the stale time', async () => {
+    vi.useFakeTimers({ toFake: ['Date'] })
+    schemaCall.mockRejectedValueOnce(new Error('timed out'))
+    const { loadSchema } = access()
+
+    await expect(loadSchema('users')).resolves.toBeNull()
+    vi.setSystemTime(Date.now() + SCHEMA_STALE_MS + 1)
+
+    await expect(loadSchema('users')).resolves.toEqual(SAMPLED.users)
+    expect(schemaCall).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps an unobserved sample cached for the stale time in the renderer', async () => {
+    const serverCheck = environmentManager.isServer()
+    // The Electron renderer has a window, so query-core applies its browser cache lifetime.
+    environmentManager.setIsServer(() => false)
+    try {
+      vi.useFakeTimers()
+      const { loadSchema } = access()
+      await loadSchema('users')
+      await vi.advanceTimersByTimeAsync(SCHEMA_STALE_MS - 60_000)
+      await loadSchema('users')
+      expect(schemaCall).toHaveBeenCalledTimes(1)
+    } finally {
+      environmentManager.setIsServer(() => serverCheck)
+    }
+  })
+
+  it('keeps suppressing a failed sample for the stale time in the renderer', async () => {
+    const serverCheck = environmentManager.isServer()
+    environmentManager.setIsServer(() => false)
+    try {
+      vi.useFakeTimers()
+      schemaCall.mockRejectedValueOnce(new Error('timed out'))
+      const { loadSchema } = access()
+      await expect(loadSchema('users')).resolves.toBeNull()
+      await vi.advanceTimersByTimeAsync(SCHEMA_STALE_MS - 60_000)
+      await expect(loadSchema('users')).resolves.toBeNull()
+      expect(schemaCall).toHaveBeenCalledTimes(1)
+    } finally {
+      environmentManager.setIsServer(() => serverCheck)
+    }
+  })
+
+  it('refreshes by sampling again and keeps serving the old schema meanwhile', async () => {
+    const { loadSchema, refreshSchema } = access()
+    await loadSchema('users')
+    const updated = schemaOf({ renamed: true })
+    let finish!: (schema: CollectionSchema) => void
+    schemaCall.mockImplementationOnce(() => new Promise((resolve) => (finish = resolve)))
+
+    refreshSchema()
+    await vi.waitFor(() => expect(schemaCall).toHaveBeenCalledTimes(2))
+    await expect(loadSchema('users')).resolves.toEqual(SAMPLED.users)
+
+    finish(updated)
+    await vi.waitFor(async () => expect(await loadSchema('users')).toEqual(updated))
+  })
+})
diff --git a/src/renderer/src/lib/completion/useCompletionEnv.ts b/src/renderer/src/lib/completion/useCompletionEnv.ts
new file mode 100644
index 0000000..0b1d4fc
--- /dev/null
+++ b/src/renderer/src/lib/completion/useCompletionEnv.ts
@@ -0,0 +1,159 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { queryOptions, useQuery, useQueryClient, type QueryClient } from '@tanstack/react-query'
+import { createSchemaBuilder } from '@shared/collectionSchema'
+import type { CollectionRef, CollectionSchema, DocumentEnvelope, UuidEncoding } from '@shared/types'
+import { api } from '../api'
+import { queryKeys } from '../queryClient'
+
+export const SCHEMA_STALE_MS = 10 * 60_000
+// Folding is synchronous on the editor's thread; an unlimited result page would stall typing.
+const MAX_MERGED_DOCUMENTS = 1000
+
+/** Query options for a collection's sampled schema (shared by completion and the index form). */
+export function collectionSchemaQuery(connectionId: string, db: string, coll: string) {
+  return queryOptions({
+    queryKey: queryKeys.collectionSchema(connectionId, db, coll),
+    queryFn: () => api.collections.schema({ connectionId, db, coll }),
+    staleTime: SCHEMA_STALE_MS,
+    // Completion fetches without an observer; the default gcTime would drop samples and failures early.
+    gcTime: SCHEMA_STALE_MS,
+    retry: false
+  })
+}
+
+export type CompletionEnv = {
+  coll: string
+  /** Collection names of the database; schemas are only ever loaded for these and `coll`. */
+  collections: readonly string[]
+  uuidEncoding: UuidEncoding
+  timezone: string
+  /** Effective schema of `name` (own collection includes loaded documents); null if sampling failed or the name is unknown. */
+  loadSchema: (name: string) => Promise<CollectionSchema | null>
+  /** Starts sampling `coll` and folding the documents into it before the first completion request needs them. */
+  prefetchSchema: () => void
+  /** Samples `coll` again. */
+  refreshSchema: () => void
+}
+
+/**
+ * Per-tab completion environment; nothing is sampled until an editor asks for a schema.
+ * @param p.documents whole, unprojected documents of `coll`, folded into its schema
+ * @param p.enabled false leaves the collection list unloaded (closed dialogs)
+ */
+export function useCompletionEnv(p: {
+  connectionId: string
+  db: string
+  coll: string
+  uuidEncoding: UuidEncoding
+  timezone: string
+  documents?: readonly DocumentEnvelope[]
+  enabled?: boolean
+}): CompletionEnv {
+  const { connectionId, db, coll, uuidEncoding, timezone, documents, enabled = true } = p
+  const queryClient = useQueryClient()
+  const collectionsQuery = useQuery({
+    queryKey: queryKeys.collections(connectionId, db),
+    queryFn: () => api.collections.list({ connectionId, db }),
+    enabled
+  })
+  const listed = collectionsQuery.data
+  const collections = useMemo(() => listed?.map((c) => c.name) ?? [], [listed])
+  // Read on every request, so a new result page does not rebuild the environment.
+  const documentsRef = useRef(documents)
+  const access = useMemo(
+    () =>
+      schemaAccess(
+        queryClient,
+        { connectionId, db, coll },
+        collections,
+        () => documentsRef.current
+      ),
+    [queryClient, connectionId, db, coll, collections]
+  )
+  useEffect(() => {
+    documentsRef.current = documents
+    // Folding a result page takes long enough to stall the next keystroke.
+    const idle = requestIdleCallback(access.foldDocuments)
+    return () => cancelIdleCallback(idle)
+  }, [documents, access])
+
+  return useMemo(
+    () => ({
+      coll,
+      collections,
+      uuidEncoding,
+      timezone,
+      loadSchema: access.loadSchema,
+      prefetchSchema: access.prefetchSchema,
+      refreshSchema: access.refreshSchema
+    }),
+    [access, coll, collections, uuidEncoding, timezone]
+  )
+}
+
+/**
+ * Schema loading of one collection's editors through the query cache.
+ * @param collections names whose schemas may be sampled besides `ref.coll`
+ * @param documents current whole documents of `ref.coll`; folded in when non-empty
+ * @returns the schema functions of the env, plus `foldDocuments`: folds the documents into an existing sample now, never samples
+ */
+export function schemaAccess(
+  queryClient: QueryClient,
+  ref: CollectionRef,
+  collections: readonly string[],
+  documents: () => readonly DocumentEnvelope[] | undefined
+): Pick<CompletionEnv, 'loadSchema' | 'prefetchSchema' | 'refreshSchema'> & {
+  foldDocuments: () => void
+} {
+  const { connectionId, db, coll } = ref
+  // Keyed by the result page, so a replaced page is collected together with its folded schema.
+  const merged = new WeakMap<
+    readonly DocumentEnvelope[],
+    { base: CollectionSchema | null; schema: CollectionSchema }
+  >()
+
+  const sampled = (name: string): Promise<CollectionSchema | null> => {
+    const options = collectionSchemaQuery(connectionId, db, name)
+    const state = queryClient.getQueryState(options.queryKey)
+    // A failed sample would otherwise be retried on every keystroke; refreshSchema retries it.
+    if (state?.status === 'error' && Date.now() - state.errorUpdatedAt < SCHEMA_STALE_MS) {
+      return Promise.resolve(state.data ?? null)
+    }
+    return queryClient.fetchQuery(options).catch(() => null)
+  }
+
+  const withDocuments = (base: CollectionSchema | null): CollectionSchema | null => {
+    const docs = documents()
+    if (!docs || docs.length === 0) return base
+    let entry = merged.get(docs)
+    if (!entry || entry.base !== base) {
+      const builder = createSchemaBuilder(base ?? undefined)
+      for (const envelope of docs.slice(0, MAX_MERGED_DOCUMENTS)) {
+        if (envelope.canonical) builder.add(JSON.parse(envelope.canonical))
+      }
+      entry = { base, schema: builder.build() }
+      merged.set(docs, entry)
+    }
+    return entry.schema
+  }
+
+  return {
+    loadSchema: async (name) => {
+      if (name !== coll && !collections.includes(name)) return null
+      const base = await sampled(name)
+      return name === coll ? withDocuments(base) : base
+    },
+    prefetchSchema: () => void sampled(coll).then(withDocuments),
+    refreshSchema: () =>
+      void queryClient.refetchQueries({
+        queryKey: queryKeys.collectionSchema(connectionId, db, coll)
+      }),
+    foldDocuments: () => {
+      const state = queryClient.getQueryState(
+        collectionSchemaQuery(connectionId, db, coll).queryKey
+      )
+      // Sampling waits for an editor to ask; only a sample it already got is folded into.
+      if (state && state.status !== 'pending') withDocuments(state.data ?? null)
+    }
+  }
+}
diff --git a/src/renderer/src/lib/dateZone.test.ts b/src/renderer/src/lib/dateZone.test.ts
new file mode 100644
index 0000000..17822ca
--- /dev/null
+++ b/src/renderer/src/lib/dateZone.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { formatIsoInZone } from './dateZone'
+
+describe('formatIsoInZone', () => {
+  const zones = ['UTC', 'Europe/Berlin', 'America/New_York']
+  const instants = [
+    '0001-01-01T00:00:00.000Z',
+    '1850-06-01T00:00:00.000Z',
+    '1970-01-01T00:00:00.000Z',
+    '2024-03-31T01:30:00.000Z',
+    '9999-12-31T23:59:59.999Z'
+  ]
+
+  for (const zone of zones) {
+    for (const instant of instants) {
+      it(`reads back ${instant} rendered in ${zone} as the same instant`, () => {
+        const d = new Date(instant)
+        expect(new Date(formatIsoInZone(d, zone)).getTime()).toBe(d.getTime())
+      })
+    }
+  }
+
+  it('renders the zone offset for ordinary dates', () => {
+    expect(formatIsoInZone(new Date('2024-01-01T00:00:00.000Z'), 'Europe/Berlin')).toBe(
+      '2024-01-01T01:00:00.000+01:00'
+    )
+    expect(formatIsoInZone(new Date('2024-07-01T12:00:00.000Z'), 'America/New_York')).toBe(
+      '2024-07-01T08:00:00.000-04:00'
+    )
+  })
+
+  it('falls back to UTC for local-mean-time offsets and years outside 1000-9999', () => {
+    expect(formatIsoInZone(new Date('1850-06-01T00:00:00.000Z'), 'Europe/Berlin')).toBe(
+      '1850-06-01T00:00:00.000Z'
+    )
+    expect(formatIsoInZone(new Date('0999-06-01T00:00:00.000Z'), 'Etc/GMT-1')).toBe(
+      '0999-06-01T00:00:00.000Z'
+    )
+    expect(formatIsoInZone(new Date('9999-12-31T23:59:59.999Z'), 'Europe/Berlin')).toBe(
+      '9999-12-31T23:59:59.999Z'
+    )
+  })
+
+  it('falls back to UTC for years before the common era', () => {
+    const d = new Date('-001000-06-01T00:00:00.000Z')
+    expect(formatIsoInZone(d, 'Etc/GMT-1')).toBe(d.toISOString())
+  })
+})
diff --git a/src/renderer/src/lib/dateZone.ts b/src/renderer/src/lib/dateZone.ts
index 03debd5..61adca4 100644
--- a/src/renderer/src/lib/dateZone.ts
+++ b/src/renderer/src/lib/dateZone.ts
@@ -13,19 +13,7 @@ export function formatIsoInZone(input: number | string | Date, tz: string): stri
 
   let parts: Intl.DateTimeFormatPart[]
   try {
-    parts = new Intl.DateTimeFormat('en-CA', {
-      timeZone: zone,
-      year: 'numeric',
-      month: '2-digit',
-      day: '2-digit',
-      hour: '2-digit',
-      minute: '2-digit',
-      second: '2-digit',
-      hour12: false,
-      hourCycle: 'h23',
-      fractionalSecondDigits: 3,
-      timeZoneName: 'longOffset'
-    }).formatToParts(d)
+    parts = zoneFormatter(zone).formatToParts(d)
   } catch {
     return d.toISOString()
   }
@@ -37,7 +25,9 @@ export function formatIsoInZone(input: number | string | Date, tz: string): stri
   const offset = tzn === 'GMT' || tzn === '' ? '+00:00' : tzn.replace('GMT', '').replace('−', '-')
   // Some Chromium builds report `24` for midnight under hourCycle: 'h23'.
   const hour = get('hour') === '24' ? '00' : get('hour')
-  return `${get('year')}-${get('month')}-${get('day')}T${hour}:${get('minute')}:${get('second')}.${ms}${offset}`
+  const iso = `${get('year')}-${get('month')}-${get('day')}T${hour}:${get('minute')}:${get('second')}.${ms}${offset}`
+  // Intl's local-mean-time offsets (+00:53:28), unpadded years and era-less BC years don't parse back.
+  return Date.parse(iso) === d.getTime() ? iso : d.toISOString()
 }
 
 /**
@@ -51,7 +41,27 @@ export function formatDateInZone(input: number | string | Date, tz: string): str
   const zone = tz && tz.length > 0 ? tz : 'UTC'
   let parts: Intl.DateTimeFormatPart[]
   try {
-    parts = new Intl.DateTimeFormat('en-CA', {
+    parts = zoneFormatter(zone).formatToParts(d)
+  } catch {
+    return d.toISOString()
+  }
+  const get = (type: string): string => parts.find((p) => p.type === type)?.value ?? ''
+  const hour = get('hour') === '24' ? '00' : get('hour')
+  const ms = get('fractionalSecond') || '000'
+  const base = `${get('day')}.${get('month')}.${get('year')} ${hour}:${get('minute')}:${get('second')}.${ms}`
+  if (zone === 'UTC') return `${base} UTC`
+  const tzn = get('timeZoneName')
+  const offset = tzn === 'GMT' || tzn === '' ? '+00:00' : tzn.replace('GMT', '').replace('−', '-')
+  return `${base} ${offset}`
+}
+
+// Building a formatter costs far more than formatting with it; tables render many dates per zone.
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+function zoneFormatter(zone: string): Intl.DateTimeFormat {
+  let formatter = formatters.get(zone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-CA', {
       timeZone: zone,
       year: 'numeric',
       month: '2-digit',
@@ -63,16 +73,8 @@ export function formatDateInZone(input: number | string | Date, tz: string): str
       hourCycle: 'h23',
       fractionalSecondDigits: 3,
       timeZoneName: zone === 'UTC' ? undefined : 'longOffset'
-    }).formatToParts(d)
-  } catch {
-    return d.toISOString()
+    })
+    formatters.set(zone, formatter)
   }
-  const get = (type: string): string => parts.find((p) => p.type === type)?.value ?? ''
-  const hour = get('hour') === '24' ? '00' : get('hour')
-  const ms = get('fractionalSecond') || '000'
-  const base = `${get('day')}.${get('month')}.${get('year')} ${hour}:${get('minute')}:${get('second')}.${ms}`
-  if (zone === 'UTC') return `${base} UTC`
-  const tzn = get('timeZoneName')
-  const offset = tzn === 'GMT' || tzn === '' ? '+00:00' : tzn.replace('GMT', '').replace('−', '-')
-  return `${base} ${offset}`
+  return formatter
 }
diff --git a/src/renderer/src/lib/displayUri.test.ts b/src/renderer/src/lib/displayUri.test.ts
new file mode 100644
index 0000000..158fe9c
--- /dev/null
+++ b/src/renderer/src/lib/displayUri.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import type { ConnectionConfig } from '@shared/types'
+import { formatConnectionAddress, formatHostShort } from './displayUri'
+
+function connection(patch: Partial<ConnectionConfig>): ConnectionConfig {
+  return {
+    id: '00000000-0000-4000-8000-000000000000',
+    name: 'test',
+    uri: 'mongodb://localhost:27017',
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    hasStoredPassword: false,
+    ...patch
+  }
+}
+
+const cloudflared = {
+  hostname: 'mongo.example.com',
+  authMethod: 'browser',
+  hasStoredServiceTokenSecret: false
+} as const
+
+describe('formatHostShort', () => {
+  it('keeps every host and drops the path and options', () => {
+    expect(formatHostShort(connection({ uri: 'mongodb://h1:27017,h2:27018/db?tls=true' }))).toBe(
+      'h1:27017,h2:27018'
+    )
+    expect(formatHostShort(connection({ uri: 'mongodb+srv://cluster.example.net?x=1' }))).toBe(
+      'cluster.example.net'
+    )
+  })
+
+  it('shows the Access hostname while a Cloudflare tunnel is on', () => {
+    const conn = connection({
+      uri: 'mongodb://localhost/db',
+      cloudflared: { ...cloudflared, enabled: true }
+    })
+    expect(formatHostShort(conn)).toBe('mongo.example.com')
+  })
+
+  it('shows the URI hosts while the Cloudflare tunnel is switched off', () => {
+    const conn = connection({
+      uri: 'mongodb://db.internal:27017/app',
+      cloudflared: { ...cloudflared, enabled: false }
+    })
+    expect(formatHostShort(conn)).toBe('db.internal:27017')
+  })
+})
+
+describe('formatConnectionAddress', () => {
+  it('is the URI as stored without a Cloudflare tunnel', () => {
+    const uri = 'mongodb://db.internal:27017/app?tls=true'
+    expect(formatConnectionAddress(connection({ uri }))).toBe(uri)
+    expect(
+      formatConnectionAddress(connection({ uri, cloudflared: { ...cloudflared, enabled: false } }))
+    ).toBe(uri)
+  })
+
+  it('is the Access hostname while a Cloudflare tunnel is on', () => {
+    const conn = connection({
+      uri: 'mongodb://localhost/db',
+      cloudflared: { ...cloudflared, enabled: true }
+    })
+    expect(formatConnectionAddress(conn)).toBe('mongo.example.com')
+  })
+})
diff --git a/src/renderer/src/lib/displayUri.ts b/src/renderer/src/lib/displayUri.ts
index 17937a9..0547018 100644
--- a/src/renderer/src/lib/displayUri.ts
+++ b/src/renderer/src/lib/displayUri.ts
@@ -19,15 +19,22 @@ export function formatConnectionUri(connection: ConnectionConfig): string {
   return `${scheme}${auth}${rest}`
 }
 
+/** Where the connection goes: the Access hostname behind a Cloudflare tunnel, else its URI. */
+export function formatConnectionAddress(connection: ConnectionConfig): string {
+  // A Cloudflare tunnel never dials the URI's hosts; the Access hostname is where it goes.
+  return connection.cloudflared?.enabled === true ? connection.cloudflared.hostname : connection.uri
+}
+
 /**
  * Compact host display for sidebar rows: just the host (and port, when present).
  * Drops the scheme, any path, and any query parameters. For comma-separated
  * replica-set hosts we keep them all.
  */
 export function formatHostShort(connection: ConnectionConfig): string {
-  const match = /^mongodb(?:\+srv)?:\/\//.exec(connection.uri)
-  if (!match) return connection.uri
-  const rest = connection.uri.slice(match[0].length)
+  const address = formatConnectionAddress(connection)
+  const match = /^mongodb(?:\+srv)?:\/\//.exec(address)
+  if (!match) return address
+  const rest = address.slice(match[0].length)
   const stop = rest.search(/[/?#]/)
   return stop === -1 ? rest : rest.slice(0, stop)
 }
diff --git a/src/renderer/src/lib/indexUsage.test.ts b/src/renderer/src/lib/indexUsage.test.ts
new file mode 100644
index 0000000..c888d7d
--- /dev/null
+++ b/src/renderer/src/lib/indexUsage.test.ts
@@ -0,0 +1,435 @@
+import { describe, expect, it } from 'vitest'
+import type { IndexInfo, IndexStatsReport, IndexUsageSample } from '@shared/types'
+import {
+  buildIndexRows,
+  formatAge,
+  formatCount,
+  formatRate,
+  nextSort,
+  sortIndexRows,
+  summarizeUsage,
+  unavailableText,
+  usageAvailable,
+  usageNotes,
+  usageSources,
+  type IndexRow
+} from './indexUsage'
+
+const MINUTE = 60_000
+const HOUR = 3_600_000
+const DAY = 86_400_000
+const NOW = Date.parse('2026-03-01T00:00:00.000Z')
+
+const iso = (ms: number): string => new Date(ms).toISOString()
+
+const sample = (
+  ops: number,
+  ageMs: number,
+  host = 'h1:27017',
+  shard?: string
+): IndexUsageSample => ({
+  host,
+  ...(shard !== undefined ? { shard } : {}),
+  ops,
+  since: iso(NOW - ageMs)
+})
+
+const index = (name: string, extra: Partial<IndexInfo> = {}): IndexInfo => ({
+  name,
+  key: { [name.replace(/_-?1$/, '')]: 1 },
+  ...extra
+})
+
+const report = (
+  indexes: IndexStatsReport['indexes'],
+  extra: Partial<IndexStatsReport> = {}
+): IndexStatsReport => ({
+  indexes,
+  usageUnavailable: null,
+  storageUnavailable: null,
+  ...extra
+})
+
+const row = (name: string, size: number | undefined, ops: number | null): IndexRow => ({
+  index: index(name),
+  size,
+  building: false,
+  usage:
+    ops === null
+      ? null
+      : { ops, opsPerDay: null, since: NOW - DAY, coveredSince: NOW - DAY, hosts: [] },
+  unused: false
+})
+
+const names = (rows: readonly IndexRow[]): string[] => rows.map((r) => r.index.name)
+
+describe('summarizeUsage', () => {
+  it('returns null without samples', () => {
+    expect(summarizeUsage([], NOW)).toBeNull()
+  })
+
+  it('extrapolates a per-day rate from one host', () => {
+    const summary = summarizeUsage([sample(1000, 10 * DAY)], NOW)
+    expect(summary).toEqual({
+      ops: 1000,
+      opsPerDay: 100,
+      since: NOW - 10 * DAY,
+      coveredSince: NOW - 10 * DAY,
+      hosts: [sample(1000, 10 * DAY)]
+    })
+  })
+
+  it('sums ops and per-host rates and spans the earliest and latest counter start', () => {
+    const summary = summarizeUsage([sample(100, DAY, 'a:1'), sample(50, 10 * DAY, 'b:1')], NOW)
+    expect(summary?.ops).toBe(150)
+    expect(summary?.opsPerDay).toBeCloseTo(105)
+    expect(summary?.since).toBe(NOW - 10 * DAY)
+    expect(summary?.coveredSince).toBe(NOW - DAY)
+  })
+
+  it('leaves hosts that counted for under a minute out of the rate', () => {
+    const summary = summarizeUsage([sample(10, DAY, 'a:1'), sample(500, 30_000, 'b:1')], NOW)
+    expect(summary?.ops).toBe(510)
+    expect(summary?.opsPerDay).toBeCloseTo(10)
+  })
+
+  it('has no rate when every host counted for under a minute', () => {
+    expect(summarizeUsage([sample(5, 59_999)], NOW)?.opsPerDay).toBeNull()
+  })
+
+  it('counts a host from exactly one minute on', () => {
+    expect(summarizeUsage([sample(1, MINUTE)], NOW)?.opsPerDay).toBeCloseTo(1440)
+  })
+
+  it('gives no negative rate for a counter start in the future', () => {
+    const summary = summarizeUsage([sample(5, -HOUR)], NOW)
+    expect(summary?.ops).toBe(5)
+    expect(summary?.opsPerDay).toBeNull()
+  })
+
+  it('copies the samples instead of sharing the input array', () => {
+    const samples = [sample(1, DAY)]
+    expect(summarizeUsage(samples, NOW)?.hosts).not.toBe(samples)
+  })
+})
+
+describe('usageAvailable', () => {
+  it('is true only for a report whose usage counters could be read', () => {
+    expect(usageAvailable(report([]))).toBe(true)
+    expect(usageAvailable(undefined)).toBe(false)
+    expect(
+      usageAvailable(report([], { usageUnavailable: { reason: 'unsupported', message: 'no' } }))
+    ).toBe(false)
+  })
+
+  it('ignores missing index sizes', () => {
+    const storageOnly = { storageUnavailable: { reason: 'failed' as const, message: 'no' } }
+    expect(usageAvailable(report([], storageOnly))).toBe(true)
+  })
+})
+
+describe('buildIndexRows', () => {
+  it('has no statistics without a report', () => {
+    expect(buildIndexRows([index('a_1')], undefined, NOW)).toEqual([
+      { index: index('a_1'), size: undefined, building: false, usage: null, unused: false }
+    ])
+  })
+
+  it('joins size, build state and usage by index name', () => {
+    const rows = buildIndexRows(
+      [index('a_1')],
+      report([{ name: 'a_1', size: 4096, building: true, usage: [sample(7, 2 * DAY)] }]),
+      NOW
+    )
+    expect(rows[0]?.size).toBe(4096)
+    expect(rows[0]?.building).toBe(true)
+    expect(rows[0]?.usage?.ops).toBe(7)
+  })
+
+  it('has no usage when usage counters are unavailable', () => {
+    const rows = buildIndexRows(
+      [index('a_1')],
+      report([{ name: 'a_1', size: 10, building: false, usage: [] }], {
+        usageUnavailable: { reason: 'unauthorized', message: 'not authorized' }
+      }),
+      NOW
+    )
+    expect(rows[0]?.usage).toBeNull()
+    expect(rows[0]?.unused).toBe(false)
+    expect(rows[0]?.size).toBe(10)
+  })
+
+  it('has no usage for an index the report does not mention', () => {
+    const rows = buildIndexRows([index('a_1')], report([]), NOW)
+    expect(rows[0]?.usage).toBeNull()
+    expect(rows[0]?.unused).toBe(false)
+  })
+
+  it('follows list order and ignores statistics of unlisted indexes', () => {
+    const rows = buildIndexRows(
+      [index('b_1'), index('a_1')],
+      report([
+        { name: 'a_1', size: 1, building: false, usage: [] },
+        { name: 'gone_1', size: 2, building: false, usage: [] },
+        { name: 'b_1', size: 3, building: false, usage: [] }
+      ]),
+      NOW
+    )
+    expect(rows.map((r) => [r.index.name, r.size])).toEqual([
+      ['b_1', 3],
+      ['a_1', 1]
+    ])
+  })
+
+  it('joins an index named __proto__ like any other', () => {
+    const rows = buildIndexRows(
+      [index('__proto__')],
+      report([{ name: '__proto__', size: 8, building: false, usage: [sample(2, DAY)] }]),
+      NOW
+    )
+    expect(rows[0]?.size).toBe(8)
+    expect(rows[0]?.usage?.ops).toBe(2)
+  })
+
+  describe('unused verdict', () => {
+    const unusedFor = (info: IndexInfo, samples: IndexUsageSample[], building = false): boolean =>
+      buildIndexRows([info], report([{ name: info.name, building, usage: samples }]), NOW)[0]!
+        .unused
+
+    it('flags a plain index without ops over two days', () => {
+      expect(unusedFor(index('a_1'), [sample(0, 2 * DAY)])).toBe(true)
+    })
+
+    it('flags a unique index too', () => {
+      expect(unusedFor(index('a_1', { unique: true }), [sample(0, 2 * DAY)])).toBe(true)
+    })
+
+    it('flags from exactly one day of counting on', () => {
+      expect(unusedFor(index('a_1'), [sample(0, DAY)])).toBe(true)
+    })
+
+    it('never flags the _id_ index', () => {
+      expect(unusedFor(index('_id_'), [sample(0, 2 * DAY)])).toBe(false)
+    })
+
+    it('never flags a hidden index', () => {
+      expect(unusedFor(index('a_1', { hidden: true }), [sample(0, 2 * DAY)])).toBe(false)
+    })
+
+    it('never flags a TTL index, even with expireAfterSeconds 0', () => {
+      expect(unusedFor(index('a_1', { expireAfterSeconds: 0 }), [sample(0, 2 * DAY)])).toBe(false)
+    })
+
+    it('never flags an index that is being built', () => {
+      expect(unusedFor(index('a_1'), [sample(0, 2 * DAY)], true)).toBe(false)
+    })
+
+    it('does not flag after only 23 hours of counting', () => {
+      expect(unusedFor(index('a_1'), [sample(0, 23 * HOUR)])).toBe(false)
+    })
+
+    it('does not flag an index with ops', () => {
+      expect(unusedFor(index('a_1'), [sample(1, 2 * DAY)])).toBe(false)
+    })
+
+    it('waits until every host has counted for a day', () => {
+      const samples = [sample(0, 5 * DAY, 'a:1'), sample(0, 12 * HOUR, 'b:1')]
+      expect(unusedFor(index('a_1'), samples)).toBe(false)
+    })
+  })
+})
+
+describe('sortIndexRows', () => {
+  const rows = [row('b', 300, 5), row('c', undefined, null), row('a', 100, 5), row('d', 200, 9)]
+
+  it('keeps server order in a new array for no sort', () => {
+    const sorted = sortIndexRows(rows, null)
+    expect(sorted).not.toBe(rows)
+    expect(names(sorted)).toEqual(['b', 'c', 'a', 'd'])
+  })
+
+  it('does not change the input', () => {
+    sortIndexRows(rows, { key: 'name', dir: 'asc' })
+    expect(names(rows)).toEqual(['b', 'c', 'a', 'd'])
+  })
+
+  it('sorts by name in both directions', () => {
+    expect(names(sortIndexRows(rows, { key: 'name', dir: 'asc' }))).toEqual(['a', 'b', 'c', 'd'])
+    expect(names(sortIndexRows(rows, { key: 'name', dir: 'desc' }))).toEqual(['d', 'c', 'b', 'a'])
+  })
+
+  it('puts rows without a size last in both directions', () => {
+    expect(names(sortIndexRows(rows, { key: 'size', dir: 'desc' }))).toEqual(['b', 'd', 'a', 'c'])
+    expect(names(sortIndexRows(rows, { key: 'size', dir: 'asc' }))).toEqual(['a', 'd', 'b', 'c'])
+  })
+
+  it('puts rows without usage last and keeps server order on equal ops', () => {
+    expect(names(sortIndexRows(rows, { key: 'ops', dir: 'desc' }))).toEqual(['d', 'b', 'a', 'c'])
+    expect(names(sortIndexRows(rows, { key: 'ops', dir: 'asc' }))).toEqual(['b', 'a', 'd', 'c'])
+  })
+})
+
+describe('nextSort', () => {
+  it('cycles name through ascending, descending and server order', () => {
+    const first = nextSort(null, 'name')
+    expect(first).toEqual({ key: 'name', dir: 'asc' })
+    const second = nextSort(first, 'name')
+    expect(second).toEqual({ key: 'name', dir: 'desc' })
+    expect(nextSort(second, 'name')).toBeNull()
+  })
+
+  it('cycles size and ops through descending, ascending and server order', () => {
+    for (const key of ['size', 'ops'] as const) {
+      const first = nextSort(null, key)
+      expect(first).toEqual({ key, dir: 'desc' })
+      const second = nextSort(first, key)
+      expect(second).toEqual({ key, dir: 'asc' })
+      expect(nextSort(second, key)).toBeNull()
+    }
+  })
+
+  it("starts a different key at that key's default direction", () => {
+    expect(nextSort({ key: 'name', dir: 'desc' }, 'size')).toEqual({ key: 'size', dir: 'desc' })
+    expect(nextSort({ key: 'ops', dir: 'asc' }, 'name')).toEqual({ key: 'name', dir: 'asc' })
+  })
+})
+
+describe('usageSources', () => {
+  it('lists distinct hosts and shards in sorted order', () => {
+    const sources = usageSources(
+      report([
+        {
+          name: 'a_1',
+          building: false,
+          usage: [sample(1, DAY, 'm2:27018', 'rs1'), sample(1, DAY, 'm1:27018', 'rs0')]
+        },
+        {
+          name: 'b_1',
+          building: false,
+          usage: [sample(1, DAY, 'm1:27018', 'rs0'), sample(1, DAY, 'm2:27018', 'rs1')]
+        }
+      ])
+    )
+    expect(sources).toEqual({ hosts: ['m1:27018', 'm2:27018'], shards: ['rs0', 'rs1'] })
+  })
+
+  it('has no shards on a replica set and nothing without samples', () => {
+    expect(
+      usageSources(report([{ name: 'a_1', building: false, usage: [sample(1, DAY, 'h:1')] }]))
+    ).toEqual({ hosts: ['h:1'], shards: [] })
+    expect(usageSources(report([{ name: 'a_1', building: false, usage: [] }]))).toEqual({
+      hosts: [],
+      shards: []
+    })
+  })
+})
+
+describe('usageNotes', () => {
+  const notesFor = (info: IndexInfo, ops: number): string[] => {
+    const [r] = buildIndexRows(
+      [info],
+      report([{ name: info.name, building: false, usage: [sample(ops, 3 * DAY)] }]),
+      NOW
+    )
+    return usageNotes(r!, NOW)
+  }
+
+  it('explains an unused verdict with the covered window', () => {
+    expect(notesFor(index('a_1'), 0)).toEqual(['No recorded use for 3d.'])
+  })
+
+  it('adds that an unused unique index still enforces uniqueness', () => {
+    expect(notesFor(index('a_1', { unique: true }), 0)).toEqual([
+      'No recorded use for 3d. It still enforces uniqueness on writes.'
+    ])
+  })
+
+  it('notes a hidden index', () => {
+    expect(notesFor(index('a_1', { hidden: true }), 0)).toEqual(['Hidden from the query planner.'])
+  })
+
+  it('notes that TTL deletions are not counted', () => {
+    expect(notesFor(index('a_1', { expireAfterSeconds: 3600 }), 4)).toEqual([
+      'TTL deletions are not counted.'
+    ])
+  })
+
+  it('combines hidden and TTL notes', () => {
+    expect(notesFor(index('a_1', { hidden: true, expireAfterSeconds: 0 }), 0)).toEqual([
+      'Hidden from the query planner.',
+      'TTL deletions are not counted.'
+    ])
+  })
+
+  it('has nothing to say about a used plain index', () => {
+    expect(notesFor(index('a_1', { unique: true }), 12)).toEqual([])
+  })
+})
+
+describe('unavailableText', () => {
+  const info = (reason: 'unauthorized' | 'unsupported' | 'failed') => ({ reason, message: 'x' })
+
+  it('explains each reason for usage counters', () => {
+    expect(unavailableText('usage', info('unauthorized'))).toBe(
+      'Usage counters need the indexStats privilege (e.g. the clusterMonitor role).'
+    )
+    expect(unavailableText('usage', info('unsupported'))).toBe(
+      'This server does not support $indexStats.'
+    )
+    expect(unavailableText('usage', info('failed'))).toBe('Could not read usage counters.')
+  })
+
+  it('explains each reason for index sizes', () => {
+    expect(unavailableText('storage', info('unauthorized'))).toBe(
+      'Index sizes need the collStats privilege.'
+    )
+    expect(unavailableText('storage', info('unsupported'))).toBe(
+      'This server does not report index sizes.'
+    )
+    expect(unavailableText('storage', info('failed'))).toBe('Could not read index sizes.')
+  })
+})
+
+describe('formatCount', () => {
+  it('prints counts below 1000 in full and larger ones compact', () => {
+    expect(formatCount(0)).toBe('0')
+    expect(formatCount(999)).toBe('999')
+    expect(formatCount(1000)).toBe('1K')
+    expect(formatCount(1250)).toBe('1.3K')
+    expect(formatCount(1234567)).toBe('1.2M')
+  })
+})
+
+describe('formatRate', () => {
+  it('prints daily rates down to one per day', () => {
+    expect(formatRate(100.4)).toBe('100/day')
+    expect(formatRate(2500)).toBe('2.5K/day')
+    expect(formatRate(1)).toBe('1/day')
+  })
+
+  it('switches to weekly rates below one per day', () => {
+    expect(formatRate(0.5)).toBe('4/wk')
+    expect(formatRate(1 / 7)).toBe('1/wk')
+    expect(formatRate(0.1)).toBe('<1/wk')
+  })
+
+  it('prints a zero rate per day', () => {
+    expect(formatRate(0)).toBe('0/day')
+  })
+})
+
+describe('formatAge', () => {
+  it('prints under a minute, including negative durations, as <1m', () => {
+    expect(formatAge(30_000)).toBe('<1m')
+    expect(formatAge(-5_000)).toBe('<1m')
+  })
+
+  it('prints one coarse unit', () => {
+    expect(formatAge(5 * MINUTE)).toBe('5m')
+    expect(formatAge(3 * HOUR)).toBe('3h')
+    expect(formatAge(4 * DAY)).toBe('4d')
+    expect(formatAge(89 * DAY)).toBe('89d')
+    expect(formatAge(120 * DAY)).toBe('4mo')
+    expect(formatAge(800 * DAY)).toBe('2y')
+  })
+})
diff --git a/src/renderer/src/lib/indexUsage.ts b/src/renderer/src/lib/indexUsage.ts
new file mode 100644
index 0000000..b7bd888
--- /dev/null
+++ b/src/renderer/src/lib/indexUsage.ts
@@ -0,0 +1,191 @@
+import type {
+  IndexInfo,
+  IndexRuntimeStats,
+  IndexStatsReport,
+  IndexStatsUnavailable,
+  IndexUsageSample
+} from '@shared/types'
+
+const MINUTE_MS = 60_000
+const HOUR_MS = 3_600_000
+const DAY_MS = 86_400_000
+// Extrapolating a per-day rate from under a minute of counting is noise.
+const MIN_RATE_WINDOW_MS = MINUTE_MS
+// Zero ops over less than a day says nothing: counters reset on every mongod restart.
+const UNUSED_MIN_WINDOW_MS = DAY_MS
+
+export type IndexUsageSummary = {
+  ops: number
+  /** null when every host has counted for less than a minute. */
+  opsPerDay: number | null
+  /** Earliest counter start across hosts, ms epoch. */
+  since: number
+  /** Latest counter start: all hosts have counted since then, ms epoch. */
+  coveredSince: number
+  hosts: IndexUsageSample[]
+}
+
+export type IndexRow = {
+  index: IndexInfo
+  size: number | undefined
+  building: boolean
+  usage: IndexUsageSummary | null
+  unused: boolean
+}
+
+export type IndexSortKey = 'name' | 'size' | 'ops'
+export type IndexSort = { key: IndexSortKey; dir: 'asc' | 'desc' } | null
+
+const DEFAULT_DIR: Record<IndexSortKey, 'asc' | 'desc'> = { name: 'asc', size: 'desc', ops: 'desc' }
+
+const UNAVAILABLE_TEXT: Record<
+  'usage' | 'storage',
+  Record<IndexStatsUnavailable['reason'], string>
+> = {
+  usage: {
+    unauthorized: 'Usage counters need the indexStats privilege (e.g. the clusterMonitor role).',
+    unsupported: 'This server does not support $indexStats.',
+    failed: 'Could not read usage counters.'
+  },
+  storage: {
+    unauthorized: 'Index sizes need the collStats privilege.',
+    unsupported: 'This server does not report index sizes.',
+    failed: 'Could not read index sizes.'
+  }
+}
+
+const COMPACT = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 })
+
+/** Folds per-host samples into one summary; null when there are none. */
+export function summarizeUsage(
+  samples: readonly IndexUsageSample[],
+  now: number
+): IndexUsageSummary | null {
+  if (samples.length === 0) return null
+  let ops = 0
+  let since = Infinity
+  let coveredSince = -Infinity
+  let opsPerDay: number | null = null
+  for (const sample of samples) {
+    const start = Date.parse(sample.since)
+    const window = now - start
+    ops += sample.ops
+    since = Math.min(since, start)
+    coveredSince = Math.max(coveredSince, start)
+    // Hosts reset independently, so each contributes its own rate.
+    if (window >= MIN_RATE_WINDOW_MS) opsPerDay = (opsPerDay ?? 0) + (sample.ops / window) * DAY_MS
+  }
+  return { ops, opsPerDay, since, coveredSince, hosts: [...samples] }
+}
+
+/** Whether the report carries usage counters; index sizes may still be missing. */
+export function usageAvailable(report: IndexStatsReport | undefined): boolean {
+  return report !== undefined && report.usageUnavailable === null
+}
+
+/** Joins list order with the stats report; rows follow `indexes`, stats for unlisted names are ignored. */
+export function buildIndexRows(
+  indexes: readonly IndexInfo[],
+  report: IndexStatsReport | undefined,
+  now: number
+): IndexRow[] {
+  const byName = new Map<string, IndexRuntimeStats>(report?.indexes.map((s) => [s.name, s]))
+  const withUsage = usageAvailable(report)
+  return indexes.map((index) => {
+    const stats = byName.get(index.name)
+    const building = stats?.building ?? false
+    const usage = withUsage ? summarizeUsage(stats?.usage ?? [], now) : null
+    const unused =
+      usage !== null &&
+      usage.ops === 0 &&
+      index.name !== '_id_' &&
+      index.hidden !== true &&
+      index.expireAfterSeconds === undefined &&
+      !building &&
+      now - usage.coveredSince >= UNUSED_MIN_WINDOW_MS
+    return { index, size: stats?.size, building, usage, unused }
+  })
+}
+
+/** Sorts a copy; null keeps server order, rows lacking the value go last in both directions, ties keep server order. */
+export function sortIndexRows(rows: readonly IndexRow[], sort: IndexSort): IndexRow[] {
+  const sorted = [...rows]
+  if (sort === null) return sorted
+  const sign = sort.dir === 'asc' ? 1 : -1
+  // Array#sort is stable, so equal values keep server order.
+  if (sort.key === 'name') {
+    return sorted.sort((a, b) => sign * a.index.name.localeCompare(b.index.name))
+  }
+  const value = (row: IndexRow): number | undefined =>
+    sort.key === 'size' ? row.size : row.usage?.ops
+  return sorted.sort((a, b) => {
+    const va = value(a)
+    const vb = value(b)
+    if (va === undefined || vb === undefined) {
+      return va === vb ? 0 : va === undefined ? 1 : -1
+    }
+    return sign * (va - vb)
+  })
+}
+
+/** Header click cycle: default direction, then reversed, then server order. */
+export function nextSort(current: IndexSort, key: IndexSortKey): IndexSort {
+  const dir = DEFAULT_DIR[key]
+  if (current?.key !== key) return { key, dir }
+  if (current.dir === dir) return { key, dir: dir === 'asc' ? 'desc' : 'asc' }
+  return null
+}
+
+/** Distinct sorted hosts and shards that contributed usage samples. */
+export function usageSources(report: IndexStatsReport): { hosts: string[]; shards: string[] } {
+  const hosts = new Set<string>()
+  const shards = new Set<string>()
+  for (const stats of report.indexes) {
+    for (const sample of stats.usage) {
+      hosts.add(sample.host)
+      if (sample.shard !== undefined) shards.add(sample.shard)
+    }
+  }
+  return { hosts: [...hosts].sort(), shards: [...shards].sort() }
+}
+
+/** Tooltip notes for a usage cell (unused verdict, hidden, TTL). */
+export function usageNotes(row: IndexRow, now: number): string[] {
+  const notes: string[] = []
+  if (row.unused && row.usage !== null) {
+    const unique = row.index.unique === true ? ' It still enforces uniqueness on writes.' : ''
+    notes.push(`No recorded use for ${formatAge(now - row.usage.coveredSince)}.${unique}`)
+  }
+  if (row.index.hidden === true) notes.push('Hidden from the query planner.')
+  if (row.index.expireAfterSeconds !== undefined) notes.push('TTL deletions are not counted.')
+  return notes
+}
+
+/** Explains why one statistics source is missing. */
+export function unavailableText(source: 'usage' | 'storage', info: IndexStatsUnavailable): string {
+  return UNAVAILABLE_TEXT[source][info.reason]
+}
+
+/** Op count in full below 1000, compact above (1K, 1.3K, 1.2M). */
+export function formatCount(n: number): string {
+  return n < 1000 ? String(n) : COMPACT.format(n)
+}
+
+/** Ops per day as a short rate; below one per day it switches to per week. */
+export function formatRate(opsPerDay: number): string {
+  if (opsPerDay >= 1) return `${formatCount(Math.round(opsPerDay))}/day`
+  if (opsPerDay >= 1 / 7) return `${Math.round(opsPerDay * 7)}/wk`
+  if (opsPerDay > 0) return '<1/wk'
+  return '0/day'
+}
+
+/** Duration in one coarse unit: <1m, 5m, 3h, 4d, 4mo (30-day months), 2y (365-day years). */
+export function formatAge(ms: number): string {
+  if (ms < MINUTE_MS) return '<1m'
+  if (ms < HOUR_MS) return `${Math.floor(ms / MINUTE_MS)}m`
+  if (ms < DAY_MS) return `${Math.floor(ms / HOUR_MS)}h`
+  const days = ms / DAY_MS
+  if (days < 90) return `${Math.floor(days)}d`
+  if (days < 730) return `${Math.floor(days / 30)}mo`
+  return `${Math.floor(days / 365)}y`
+}
diff --git a/src/renderer/src/lib/monacoSetup.ts b/src/renderer/src/lib/monacoSetup.ts
index b6189e6..0a28c63 100644
--- a/src/renderer/src/lib/monacoSetup.ts
+++ b/src/renderer/src/lib/monacoSetup.ts
@@ -5,12 +5,14 @@
  *
  * Imported once from main.tsx — the side effect installs the global,
  * registers the MongoBench-branded editor theme, and registers the
- * `mongo-shell` language used by the document editor and query toolbar.
+ * `mongo-shell` language (with its completion provider) used by the
+ * document editor and query toolbar.
  */
 import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'
 import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker'
 import * as monaco from 'monaco-editor'
 import { loader } from '@monaco-editor/react'
+import { registerMongoCompletion } from './completion/monacoAdapter'
 
 self.MonacoEnvironment = {
   getWorker(_workerId, label) {
@@ -169,6 +171,19 @@ monaco.languages.setMonarchTokensProvider('mongo-shell', {
   }
 })
 
+registerMongoCompletion()
+
+/** Options every editor shares; its own options are spread over them. */
+export const BASE_EDITOR_OPTIONS = {
+  // Its pending highlight rejects with 'Canceled' when a mode switch or Escape disposes the editor.
+  occurrencesHighlight: 'off',
+  // Word suggestions would offer text from other editors' models.
+  wordBasedSuggestions: 'off',
+  suggestOnTriggerCharacters: true,
+  acceptSuggestionOnEnter: 'smart',
+  suggest: { showWords: false }
+} as const satisfies monaco.editor.IStandaloneEditorConstructionOptions
+
 // Subtle, low-saturation palette. The goal is *gentle* tinting against the
 // dark editor background — values still read as text first, color second.
 monaco.editor.defineTheme('mongobench-dark', {
diff --git a/src/renderer/src/lib/mongoFormat.test.ts b/src/renderer/src/lib/mongoFormat.test.ts
new file mode 100644
index 0000000..b3e8f8c
--- /dev/null
+++ b/src/renderer/src/lib/mongoFormat.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest'
+import { formatMongoSource } from './mongoFormat'
+import { parseMongoQuery } from './mongoQueryLang'
+
+const options = { timezone: 'UTC', uuidEncoding: 'default' as const, indent: 2, printWidth: 80 }
+
+describe('formatMongoSource', () => {
+  it('re-prints a short filter on one line', () => {
+    expect(formatMongoSource('{status:"A",n:{$gt:1}}', options)).toBe(
+      '{ status: "A", n: { $gt: 1 } }'
+    )
+  })
+
+  it('breaks a pipeline that does not fit and keeps short stages inline', () => {
+    const source = '[{$match:{status:"A",n:{$gte:10}}},{$group:{_id:"$cust",n:{$sum:1}}}]'
+    expect(formatMongoSource(source, options)).toBe(
+      [
+        '[',
+        '  { $match: { status: "A", n: { $gte: 10 } } },',
+        '  { $group: { _id: "$cust", n: { $sum: 1 } } }',
+        ']'
+      ].join('\n')
+    )
+  })
+
+  it('keeps shell helpers instead of EJSON wrappers', () => {
+    const source = `{
+      _id: ObjectId("507f1f77bcf86cd799439011"), n: NumberLong("5"), d: 5.0,
+      re: /^a/i, u: JUUID("550e8400-e29b-41d4-a716-446655440000"), m: MinKey
+    }`
+    const text = formatMongoSource(source, { ...options, uuidEncoding: 'java' })
+    expect(text).toContain('ObjectId("507f1f77bcf86cd799439011")')
+    expect(text).toContain('NumberLong("5")')
+    expect(text).toContain('d: 5.0')
+    expect(text).toContain('/^a/i')
+    expect(text).toContain('JUUID("550e8400-e29b-41d4-a716-446655440000")')
+    expect(text).toContain('MinKey()')
+    expect(text).not.toContain('$oid')
+  })
+
+  it('drops comments', () => {
+    expect(formatMongoSource('{ a: 1 /* why */ } // note', options)).toBe('{ a: 1 }')
+  })
+
+  it('round-trips to the same value', () => {
+    for (const source of [
+      '{ a: { $in: [1, 2.5, 3.0, -0.0] }, b: /x\\/y/, c: NumberDecimal("1.50") }',
+      '[{ $match: { at: { $lt: ISODate("2024-01-01T00:00:00.000Z") } } }, { $sort: { at: -1 } }]',
+      '{ u: UUID("550e8400-e29b-41d4-a716-446655440000"), t: Timestamp(1700000000, 7), x: NumberDouble("NaN") }'
+    ]) {
+      const formatted = formatMongoSource(source, options)
+      expect(formatted, source).not.toBeNull()
+      expect(parseMongoQuery(formatted!), source).toEqual(parseMongoQuery(source))
+    }
+  })
+
+  it('returns null for blank or invalid source', () => {
+    expect(formatMongoSource('', options)).toBeNull()
+    expect(formatMongoSource('  \n ', options)).toBeNull()
+    expect(formatMongoSource('{ a: }', options)).toBeNull()
+  })
+})
diff --git a/src/renderer/src/lib/mongoFormat.ts b/src/renderer/src/lib/mongoFormat.ts
new file mode 100644
index 0000000..9cef839
--- /dev/null
+++ b/src/renderer/src/lib/mongoFormat.ts
@@ -0,0 +1,9 @@
+import { parseMongoQuery } from './mongoQueryLang'
+import { serializeMongoValue, type SerializeOptions } from './mongoQuerySerialize'
+
+/** Re-prints mongo-shell source with helpers preserved; null when blank or invalid. Comments are dropped. */
+export function formatMongoSource(source: string, options: SerializeOptions): string | null {
+  const parsed = parseMongoQuery(source)
+  if (!parsed.ok || parsed.ejson === '') return null
+  return serializeMongoValue(parsed.value, options)
+}
diff --git a/src/renderer/src/lib/mongoQueryLang.test.ts b/src/renderer/src/lib/mongoQueryLang.test.ts
index b7d45ec..a4f6be5 100644
--- a/src/renderer/src/lib/mongoQueryLang.test.ts
+++ b/src/renderer/src/lib/mongoQueryLang.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { parseMongoDocuments, parseMongoQuery } from './mongoQueryLang'
+import { EJSON } from 'bson'
+import { ParseError, parseMongoDocuments, parseMongoQuery, tokenize } from './mongoQueryLang'
 
 describe('parseMongoQuery', () => {
   it('returns empty ejson for blank input', () => {
@@ -142,6 +143,145 @@ describe('parseMongoQuery', () => {
         payload: { $binary: { base64: 'AQID', subType: '00' } }
       })
   })
+
+  it('keeps integral number literals with a dot or exponent as doubles', () => {
+    const r = parseMongoQuery('{ a: 5.0, b: -0.0, c: 1e3, d: 1E+21, e: 7 }')
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(JSON.parse(r.ejson)).toEqual({
+        a: { $numberDouble: '5.0' },
+        b: { $numberDouble: '-0.0' },
+        c: { $numberDouble: '1e3' },
+        d: { $numberDouble: '1E+21' },
+        e: 7
+      })
+    }
+  })
+
+  it('leaves fractional literals as plain JSON numbers', () => {
+    const r = parseMongoQuery('{a: 1.5}')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.ejson).toBe('{"a":1.5}')
+  })
+
+  it('stores integral doubles as BSON Double on the main side', () => {
+    const r = parseMongoQuery('{ a: 100.0 }')
+    expect(r.ok).toBe(true)
+    if (!r.ok) return
+    const doc = EJSON.parse(r.ejson, { relaxed: false }) as { a: { _bsontype: string } }
+    expect(doc.a._bsontype).toBe('Double')
+  })
+
+  it('passes integral doubles to helpers as plain numbers', () => {
+    const r = parseMongoQuery('{ a: NumberLong(5.0), b: ISODate(1.7e12), c: NumberInt(2.0) }')
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(JSON.parse(r.ejson)).toEqual({
+        a: { $numberLong: '5' },
+        b: { $date: { $numberLong: '1700000000000' } },
+        c: { $numberInt: '2' }
+      })
+    }
+  })
+
+  it('keeps an integral double as the id of a DBRef', () => {
+    const r = parseMongoQuery('{ r: DBRef("users", 5.0) }')
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(JSON.parse(r.ejson)).toEqual({ r: { $ref: 'users', $id: { $numberDouble: '5.0' } } })
+    }
+  })
+
+  it('accepts Double / NumberDouble with numbers and numeric strings', () => {
+    const r = parseMongoQuery(
+      '[Double(5), NumberDouble(2.5), Double(-0.0), NumberDouble("NaN"), Double("Infinity"), Double("-Infinity"), Double("-0.0"), Double("1e+21")]'
+    )
+    expect(r.ok).toBe(true)
+    if (r.ok) {
+      expect(JSON.parse(r.ejson)).toEqual([
+        { $numberDouble: '5' },
+        { $numberDouble: '2.5' },
+        { $numberDouble: '-0.0' },
+        { $numberDouble: 'NaN' },
+        { $numberDouble: 'Infinity' },
+        { $numberDouble: '-Infinity' },
+        { $numberDouble: '-0.0' },
+        { $numberDouble: '1e+21' }
+      ])
+    }
+  })
+
+  it('rejects Double with a non-numeric argument', () => {
+    for (const input of [
+      'Double("abc")',
+      'Double("")',
+      'Double("0x10")',
+      'Double()',
+      'Double({})'
+    ]) {
+      const r = parseMongoQuery(input)
+      expect(r.ok, input).toBe(false)
+      if (!r.ok) expect(r.error).toMatch(/Double\(\) argument must be a number or numeric string/)
+    }
+  })
+
+  it('mints a fresh ObjectId for ObjectId() without arguments', () => {
+    const a = parseMongoQuery('ObjectId()')
+    const b = parseMongoQuery('ObjectId()')
+    expect(a.ok && b.ok).toBe(true)
+    if (!a.ok || !b.ok) return
+    const idA = (a.value as { $oid: string }).$oid
+    const idB = (b.value as { $oid: string }).$oid
+    expect(idA).toMatch(/^[0-9a-f]{24}$/)
+    expect(idB).toMatch(/^[0-9a-f]{24}$/)
+    expect(idA).not.toBe(idB)
+    expect(idA).not.toBe('000000000000000000000000')
+    const seconds = parseInt(idA.slice(0, 8), 16)
+    expect(Math.abs(seconds - Date.now() / 1000)).toBeLessThanOrEqual(5)
+  })
+
+  it('rejects ISODate with an unparseable string', () => {
+    for (const input of [
+      'ISODate("1-01-01T00:00:00+00:53:28")',
+      'ISODate("1850-06-01T00:53:28.000+00:53:28")',
+      'new Date("not a date")'
+    ]) {
+      const r = parseMongoQuery(input)
+      expect(r.ok, input).toBe(false)
+      if (!r.ok) expect(r.error).toMatch(/^Invalid date "/)
+    }
+  })
+
+  it('keeps "__proto__" keys as own properties', () => {
+    const r = parseMongoQuery('{ a: 1, __proto__: { x: NumberInt(1) }, b: { "__proto__": "s" } }')
+    expect(r.ok).toBe(true)
+    if (!r.ok) return
+    expect(r.ejson).toBe('{"a":1,"__proto__":{"x":{"$numberInt":"1"}},"b":{"__proto__":"s"}}')
+    expect(Object.getPrototypeOf(r.value)).toBe(Object.prototype)
+  })
+})
+
+describe('tokenize', () => {
+  it('emits "." and ";" as punctuation in shell mode', () => {
+    const tokens = tokenize('db.users.find();', { shell: true })
+    expect(
+      tokens.map((t) => (t.type === 'punct' || t.type === 'ident' ? t.value : t.type))
+    ).toEqual(['db', '.', 'users', '.', 'find', '(', ')', ';'])
+  })
+
+  it('rejects a lone "." without the shell option', () => {
+    expect(() => tokenize('a.b')).toThrow(ParseError)
+  })
+
+  it('still reads ".5" as a number in shell mode', () => {
+    const tokens = tokenize('.5', { shell: true })
+    expect(tokens).toEqual([{ type: 'number', value: '.5', offset: 0 }])
+  })
+
+  it('reads a regex containing ")" and a quote after "(" in shell mode', () => {
+    const tokens = tokenize("find(/a)'/)", { shell: true })
+    expect(tokens[2]).toEqual({ type: 'regex', pattern: "a)'", flags: '', offset: 5 })
+  })
 })
 
 describe('parseMongoDocuments', () => {
@@ -224,4 +364,10 @@ describe('parseMongoDocuments', () => {
     expect(r.ok).toBe(false)
     if (!r.ok) expect(r.error).toMatch(/must be an object/)
   })
+
+  it('keeps "__proto__" keys of each document', () => {
+    const r = parseMongoDocuments('{ __proto__: { x: 1 } }\n{ "__proto__": "s" }')
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.documents).toEqual(['{"__proto__":{"x":1}}', '{"__proto__":"s"}'])
+  })
 })
diff --git a/src/renderer/src/lib/mongoQueryLang.ts b/src/renderer/src/lib/mongoQueryLang.ts
index 93a2766..8c8987b 100644
--- a/src/renderer/src/lib/mongoQueryLang.ts
+++ b/src/renderer/src/lib/mongoQueryLang.ts
@@ -9,12 +9,14 @@
  *   - trailing commas                      `{ a: 1, }`
  *   - line / block comments                `// ...`  and  / *...* /
  *   - regex literals                       `/^foo/i`
+ *   - integral doubles                     `5.0`, `1e3` stay doubles (`{"$numberDouble":"5.0"}`)
  *   - shell helpers:
- *       ObjectId("…")
+ *       ObjectId("…")  /  ObjectId()       (mints a fresh id)
  *       ISODate("…")  /  new Date("…")  /  Date("…")
  *       NumberLong("…")  /  Long("…")
  *       NumberDecimal("…")  /  Decimal128("…")
  *       NumberInt(…)  /  Int32(…)
+ *       NumberDouble(…)  /  Double(…)      (number, or "NaN" / "Infinity" / "-Infinity" / numeric string)
  *       UUID("…")
  *       BinData(subType, "base64")
  *       Timestamp(t, i)
@@ -28,6 +30,7 @@
  * Each helper is rewritten into its EJSON wrapper (`{"$oid":...}`,
  * `{"$date":...}`, …) — which the existing backend already understands.
  */
+import { ObjectId } from 'bson'
 
 export type ParseSuccess = { ok: true; ejson: string; value: unknown }
 export type ParseFailure = { ok: false; error: string; offset: number }
@@ -96,7 +99,8 @@ export function parseMongoDocuments(input: string): DocumentsParseResult {
   }
 }
 
-class ParseError extends Error {
+/** A syntax error at `offset` (UTF-16 index into the parsed source). */
+export class ParseError extends Error {
   constructor(
     message: string,
     public readonly offset: number
@@ -106,9 +110,11 @@ class ParseError extends Error {
   }
 }
 
-type PunctValue = '{' | '}' | '[' | ']' | ':' | ',' | '(' | ')'
+/** `.` and `;` only occur in shell mode. */
+export type PunctValue = '{' | '}' | '[' | ']' | ':' | ',' | '(' | ')' | '.' | ';'
 
-type Token =
+/** A lexical token; `offset` is the index of its first character. */
+export type Token =
   | { type: 'punct'; value: PunctValue; offset: number }
   | { type: 'string'; value: string; offset: number }
   | { type: 'number'; value: string; offset: number }
@@ -117,7 +123,15 @@ type Token =
 
 const REGEX_OK_AFTER = new Set<PunctValue>([':', ',', '[', '('])
 
-function tokenize(src: string): Token[] {
+const NUMBER_RE = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/
+
+/**
+ * Splits source into tokens, skipping whitespace and comments.
+ * @param options.shell also emits `.` and `;` so command chains like `db.c.find()` tokenize.
+ * @throws ParseError on characters or literals the language doesn't know.
+ */
+export function tokenize(src: string, options: { shell?: boolean } = {}): Token[] {
+  const punctuation = options.shell ? '{}[]:,().;' : '{}[]:,()'
   const out: Token[] = []
   let i = 0
   let lastSignificant: Token | null = null
@@ -227,7 +241,7 @@ function tokenize(src: string): Token[] {
     }
 
     // number
-    const numMatch = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/.exec(src.slice(i))
+    const numMatch = NUMBER_RE.exec(src.slice(i))
     if (numMatch && ((c >= '0' && c <= '9') || c === '.' || c === '-' || c === '+')) {
       // disambiguate: a leading +/- followed by no digit isn't a number
       const m = numMatch[0]
@@ -241,7 +255,7 @@ function tokenize(src: string): Token[] {
     }
 
     // punctuation
-    if ('{}[]:,()'.includes(c)) {
+    if (punctuation.includes(c)) {
       const t: Token = { type: 'punct', value: c as PunctValue, offset: i }
       out.push(t)
       lastSignificant = t
@@ -265,7 +279,8 @@ function tokenize(src: string): Token[] {
   return out
 }
 
-class Parser {
+/** Recursive-descent parser over `tokenize` output; values come back as EJSON wrapper trees. */
+export class Parser {
   private pos = 0
   constructor(
     private readonly tokens: Token[],
@@ -284,7 +299,7 @@ class Parser {
     }
     if (t.type === 'number') {
       this.advance()
-      return parseNumberLiteral(t.value)
+      return parseNumberLiteral(t.value, t.offset)
     }
     if (t.type === 'regex') {
       this.advance()
@@ -322,7 +337,13 @@ class Parser {
       }
       this.expectPunct(':')
       const value = this.parseValue()
-      obj[key] = value
+      // Assigning "__proto__" would call the prototype setter and drop the stored field.
+      Object.defineProperty(obj, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true
+      })
       const sep = this.peek()
       if (sep && sep.type === 'punct' && sep.value === ',') {
         this.advance()
@@ -398,7 +419,7 @@ class Parser {
     const next = this.peek()
     const hasArgs = next?.type === 'punct' && next.value === '('
     if (hasArgs) {
-      const args = this.parseCallArgs()
+      const args = this.parseArgs().map((arg) => arg.value)
       return applyHelper(name, args, t.offset)
     }
     // Standalone helpers (no parens)
@@ -408,9 +429,10 @@ class Parser {
     throw new ParseError(`Unknown identifier "${name}"`, t.offset)
   }
 
-  parseCallArgs(): unknown[] {
+  /** Parses `(value, …)`; each argument keeps the offset of its first token. */
+  parseArgs(): Array<{ value: unknown; offset: number }> {
     this.expectPunct('(')
-    const args: unknown[] = []
+    const args: Array<{ value: unknown; offset: number }> = []
     if (
       this.peek()?.type === 'punct' &&
       (this.peek() as Token & { value: PunctValue }).value === ')'
@@ -419,7 +441,8 @@ class Parser {
       return args
     }
     for (;;) {
-      args.push(this.parseValue())
+      const offset = this.peek()?.offset ?? this.src.length
+      args.push({ value: this.parseValue(), offset })
       const sep = this.peek()
       if (sep && sep.type === 'punct' && sep.value === ',') {
         this.advance()
@@ -461,15 +484,13 @@ class Parser {
   }
 }
 
-function applyHelper(name: string, args: unknown[], offset: number): unknown {
+function applyHelper(name: string, rawArgs: unknown[], offset: number): unknown {
+  // Number arguments configure the helper (`NumberLong(5.0)` means 5); a DBRef id is a stored value.
+  const args = name === 'DBRef' ? rawArgs : rawArgs.map(plainNumber)
   switch (name) {
     case 'ObjectId':
     case 'objectId': {
-      if (args.length === 0) {
-        // mongo shell allows ObjectId() to mint one — we leave generation to the server.
-        // Use placeholder so the backend can see the intent (driver auto-fills _id on insert anyway).
-        return { $oid: '000000000000000000000000' }
-      }
+      if (args.length === 0) return { $oid: new ObjectId().toHexString() }
       requireString(args[0], 'ObjectId', offset)
       return { $oid: args[0] as string }
     }
@@ -477,7 +498,11 @@ function applyHelper(name: string, args: unknown[], offset: number): unknown {
     case 'Date': {
       if (args.length === 0) return { $date: new Date().toISOString() }
       const a = args[0]
-      if (typeof a === 'string') return { $date: a }
+      if (typeof a === 'string') {
+        // Main would store an unparseable date string as 1970-01-01 without an error.
+        if (Number.isNaN(Date.parse(a))) throw new ParseError(`Invalid date "${a}"`, offset)
+        return { $date: a }
+      }
       if (typeof a === 'number') return { $date: { $numberLong: String(a) } }
       throw new ParseError(`${name}() argument must be a string or number`, offset)
     }
@@ -499,6 +524,15 @@ function applyHelper(name: string, args: unknown[], offset: number): unknown {
       if (typeof v === 'string' || typeof v === 'number') return { $numberDecimal: String(v) }
       throw new ParseError(`${name}() argument must be a string or number`, offset)
     }
+    case 'NumberDouble':
+    case 'Double': {
+      const v = args[0]
+      if (typeof v === 'number') return { $numberDouble: Object.is(v, -0) ? '-0.0' : String(v) }
+      if (typeof v === 'string' && (NON_FINITE_DOUBLES.has(v) || isFiniteDecimal(v))) {
+        return { $numberDouble: v }
+      }
+      throw new ParseError(`${name}() argument must be a number or numeric string`, offset)
+    }
     case 'UUID': {
       requireString(args[0], 'UUID', offset)
       return { $uuid: args[0] as string }
@@ -583,12 +617,32 @@ function regexToEjson(pattern: string, flags: string): unknown {
   return { $regularExpression: { pattern, options: flags } }
 }
 
-function parseNumberLiteral(text: string): number {
+const NON_FINITE_DOUBLES = new Set(['NaN', 'Infinity', '-Infinity'])
+
+// Main parses `$numberDouble` with parseFloat, which reads hex or blank strings differently than Number().
+const isFiniteDecimal = (text: string): boolean =>
+  NUMBER_RE.exec(text)?.[0] === text && Number.isFinite(Number(text))
+
+function parseNumberLiteral(text: string, offset: number): unknown {
   const n = Number(text)
-  if (!Number.isFinite(n)) throw new ParseError(`Invalid number "${text}"`, 0)
+  if (!Number.isFinite(n)) throw new ParseError(`Invalid number "${text}"`, offset)
+  // Main maps an integral JSON number to Int32/Int64; the literal's dot or exponent says it's a double.
+  if (Number.isInteger(n) && /[.eE]/.test(text)) return { $numberDouble: text }
   return n
 }
 
+function plainNumber(value: unknown): unknown {
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.keys(value).length === 1 &&
+    typeof (value as { $numberDouble?: unknown }).$numberDouble === 'string'
+  ) {
+    return Number((value as { $numberDouble: string }).$numberDouble)
+  }
+  return value
+}
+
 function encodeJavaLegacyUuid(uuid: string): string | null {
   const hex = uuid.replace(/-/g, '')
   if (!/^[0-9a-fA-F]{32}$/.test(hex)) return null
diff --git a/src/renderer/src/lib/mongoQuerySerialize.test.ts b/src/renderer/src/lib/mongoQuerySerialize.test.ts
index 9778c27..a358976 100644
--- a/src/renderer/src/lib/mongoQuerySerialize.test.ts
+++ b/src/renderer/src/lib/mongoQuerySerialize.test.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { EJSON } from 'bson'
 import { parseMongoQuery } from './mongoQueryLang'
-import { serializeMongoValue } from './mongoQuerySerialize'
+import { isBareKey, serializeMongoValue } from './mongoQuerySerialize'
 
 const roundTrip = (
   canonicalEjsonObject: unknown,
@@ -78,6 +78,95 @@ describe('serializeMongoValue', () => {
     expect(text).toContain('"with space":')
     expect(text).toContain('"has-dash":')
   })
+
+  it('tells which keys are written without quotes', () => {
+    expect(['name', '_id', '$set', 'a1'].every(isBareKey)).toBe(true)
+    expect(['with space', 'has-dash', 'a.b', '1a', ''].some(isBareKey)).toBe(false)
+  })
+
+  it('renders doubles so they read back as doubles', () => {
+    const render = (raw: string): string => serializeMongoValue({ $numberDouble: raw })
+    expect(render('100.0')).toBe('100.0')
+    expect(render('2.5')).toBe('2.5')
+    expect(render('-0.0')).toBe('-0.0')
+    expect(render('1e+21')).toBe('1e+21')
+    expect(render('100000000000000000000.0')).toBe('100000000000000000000.0')
+    expect(render('NaN')).toBe('NumberDouble("NaN")')
+    expect(render('Infinity')).toBe('NumberDouble("Infinity")')
+    expect(render('-Infinity')).toBe('NumberDouble("-Infinity")')
+  })
+
+  it('falls back to RegExp("…", "…") when a literal would not read back', () => {
+    const render = (pattern: string, options = ''): string =>
+      serializeMongoValue({ $regularExpression: { pattern, options } })
+    expect(render('^https://x')).toBe('RegExp("^https://x", "")')
+    expect(render('a\nb', 'i')).toBe('RegExp("a\\nb", "i")')
+    expect(render('a b', 'x')).toBe('RegExp("a b", "x")')
+    expect(render('')).toBe('RegExp("", "")')
+    expect(render('*a')).toBe('RegExp("*a", "")')
+    expect(render('[a')).toBe('RegExp("[a", "")')
+    expect(render('a\\')).toBe('RegExp("a\\\\", "")')
+    expect(render('a\\\\', 'i')).toBe('/a\\\\/i')
+    expect(render('[/]')).toBe('RegExp("[/]", "")')
+  })
+})
+
+describe('serializeMongoValue printWidth', () => {
+  it('keeps short objects and arrays on one line', () => {
+    const text = serializeMongoValue({ a: 1, b: { c: [1, 2] } }, { indent: 2, printWidth: 80 })
+    expect(text).toBe('{ a: 1, b: { c: [1, 2] } }')
+  })
+
+  it('expands values that do not fit and keeps fitting children inline', () => {
+    const value = {
+      name: 'x'.repeat(40),
+      address: { city: 'Berlin', zip: '10115' },
+      tags: ['a', 'b']
+    }
+    const text = serializeMongoValue(value, { indent: 2, printWidth: 80 })
+    expect(text).toBe(
+      [
+        '{',
+        `  name: "${'x'.repeat(40)}",`,
+        '  address: { city: "Berlin", zip: "10115" },',
+        '  tags: ["a", "b"]',
+        '}'
+      ].join('\n')
+    )
+  })
+
+  it('counts indentation and the key toward the width', () => {
+    const fits = serializeMongoValue({ key: { s: 'x'.repeat(64) } }, { indent: 2, printWidth: 80 })
+    expect(fits).toBe(`{\n  key: { s: "${'x'.repeat(64)}" }\n}`)
+    const tooWide = serializeMongoValue(
+      { key: { s: 'x'.repeat(65) } },
+      { indent: 2, printWidth: 80 }
+    )
+    expect(tooWide).toBe(`{\n  key: {\n    s: "${'x'.repeat(65)}"\n  }\n}`)
+  })
+
+  it('counts startColumn toward the width of the outermost value', () => {
+    const pipeline = [{ $match: { status: 'A' } }, { $group: { _id: '$cust', n: { $sum: 1 } } }]
+    const flat = '[{ $match: { status: "A" } }, { $group: { _id: "$cust", n: { $sum: 1 } } }]'
+    expect(serializeMongoValue(pipeline, { indent: 2, printWidth: 80 })).toBe(flat)
+    expect(serializeMongoValue(pipeline, { indent: 2, printWidth: 80, startColumn: 20 })).toBe(
+      [
+        '[',
+        '  { $match: { status: "A" } },',
+        '  { $group: { _id: "$cust", n: { $sum: 1 } } }',
+        ']'
+      ].join('\n')
+    )
+  })
+
+  it('leaves the default and the compact output unchanged', () => {
+    expect(serializeMongoValue({ a: { b: [1] } })).toBe(
+      '{\n  a: {\n    b: [\n      1\n    ]\n  }\n}'
+    )
+    expect(serializeMongoValue({ a: { b: [1] } }, { indent: 0, printWidth: 80 })).toBe(
+      '{a:{b:[1]}}'
+    )
+  })
 })
 
 describe('parse → serialize round-trips', () => {
@@ -124,6 +213,33 @@ describe('parse → serialize round-trips', () => {
     })
   }
 
+  const canonicalCases = [
+    '{"a":{"$numberDouble":"100.0"}}',
+    '{"a":{"$numberDouble":"2.5"}}',
+    '{"a":{"$numberDouble":"-0.0"}}',
+    '{"a":{"$numberDouble":"1e+21"}}',
+    '{"a":{"$numberDouble":"100000000000000000000.0"}}',
+    '{"a":{"$numberDouble":"NaN"}}',
+    '{"a":{"$numberDouble":"Infinity"}}',
+    '{"a":{"$numberDouble":"-Infinity"}}',
+    '{"a":{"$numberInt":"5"}}',
+    '{"a":{"$numberLong":"5"}}',
+    '{"a":{"$regularExpression":{"pattern":"^https://x","options":""}}}',
+    '{"a":{"$regularExpression":{"pattern":"a/b","options":"i"}}}',
+    '{"a":{"$regularExpression":{"pattern":"a\\\\\\\\","options":""}}}',
+    '{"a":{"$regularExpression":{"pattern":"a\\\\","options":""}}}',
+    '{"a":{"$regularExpression":{"pattern":"line\\nbreak","options":"m"}}}',
+    '{"a":{"$regularExpression":{"pattern":"a b","options":"x"}}}'
+  ]
+
+  for (const canonical of canonicalCases) {
+    it(`keeps the BSON type of ${canonical} through serialize and parse`, () => {
+      const { parsed } = roundTrip(JSON.parse(canonical))
+      const stored = EJSON.parse(JSON.stringify(parsed), { relaxed: false })
+      expect(EJSON.stringify(stored, { relaxed: false })).toBe(canonical)
+    })
+  }
+
   it('round-trips JUUID under java encoding', () => {
     const r = parseMongoQuery('JUUID("550e8400-e29b-41d4-a716-446655440000")')
     expect(r.ok).toBe(true)
diff --git a/src/renderer/src/lib/mongoQuerySerialize.ts b/src/renderer/src/lib/mongoQuerySerialize.ts
index 4c1cac9..6703b2c 100644
--- a/src/renderer/src/lib/mongoQuerySerialize.ts
+++ b/src/renderer/src/lib/mongoQuerySerialize.ts
@@ -6,12 +6,13 @@
  *
  *   { $oid: "…" }                                    →  ObjectId("…")
  *   { $date: "…" } / { $date: { $numberLong: ms } }  →  ISODate("…")
- *   { $numberLong: "…" } / Int / Decimal / Double    →  NumberLong("…") / NumberInt(…) / NumberDecimal("…") / number
+ *   { $numberLong: "…" } / Int / Decimal             →  NumberLong("…") / NumberInt(…) / NumberDecimal("…")
+ *   { $numberDouble: "…" }                           →  5.0 / 2.5 / -0.0 / 1e+21 / NumberDouble("NaN")
  *   { $uuid: "…" }                                   →  UUID("…")
  *   { $binary: { base64, subType: "04" } }           →  UUID("…")    (decoded)
  *   { $binary: { base64, subType: "03" } } + java    →  JUUID("…")   (decoded with java byte order)
  *   { $binary: { base64, subType: x } }              →  BinData(<int>, "…")
- *   { $regularExpression: { pattern, options } }     →  /pattern/options
+ *   { $regularExpression: { pattern, options } }     →  /pattern/options, or RegExp("…", "…") when no literal reads back
  *   { $timestamp: { t, i } }                         →  Timestamp(t, i)
  *   { $minKey: 1 } / { $maxKey: 1 }                  →  MinKey() / MaxKey()
  *   { $undefined: true }                             →  undefined
@@ -31,20 +32,40 @@ export type SerializeOptions = {
    * the user saves.
    */
   timezone?: string
+  /** Line length within which an object or array stays on one line; needs indent > 0. */
+  printWidth?: number
+  /** Column the value starts at on its first line; counts toward printWidth. */
+  startColumn?: number
 }
 
 export function serializeMongoValue(value: unknown, options: SerializeOptions = {}): string {
   const indent = options.indent ?? 2
+  const uuidEncoding = options.uuidEncoding ?? 'default'
+  const timezone = options.timezone ?? 'UTC'
+  const inline: Ctx = {
+    uuidEncoding,
+    timezone,
+    indentSize: 0,
+    indentStr: '',
+    nl: '',
+    sep: ': ',
+    listSep: ', ',
+    pad: ' ',
+    fit: null
+  }
   const ctx: Ctx = {
-    uuidEncoding: options.uuidEncoding ?? 'default',
-    timezone: options.timezone ?? 'UTC',
+    uuidEncoding,
+    timezone,
     indentSize: indent,
     indentStr: indent > 0 ? ' '.repeat(indent) : '',
     nl: indent > 0 ? '\n' : '',
     sep: indent > 0 ? ': ' : ':',
-    listSep: indent > 0 ? ', ' : ','
+    listSep: indent > 0 ? ', ' : ',',
+    pad: '',
+    fit:
+      indent > 0 && options.printWidth !== undefined ? { width: options.printWidth, inline } : null
   }
-  return write(value, 0, ctx)
+  return write(value, 0, ctx, options.startColumn ?? 0)
 }
 
 type Ctx = {
@@ -55,11 +76,21 @@ type Ctx = {
   nl: string
   sep: string
   listSep: string
+  /** Space inside one-line object braces. */
+  pad: string
+  /** Set when objects and arrays may stay on one line up to `width` columns. */
+  fit: { width: number; inline: Ctx } | null
 }
 
 const IDENT_RE = /^[A-Za-z_$][\w$]*$/
 
-function write(value: unknown, depth: number, ctx: Ctx): string {
+/** Whether `key` is written without quotes, as an identifier. */
+export function isBareKey(key: string): boolean {
+  return IDENT_RE.test(key)
+}
+
+// `prefix` is the width of what precedes the value on its first line after the indentation.
+function write(value: unknown, depth: number, ctx: Ctx, prefix = 0): string {
   if (value === null) return 'null'
   if (value === undefined) return 'undefined'
   if (typeof value === 'boolean') return value ? 'true' : 'false'
@@ -68,20 +99,28 @@ function write(value: unknown, depth: number, ctx: Ctx): string {
     return String(value)
   }
   if (typeof value === 'string') return JSON.stringify(value)
-  if (Array.isArray(value)) return writeArray(value, depth, ctx)
+  if (Array.isArray(value)) return writeArray(value, depth, ctx, prefix)
   if (typeof value === 'object') {
     const helper = matchHelper(value as Record<string, unknown>, ctx)
     if (helper !== null) return helper
-    return writeObject(value as Record<string, unknown>, depth, ctx)
+    return writeObject(value as Record<string, unknown>, depth, ctx, prefix)
   }
   return JSON.stringify(value)
 }
 
-function writeArray(arr: unknown[], depth: number, ctx: Ctx): string {
+function inlineIfFits(value: object, depth: number, ctx: Ctx, prefix: number): string | null {
+  if (ctx.fit === null) return null
+  const flat = write(value, depth, ctx.fit.inline)
+  return depth * ctx.indentSize + prefix + flat.length <= ctx.fit.width ? flat : null
+}
+
+function writeArray(arr: unknown[], depth: number, ctx: Ctx, prefix: number): string {
   if (arr.length === 0) return '[]'
   if (ctx.indentSize === 0) {
     return '[' + arr.map((v) => write(v, depth + 1, ctx)).join(ctx.listSep) + ']'
   }
+  const fitted = inlineIfFits(arr, depth, ctx, prefix)
+  if (fitted !== null) return fitted
   const inner = ctx.indentStr.repeat(depth + 1)
   const closer = ctx.indentStr.repeat(depth)
   return (
@@ -94,15 +133,25 @@ function writeArray(arr: unknown[], depth: number, ctx: Ctx): string {
   )
 }
 
-function writeObject(obj: Record<string, unknown>, depth: number, ctx: Ctx): string {
+function writeObject(
+  obj: Record<string, unknown>,
+  depth: number,
+  ctx: Ctx,
+  prefix: number
+): string {
   const keys = Object.keys(obj)
   if (keys.length === 0) return '{}'
+  const fitted = inlineIfFits(obj, depth, ctx, prefix)
+  if (fitted !== null) return fitted
   const inner = ctx.indentStr.repeat(depth + 1)
   const closer = ctx.indentStr.repeat(depth)
-  const writeKey = (k: string): string => (IDENT_RE.test(k) ? k : JSON.stringify(k))
-  const lines = keys.map((k) => `${inner}${writeKey(k)}${ctx.sep}${write(obj[k], depth + 1, ctx)}`)
+  const writeKey = (k: string): string => (isBareKey(k) ? k : JSON.stringify(k))
+  const lines = keys.map((k) => {
+    const head = writeKey(k) + ctx.sep
+    return `${inner}${head}${write(obj[k], depth + 1, ctx, head.length)}`
+  })
   if (ctx.indentSize === 0) {
-    return '{' + lines.map((l) => l.trimStart()).join(ctx.listSep) + '}'
+    return '{' + ctx.pad + lines.map((l) => l.trimStart()).join(ctx.listSep) + ctx.pad + '}'
   }
   return '{' + ctx.nl + lines.join(',' + ctx.nl) + ctx.nl + closer + '}'
 }
@@ -135,8 +184,11 @@ function matchHelper(obj: Record<string, unknown>, ctx: Ctx): string | null {
   }
   if (keys.length === 1 && typeof obj['$numberDouble'] === 'string') {
     const n = Number(obj['$numberDouble'])
-    if (Number.isFinite(n)) return String(n)
-    return `NumberDouble(${JSON.stringify(obj['$numberDouble'])})`
+    if (!Number.isFinite(n)) return `NumberDouble(${JSON.stringify(String(n))})`
+    if (Object.is(n, -0)) return '-0.0'
+    // Without a dot or exponent the parser reads the literal back as an integer.
+    const text = String(n)
+    return /[.e]/.test(text) ? text : `${text}.0`
   }
 
   if (keys.length === 1 && typeof obj['$uuid'] === 'string') {
@@ -153,8 +205,9 @@ function matchHelper(obj: Record<string, unknown>, ctx: Ctx): string | null {
     typeof (obj['$regularExpression'] as Record<string, unknown>)['pattern'] === 'string'
   ) {
     const r = obj['$regularExpression'] as { pattern: string; options?: string }
-    const escaped = r.pattern.replace(/(^|[^\\])\//g, '$1\\/')
-    return `/${escaped}/${typeof r.options === 'string' ? r.options : ''}`
+    const options = typeof r.options === 'string' ? r.options : ''
+    if (readsBackAsLiteral(r.pattern, options)) return `/${r.pattern}/${options}`
+    return `RegExp(${JSON.stringify(r.pattern)}, ${JSON.stringify(options)})`
   }
 
   if (keys.length === 1 && isPlainRecord(obj['$timestamp'])) {
@@ -202,6 +255,22 @@ function dateToIso(raw: unknown, tz: string): string | null {
   return null
 }
 
+// Mirrors the tokenizer's regex scan; "//" and "/*" would start a comment instead.
+function readsBackAsLiteral(pattern: string, options: string): boolean {
+  if (pattern === '' || pattern.startsWith('*') || !/^[gimsuy]*$/.test(options)) return false
+  if (/[/\n\r\u2028\u2029]/.test(pattern)) return false
+  let inClass = false
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]
+    if (ch === '\\') {
+      if (i === pattern.length - 1) return false
+      i++
+    } else if (ch === '[') inClass = true
+    else if (ch === ']') inClass = false
+  }
+  return !inClass
+}
+
 function renderBinary(bin: Record<string, unknown>, ctx: Ctx): string {
   const base64 = typeof bin['base64'] === 'string' ? bin['base64'] : ''
   const subTypeHex = typeof bin['subType'] === 'string' ? bin['subType'].toLowerCase() : '00'
diff --git a/src/renderer/src/lib/queryCancellation.test.ts b/src/renderer/src/lib/queryCancellation.test.ts
new file mode 100644
index 0000000..756ba4f
--- /dev/null
+++ b/src/renderer/src/lib/queryCancellation.test.ts
@@ -0,0 +1,128 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { cancelRequests, withRequestId } from './queryCancellation'
+
+const { cancel } = vi.hoisted(() => ({
+  cancel: vi.fn((_request: { requestId: string }) => Promise.resolve())
+}))
+vi.mock('./api', () => ({ api: { query: { cancel } } }))
+
+type Deferred<T> = { promise: Promise<T>; resolve: (v: T) => void; reject: (e: unknown) => void }
+function deferred<T>(): Deferred<T> {
+  let resolve!: (v: T) => void
+  let reject!: (e: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+const cancelledIds = () => cancel.mock.calls.map(([request]) => request.requestId)
+
+beforeEach(() => {
+  cancel.mockClear()
+  cancelRequests(() => true)
+  cancel.mockClear()
+})
+
+describe('withRequestId', () => {
+  it('passes a fresh v4 uuid per run and returns the result', async () => {
+    const ids: string[] = []
+    const a = await withRequestId(['find', 1], async (id) => {
+      ids.push(id)
+      return 'a'
+    })
+    const b = await withRequestId(['find', 1], async (id) => {
+      ids.push(id)
+      return 'b'
+    })
+    expect([a, b]).toEqual(['a', 'b'])
+    expect(ids[0]).toMatch(UUID)
+    expect(ids[1]).toMatch(UUID)
+    expect(ids[0]).not.toBe(ids[1])
+  })
+
+  it('keeps the id registered while running and forgets it once settled', async () => {
+    const run = deferred<string>()
+    let requestId = ''
+    const pending = withRequestId(['aggregate', 't1'], (id) => {
+      requestId = id
+      return run.promise
+    })
+    cancelRequests(() => true)
+    expect(cancelledIds()).toEqual([requestId])
+
+    run.resolve('done')
+    await pending
+    cancel.mockClear()
+    cancelRequests(() => true)
+    expect(cancel).not.toHaveBeenCalled()
+  })
+
+  it('forgets the id when the run fails', async () => {
+    await expect(
+      withRequestId(['find', 2], () => Promise.reject(new Error('boom')))
+    ).rejects.toThrow('boom')
+    cancelRequests(() => true)
+    expect(cancel).not.toHaveBeenCalled()
+  })
+
+  it('aborts the older server op when the same key runs again', async () => {
+    const first = deferred<string>()
+    const second = deferred<string>()
+    let firstId = ''
+    let secondId = ''
+    const a = withRequestId(['shell', 't1', { epoch: 3 }], (id) => {
+      firstId = id
+      return first.promise
+    })
+    const b = withRequestId(['shell', 't1', { epoch: 3 }], (id) => {
+      secondId = id
+      return second.promise
+    })
+    expect(cancelledIds()).toEqual([firstId])
+
+    // The superseded run settling later must not unregister the newer one.
+    first.resolve('old')
+    await a
+    cancel.mockClear()
+    cancelRequests(() => true)
+    expect(cancelledIds()).toEqual([secondId])
+    second.resolve('new')
+    await b
+  })
+})
+
+describe('cancelRequests', () => {
+  it('aborts only matching running queries, once', async () => {
+    const runs = [deferred<void>(), deferred<void>()]
+    const ids: string[] = []
+    const keys = [
+      ['aggregate', 't1', 'c', 'db', 'coll', { pipeline: '[]', epoch: 4 }],
+      ['aggregate', 't2', 'c', 'db', 'coll', { pipeline: '[]', epoch: 5 }]
+    ]
+    const pending = keys.map((key, i) =>
+      withRequestId(key, (id) => {
+        ids.push(id)
+        return runs[i]?.promise ?? Promise.resolve()
+      })
+    )
+    cancelRequests((key) => key[1] === 't2')
+    expect(cancelledIds()).toEqual([ids[1]])
+    cancelRequests((key) => key[1] === 't2')
+    expect(cancel).toHaveBeenCalledTimes(1)
+
+    for (const run of runs) run.resolve()
+    await Promise.all(pending)
+  })
+
+  it('swallows a failing cancel request', async () => {
+    cancel.mockImplementationOnce(() => Promise.reject(new Error('ipc down')))
+    const run = deferred<void>()
+    const pending = withRequestId(['find', 3], () => run.promise)
+    expect(() => cancelRequests(() => true)).not.toThrow()
+    run.resolve()
+    await pending
+  })
+})
diff --git a/src/renderer/src/lib/queryCancellation.ts b/src/renderer/src/lib/queryCancellation.ts
new file mode 100644
index 0000000..29b6329
--- /dev/null
+++ b/src/renderer/src/lib/queryCancellation.ts
@@ -0,0 +1,39 @@
+import { hashKey, type QueryKey } from '@tanstack/react-query'
+import { api } from './api'
+
+type RunningRequest = { requestId: string; queryKey: QueryKey }
+
+// React Query's own `signal` is not used: it aborts a query as soon as its last observer
+// unmounts, which happens on every tab switch.
+const running = new Map<string, RunningRequest>()
+
+function abortServerOp(requestId: string): void {
+  // The run may already have settled in main; an unknown id is a no-op there.
+  void api.query.cancel({ requestId }).catch(() => undefined)
+}
+
+/** Runs `fn` with a fresh request id; a newer run of the same key aborts the older server op. */
+export async function withRequestId<T>(
+  queryKey: QueryKey,
+  fn: (requestId: string) => Promise<T>
+): Promise<T> {
+  const hash = hashKey(queryKey)
+  const previous = running.get(hash)
+  if (previous) abortServerOp(previous.requestId)
+  const entry: RunningRequest = { requestId: crypto.randomUUID(), queryKey }
+  running.set(hash, entry)
+  try {
+    return await fn(entry.requestId)
+  } finally {
+    if (running.get(hash) === entry) running.delete(hash)
+  }
+}
+
+/** Aborts the server-side ops of running queries whose key matches. */
+export function cancelRequests(matches: (queryKey: QueryKey) => boolean): void {
+  for (const [hash, entry] of running) {
+    if (!matches(entry.queryKey)) continue
+    running.delete(hash)
+    abortServerOp(entry.requestId)
+  }
+}
diff --git a/src/renderer/src/lib/queryClient.test.ts b/src/renderer/src/lib/queryClient.test.ts
new file mode 100644
index 0000000..d975f2d
--- /dev/null
+++ b/src/renderer/src/lib/queryClient.test.ts
@@ -0,0 +1,776 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  hashKey,
+  MutationObserver,
+  onlineManager,
+  QueryClient,
+  QueryObserver,
+  type QueryKey
+} from '@tanstack/react-query'
+import type { CollectionRef, WriteResponse } from '@shared/types'
+import { useAppStore } from '@/store'
+import { useTabsStore } from '@/store/tabs'
+import { api, ApiError } from './api'
+import {
+  explicitRunOptions,
+  invalidateWrittenCollection,
+  mutationKeys,
+  queryClient,
+  queryKeys,
+  releaseConnection,
+  releaseTabResults,
+  removeNamespaceQueries,
+  runQueryOptions,
+  shellWriteOptions,
+  simpleRunOptions,
+  type ShellWriteVariables
+} from './queryClient'
+import { cancelRequests, withRequestId } from './queryCancellation'
+import type { ShellWriteCommand, ShellWriteResult } from './queryRun'
+
+const cancel = vi.spyOn(api.query, 'cancel').mockResolvedValue(undefined)
+const write = vi.spyOn(api.query, 'write')
+
+const WRITTEN: WriteResponse = { tookMs: 4, counts: { deleted: 3 }, ids: [], idsTruncated: false }
+
+/** Every key family scoped to `connectionId/db/coll`, as the app builds them. */
+function namespaceKeys(c: string, db: string, coll: string, tabId: string): QueryKey[] {
+  return [
+    queryKeys.databases(c),
+    queryKeys.collections(c, db),
+    queryKeys.users(c, db),
+    queryKeys.roles(c, db),
+    queryKeys.collectionStats(c, db, coll),
+    queryKeys.indexes(c, db, coll),
+    queryKeys.indexStats(c, db, coll),
+    queryKeys.collectionSchema(c, db, coll),
+    queryKeys.find(c, db, coll, '{}', '{}', '{}', 0, 100, 1),
+    queryKeys.count(c, db, coll, '{}', 1),
+    queryKeys.aggregate(tabId, c, db, coll, '[]', 2),
+    queryKeys.shell(tabId, c, db, `db.${coll}.find()`, 3)
+  ]
+}
+
+const UNSCOPED: QueryKey[] = [
+  queryKeys.connections,
+  queryKeys.serverStats('c1'),
+  queryKeys.cloudflaredVersion('c1')
+]
+
+function populated(): QueryClient {
+  const qc = new QueryClient()
+  const keys = [
+    ...namespaceKeys('c1', 'app', 'users', 't1'),
+    ...namespaceKeys('c1', 'app', 'orders', 't2'),
+    ...namespaceKeys('c1', 'audit', 'users', 't3'),
+    ...namespaceKeys('c2', 'app', 'users', 't4'),
+    ...UNSCOPED
+  ]
+  for (const key of keys) qc.setQueryData(key, 'cached')
+  return qc
+}
+
+const cachedKeys = (qc: QueryClient): string[] =>
+  qc
+    .getQueryCache()
+    .getAll()
+    .map((q) => q.queryHash)
+    .sort()
+const hashes = (keys: QueryKey[]): string[] => [...new Set(keys.map(hashKey))].sort()
+
+const settle = async (): Promise<void> => {
+  for (let i = 0; i < 10; i++) await Promise.resolve()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+/** One persistent observer whose key follows mode and tab switches, as in CollectionTab. */
+function resultView(qc: QueryClient, initial: QueryKey) {
+  const runs = new Map<string, number>()
+  // `['idle', tabId]` shows no run, like a mode that never ran.
+  const options = (queryKey: QueryKey) =>
+    runQueryOptions(
+      String(queryKey[1]),
+      queryKey[0] === 'idle'
+        ? null
+        : {
+            key: queryKey,
+            execute: async () => {
+              runs.set(hashKey(queryKey), (runs.get(hashKey(queryKey)) ?? 0) + 1)
+              return 'rows'
+            }
+          },
+      explicitRunOptions
+    )
+  const observer = new QueryObserver(qc, options(initial))
+  const unsubscribe = observer.subscribe(() => undefined)
+  return {
+    show: (queryKey: QueryKey) => observer.setOptions(options(queryKey)),
+    runs: (queryKey: QueryKey) => runs.get(hashKey(queryKey)) ?? 0,
+    unsubscribe
+  }
+}
+
+/** Starts a server op that stays open until released; its request id is known at once. */
+function runningOp(queryKey: QueryKey): { requestId: string; release: () => Promise<void> } {
+  let requestId = ''
+  let finish!: () => void
+  const done = withRequestId(queryKey, (id) => {
+    requestId = id
+    return new Promise<void>((resolve) => (finish = resolve))
+  })
+  return {
+    requestId,
+    release: () => {
+      finish()
+      return done
+    }
+  }
+}
+
+const tabOf = (id: string) => {
+  const found = useTabsStore.getState().tabs.find((t) => t.id === id)
+  if (!found) throw new Error(`no tab ${id}`)
+  return found
+}
+const activeId = (): string => useTabsStore.getState().activeTabId ?? ''
+
+/** Find (current page) and count keys of the tab's applied simple run. */
+function simpleKeys(id: string): [QueryKey, QueryKey] {
+  const { connectionId, db, coll, applied } = tabOf(id)
+  const s = applied.simple
+  return [
+    queryKeys.find(
+      connectionId,
+      db,
+      coll,
+      s.filter,
+      s.projection,
+      s.sort,
+      s.skip,
+      s.limit,
+      s.epoch
+    ),
+    queryKeys.count(connectionId, db, coll, s.filter, s.epoch)
+  ]
+}
+
+function aggregateKey(id: string): QueryKey {
+  const { connectionId, db, coll, applied } = tabOf(id)
+  if (!applied.aggregation) throw new Error(`no aggregation run in ${id}`)
+  const { source, epoch } = applied.aggregation
+  return queryKeys.aggregate(id, connectionId, db, coll, source, epoch)
+}
+
+function shellKey(id: string): QueryKey {
+  const { connectionId, db, applied } = tabOf(id)
+  if (!applied.shell) throw new Error(`no shell run in ${id}`)
+  return queryKeys.shell(id, connectionId, db, applied.shell.source, applied.shell.epoch)
+}
+
+const deleteAll = (coll: string): ShellWriteCommand => ({
+  coll,
+  op: { kind: 'write', write: { method: 'deleteMany', filter: '{}' }, writes: { db: null, coll } }
+})
+
+/** Commits the tab's shell draft and runs it as a write under that run's epoch, as Run does. */
+function runWrite(
+  writer: MutationObserver<ShellWriteResult, Error, ShellWriteVariables>,
+  tabId: string,
+  command: ShellWriteCommand = deleteAll(tabOf(tabId).coll)
+): Promise<unknown> {
+  useTabsStore.getState().run(tabId)
+  const { connectionId, db, applied } = tabOf(tabId)
+  if (!applied.shell) throw new Error(`no shell run in ${tabId}`)
+  return writer.mutate({ tabId, epoch: applied.shell.epoch, target: { connectionId, db }, command })
+}
+
+const writeRuns = (): ShellWriteVariables[] =>
+  queryClient
+    .getMutationCache()
+    .findAll({ mutationKey: mutationKeys.shellWrite })
+    .map((m) => m.state.variables as ShellWriteVariables)
+
+beforeEach(() => {
+  // Epochs restart with the store, so a request left running would collide with the next test's.
+  cancelRequests(() => true)
+  cancel.mockClear()
+  write.mockReset().mockResolvedValue(WRITTEN)
+  queryClient.clear()
+  useTabsStore.setState(useTabsStore.getInitialState(), true)
+})
+
+describe('removeNamespaceQueries', () => {
+  it('collection scope removes that collection, keeping database-wide families and other namespaces', () => {
+    const qc = populated()
+    const before = cachedKeys(qc)
+    removeNamespaceQueries(qc, 'c1', 'app', 'users')
+    const after = new Set(cachedKeys(qc))
+    expect(before.filter((h) => !after.has(h))).toEqual(
+      hashes([
+        queryKeys.collectionStats('c1', 'app', 'users'),
+        queryKeys.indexes('c1', 'app', 'users'),
+        queryKeys.indexStats('c1', 'app', 'users'),
+        queryKeys.collectionSchema('c1', 'app', 'users'),
+        queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1),
+        queryKeys.count('c1', 'app', 'users', '{}', 1),
+        queryKeys.aggregate('t1', 'c1', 'app', 'users', '[]', 2)
+      ])
+    )
+  })
+
+  it('database scope removes everything of the database, including lists, users and shell results', () => {
+    const qc = populated()
+    removeNamespaceQueries(qc, 'c1', 'app')
+    expect(cachedKeys(qc)).toEqual(
+      hashes([
+        ...namespaceKeys('c1', 'audit', 'users', 't3'),
+        ...namespaceKeys('c2', 'app', 'users', 't4'),
+        ...UNSCOPED
+      ])
+    )
+  })
+
+  it('connection scope removes everything of that connection and nothing else', () => {
+    const qc = populated()
+    removeNamespaceQueries(qc, 'c1')
+    expect(cachedKeys(qc)).toEqual(
+      hashes([...namespaceKeys('c2', 'app', 'users', 't4'), ...UNSCOPED])
+    )
+  })
+})
+
+describe('invalidateWrittenCollection', () => {
+  const users: CollectionRef = { connectionId: 'c1', db: 'app', coll: 'users' }
+
+  it("marks the collection's find, count and stats and its database's collection list stale, nothing else", async () => {
+    const qc = populated()
+    await invalidateWrittenCollection(qc, users)
+    const invalidated = qc
+      .getQueryCache()
+      .getAll()
+      .filter((q) => q.state.isInvalidated)
+      .map((q) => q.queryHash)
+      .sort()
+    expect(invalidated).toEqual(
+      hashes([
+        queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1),
+        queryKeys.count('c1', 'app', 'users', '{}', 1),
+        queryKeys.collections('c1', 'app'),
+        queryKeys.collectionStats('c1', 'app', 'users')
+      ])
+    )
+  })
+
+  it('re-runs the shown aggregation and shell results that may read the collection', async () => {
+    const qc = new QueryClient()
+    const pipeline = queryKeys.aggregate('t1', 'c1', 'app', 'users', '[]', 2)
+    // Shell keys name only the database: any command there may read the collection.
+    const command = queryKeys.shell('t2', 'c1', 'app', 'db.orders.find()', 3)
+    const otherCollection = queryKeys.aggregate('t3', 'c1', 'app', 'orders', '[]', 4)
+    const views = [pipeline, command, otherCollection].map((key) => resultView(qc, key))
+    await settle()
+    await invalidateWrittenCollection(qc, users)
+    expect(views.map((view, i) => view.runs([pipeline, command, otherCollection][i]!))).toEqual([
+      2, 2, 1
+    ])
+    views.forEach((view) => view.unsubscribe())
+  })
+
+  it('never re-runs a hidden aggregation when a mode switch shows it again', async () => {
+    const qc = new QueryClient()
+    const pipeline = queryKeys.aggregate('t1', 'c1', 'app', 'users', '[]', 2)
+    const view = resultView(qc, pipeline)
+    await settle()
+    view.show(['idle', 't1'])
+    await invalidateWrittenCollection(qc, users)
+    view.show(pipeline)
+    await settle()
+    expect(view.runs(pipeline)).toBe(1)
+    expect(qc.getQueryData(pipeline)).toBe('rows')
+    view.unsubscribe()
+  })
+
+  it('never re-runs a hidden shell result when a tab switch shows it again', async () => {
+    const qc = new QueryClient()
+    const command = queryKeys.shell('t1', 'c1', 'app', 'db.big.find()', 2)
+    const view = resultView(qc, command)
+    await settle()
+    view.show(['idle', 't2'])
+    await invalidateWrittenCollection(qc, { ...users, coll: 'small' })
+    view.show(command)
+    await settle()
+    expect(view.runs(command)).toBe(1)
+    view.unsubscribe()
+  })
+})
+
+describe('runQueryOptions', () => {
+  const key = queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1)
+  const noRetry = () => new QueryClient({ defaultOptions: { queries: { retry: false } } })
+
+  it("observes the tab's idle placeholder without a run", async () => {
+    const qc = noRetry()
+    const observer = new QueryObserver(qc, runQueryOptions('t1', null, simpleRunOptions))
+    const unsubscribe = observer.subscribe(() => undefined)
+    await settle()
+    expect(
+      qc
+        .getQueryCache()
+        .getAll()
+        .map((q) => q.queryKey)
+    ).toEqual([['idle', 't1']])
+    expect(observer.getCurrentResult()).toMatchObject({ fetchStatus: 'idle', data: undefined })
+    unsubscribe()
+  })
+
+  it('never executes a failed run again when it is shown again', async () => {
+    const qc = noRetry()
+    const execute = vi.fn().mockRejectedValue(new Error('$where is not allowed'))
+    const shown = runQueryOptions('t1', { key, execute }, simpleRunOptions)
+    const observer = new QueryObserver(qc, shown)
+    const unsubscribe = observer.subscribe(() => undefined)
+    await settle()
+    observer.setOptions(runQueryOptions('t1', null, simpleRunOptions))
+    observer.setOptions(shown)
+    await settle()
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(observer.getCurrentResult().error?.message).toBe('$where is not allowed')
+    unsubscribe()
+  })
+
+  it('executes a hidden run only once it is shown', async () => {
+    const qc = noRetry()
+    const execute = vi.fn().mockResolvedValue('rows')
+    const observer = new QueryObserver(
+      qc,
+      runQueryOptions('t1', { key, execute }, simpleRunOptions, false)
+    )
+    const unsubscribe = observer.subscribe(() => undefined)
+    await settle()
+    expect(execute).not.toHaveBeenCalled()
+    observer.setOptions(runQueryOptions('t1', { key, execute }, simpleRunOptions))
+    await settle()
+    expect(execute).toHaveBeenCalledTimes(1)
+    expect(observer.getCurrentResult().data).toBe('rows')
+    unsubscribe()
+  })
+})
+
+describe('releaseConnection', () => {
+  it('marks the connection disconnected, closes its tabs and drops its queries', () => {
+    useAppStore.setState(useAppStore.getInitialState(), true)
+    for (const id of ['c1', 'c2']) {
+      useAppStore.getState().markConnected(id)
+      useTabsStore.getState().openNew({ connectionId: id, db: 'app', coll: 'users' })
+      queryClient.setQueryData(queryKeys.databases(id), 'cached')
+    }
+    releaseConnection(queryClient, 'c1')
+    expect([...useAppStore.getState().activeConnectionIds]).toEqual(['c2'])
+    expect(useTabsStore.getState().tabs.map((t) => t.connectionId)).toEqual(['c2'])
+    expect(queryClient.getQueryData(queryKeys.databases('c1'))).toBeUndefined()
+    expect(queryClient.getQueryData(queryKeys.databases('c2'))).toBe('cached')
+  })
+})
+
+describe('retry', () => {
+  const retry = queryClient.getDefaultOptions().queries?.retry as (
+    failureCount: number,
+    error: Error
+  ) => boolean
+
+  it('does not repeat a server error; the driver already retried what can succeed', () => {
+    const error = new ApiError({ code: 'driver_error', message: '$where is not allowed' })
+    expect(retry(0, error)).toBe(false)
+  })
+
+  it('repeats a network failure once', () => {
+    const error = new ApiError({ code: 'network_error', message: 'connection reset' })
+    expect(retry(0, error)).toBe(true)
+    expect(retry(1, error)).toBe(false)
+  })
+})
+
+describe('while the OS reports no network', () => {
+  afterEach(() => onlineManager.setOnline(true))
+
+  it('runs queries, which reach main over IPC', async () => {
+    onlineManager.setOnline(false)
+    const observer = new QueryObserver(queryClient, {
+      queryKey: queryKeys.connections,
+      queryFn: async () => 'rows'
+    })
+    const unsubscribe = observer.subscribe(() => undefined)
+    await settle()
+    expect(observer.getCurrentResult()).toMatchObject({ status: 'success', data: 'rows' })
+    unsubscribe()
+  })
+
+  it('runs a shell write when Run is pressed and not again once the network returns', async () => {
+    onlineManager.setOnline(false)
+    const writer = new MutationObserver(queryClient, shellWriteOptions(queryClient))
+    const running = writer.mutate({
+      tabId: 't1',
+      epoch: 1,
+      target: { connectionId: 'c1', db: 'app' },
+      command: deleteAll('users')
+    })
+    await settle()
+    expect(write).toHaveBeenCalledTimes(1)
+    await running
+    onlineManager.setOnline(true)
+    await settle()
+    expect(write).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('releaseTabResults', () => {
+  it("drops the tab's aggregation and shell results only", () => {
+    const own = [
+      queryKeys.aggregate('t1', 'c1', 'app', 'users', '[]', 2),
+      queryKeys.shell('t1', 'c1', 'app', 'db.users.find()', 3)
+    ]
+    const kept = [
+      queryKeys.aggregate('t11', 'c1', 'app', 'users', '[]', 4),
+      queryKeys.shell('t2', 'c1', 'app', 'db.users.find()', 5),
+      queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1)
+    ]
+    for (const key of [...own, ...kept]) queryClient.setQueryData(key, 'cached')
+    releaseTabResults('t1')
+    for (const key of own) expect(queryClient.getQueryData(key)).toBeUndefined()
+    for (const key of kept) expect(queryClient.getQueryData(key)).toBe('cached')
+  })
+
+  it("aborts the tab's running server ops", async () => {
+    let resolveOwn!: () => void
+    let resolveOther!: () => void
+    let ownId = ''
+    const own = withRequestId(queryKeys.aggregate('t1', 'c1', 'app', 'users', '[]', 2), (id) => {
+      ownId = id
+      return new Promise<void>((resolve) => (resolveOwn = resolve))
+    })
+    const other = withRequestId(
+      queryKeys.aggregate('t2', 'c1', 'app', 'users', '[]', 3),
+      () => new Promise<void>((resolve) => (resolveOther = resolve))
+    )
+    releaseTabResults('t1')
+    expect(cancel.mock.calls).toEqual([[{ requestId: ownId }]])
+    resolveOwn()
+    resolveOther()
+    await Promise.all([own, other])
+  })
+})
+
+describe('closing tabs', () => {
+  const users = { connectionId: 'c1', db: 'app', coll: 'users' }
+
+  it('releases the results of every tab that closes, whichever action closed it', () => {
+    const tabs = useTabsStore.getState()
+    tabs.openNew(users)
+    const a = useTabsStore.getState().activeTabId ?? ''
+    tabs.openNew(users)
+    const b = useTabsStore.getState().activeTabId ?? ''
+    tabs.openNew({ ...users, connectionId: 'c2' })
+    const c = useTabsStore.getState().activeTabId ?? ''
+    const keyOf = (tabId: string) => queryKeys.shell(tabId, 'c1', 'app', 'db.users.find()', 1)
+    for (const id of [a, b, c]) queryClient.setQueryData(keyOf(id), 'cached')
+
+    useTabsStore.getState().close(a)
+    expect(queryClient.getQueryData(keyOf(a))).toBeUndefined()
+    expect(queryClient.getQueryData(keyOf(b))).toBe('cached')
+
+    useTabsStore.getState().closeForConnection('c1')
+    expect(queryClient.getQueryData(keyOf(b))).toBeUndefined()
+    expect(queryClient.getQueryData(keyOf(c))).toBe('cached')
+  })
+
+  it('keeps the shown runs while tabs are paged, opened or activated', () => {
+    const tabs = useTabsStore.getState()
+    tabs.openNew(users)
+    const a = activeId()
+    tabs.setDraft(a, { mode: 'aggregation', pipeline: '[]' })
+    tabs.run(a)
+    tabs.setDraft(a, { mode: 'shell', shell: 'db.users.find()' })
+    tabs.run(a)
+    const keys = [...simpleKeys(a), aggregateKey(a), shellKey(a)]
+    for (const key of keys) queryClient.setQueryData(key, 'cached')
+    tabs.setSkip(a, 100)
+    tabs.openNew(users)
+    tabs.activate(a)
+    for (const key of keys) expect(queryClient.getQueryData(key)).toBe('cached')
+    expect(cancel).not.toHaveBeenCalled()
+  })
+
+  it("drops a closed tab's find and count and aborts their running server ops", async () => {
+    useTabsStore.getState().openNew(users)
+    const a = activeId()
+    const [find, count] = simpleKeys(a)
+    queryClient.setQueryData(find, 'cached')
+    const op = runningOp(count)
+    useTabsStore.getState().close(a)
+    expect(queryClient.getQueryData(find)).toBeUndefined()
+    expect(cancel.mock.calls).toEqual([[{ requestId: op.requestId }]])
+    await op.release()
+  })
+
+  it('keeps find and count while a duplicate still shows the same run', async () => {
+    useTabsStore.getState().openNew(users)
+    const a = activeId()
+    useTabsStore.getState().duplicate(a)
+    const b = activeId()
+    const [find, count] = simpleKeys(a)
+    queryClient.setQueryData(find, 'cached')
+    const op = runningOp(count)
+    useTabsStore.getState().close(a)
+    expect(queryClient.getQueryData(find)).toBe('cached')
+    expect(cancel).not.toHaveBeenCalled()
+    useTabsStore.getState().close(b)
+    expect(queryClient.getQueryData(find)).toBeUndefined()
+    expect(cancel.mock.calls).toEqual([[{ requestId: op.requestId }]])
+    await op.release()
+  })
+})
+
+describe('replacing a run', () => {
+  const users = { connectionId: 'c1', db: 'app', coll: 'users' }
+
+  it('Run drops every page and the count of the replaced simple run and aborts them', async () => {
+    useTabsStore.getState().openNew(users)
+    const a = activeId()
+    const [firstPage, count] = simpleKeys(a)
+    useTabsStore.getState().setSkip(a, 100)
+    const [secondPage] = simpleKeys(a)
+    queryClient.setQueryData(firstPage, 'cached')
+    queryClient.setQueryData(count, 'cached')
+    const op = runningOp(secondPage)
+    useTabsStore.getState().run(a)
+    for (const key of [firstPage, secondPage, count]) {
+      expect(queryClient.getQueryData(key)).toBeUndefined()
+    }
+    expect(cancel.mock.calls).toEqual([[{ requestId: op.requestId }]])
+    await op.release()
+  })
+
+  it('a repeated lookup drops the run its tab showed before', () => {
+    const lookup = '{ _id: 1 }'
+    useTabsStore.getState().openWithFilter(users, lookup)
+    const a = activeId()
+    const [find] = simpleKeys(a)
+    queryClient.setQueryData(find, 'cached')
+    useTabsStore.getState().openNew({ ...users, coll: 'orders' })
+    useTabsStore.getState().openWithFilter(users, lookup)
+    expect(activeId()).toBe(a)
+    expect(queryClient.getQueryData(find)).toBeUndefined()
+  })
+
+  it.each([
+    ['aggregation', { pipeline: '[]' }, aggregateKey],
+    ['shell', { shell: 'db.users.find()' }, shellKey]
+  ] as const)(
+    "Run drops the tab's superseded %s run and aborts it, keeping other tabs' runs",
+    async (mode, draft, keyOf) => {
+      useTabsStore.getState().openNew(users)
+      const other = activeId()
+      useTabsStore.getState().setDraft(other, { mode, ...draft })
+      useTabsStore.getState().run(other)
+      queryClient.setQueryData(keyOf(other), 'cached')
+      useTabsStore.getState().openNew(users)
+      const a = activeId()
+      useTabsStore.getState().setDraft(a, { mode, ...draft })
+      useTabsStore.getState().run(a)
+      const superseded = keyOf(a)
+      const op = runningOp(superseded)
+      useTabsStore.getState().run(a)
+      queryClient.setQueryData(keyOf(a), 'cached')
+      expect(queryClient.getQueryData(superseded)).toBeUndefined()
+      expect(queryClient.getQueryData(keyOf(a))).toBe('cached')
+      expect(queryClient.getQueryData(keyOf(other))).toBe('cached')
+      expect(cancel.mock.calls).toEqual([[{ requestId: op.requestId }]])
+      await op.release()
+    }
+  )
+
+  it("rename drops the tab's aggregation run and keeps its shell run", () => {
+    useTabsStore.getState().openNew(users)
+    const a = activeId()
+    useTabsStore.getState().setDraft(a, { mode: 'aggregation', pipeline: '[]' })
+    useTabsStore.getState().run(a)
+    useTabsStore.getState().setDraft(a, { mode: 'shell', shell: 'db.users.find()' })
+    useTabsStore.getState().run(a)
+    const pipeline = aggregateKey(a)
+    const command = shellKey(a)
+    queryClient.setQueryData(pipeline, 'cached')
+    queryClient.setQueryData(command, 'cached')
+    useTabsStore.getState().renameCollection('c1', 'app', 'users', 'members')
+    expect(queryClient.getQueryData(pipeline)).toBeUndefined()
+    expect(queryClient.getQueryData(command)).toBe('cached')
+  })
+})
+
+describe('shell writes', () => {
+  const users = { connectionId: 'c1', db: 'app', coll: 'users' }
+  const writer = () => new MutationObserver(queryClient, shellWriteOptions(queryClient))
+
+  function openShellTab(ref = users): string {
+    useTabsStore.getState().openNew(ref)
+    const id = activeId()
+    useTabsStore.getState().setDraft(id, { mode: 'shell', shell: `db.${ref.coll}.deleteMany({})` })
+    return id
+  }
+
+  const invalidated = (): string[] =>
+    queryClient
+      .getQueryCache()
+      .getAll()
+      .filter((q) => q.state.isInvalidated)
+      .map((q) => q.queryHash)
+      .sort()
+
+  it('never runs a write again: not on invalidation, refetches, tab or mode switches', async () => {
+    const a = openShellTab()
+    await runWrite(writer(), a)
+    const [find] = simpleKeys(a)
+    // A shown write observes no query of its own, as in CollectionTab.
+    const view = resultView(queryClient, ['idle', a])
+    await settle()
+
+    await invalidateWrittenCollection(queryClient, users)
+    await queryClient.invalidateQueries()
+    await queryClient.refetchQueries()
+    view.show(find)
+    await settle()
+    view.show(['idle', a])
+    useTabsStore.getState().openNew(users)
+    const b = activeId()
+    useTabsStore.getState().setDraft(b, { mode: 'shell', shell: 'db.users.find()' })
+    useTabsStore.getState().run(b)
+    view.show(shellKey(b))
+    await settle()
+    useTabsStore.getState().activate(a)
+    view.show(['idle', a])
+    await invalidateWrittenCollection(queryClient, users)
+    await settle()
+
+    expect(write).toHaveBeenCalledTimes(1)
+    const [shown] = queryClient.getMutationCache().findAll({ mutationKey: mutationKeys.shellWrite })
+    expect(shown?.state).toMatchObject({ status: 'success', variables: { tabId: a } })
+    view.unsubscribe()
+  })
+
+  it('sends the command to its collection of the tab database', async () => {
+    const a = openShellTab()
+    await runWrite(writer(), a, deleteAll('orders'))
+    expect(write.mock.calls).toEqual([
+      [
+        {
+          connectionId: 'c1',
+          db: 'app',
+          coll: 'orders',
+          op: { method: 'deleteMany', filter: '{}' }
+        }
+      ]
+    ])
+  })
+
+  it('refreshes the written collection, its stats and the database collection list', async () => {
+    const touched = [
+      queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1),
+      queryKeys.count('c1', 'app', 'users', '{}', 1),
+      queryKeys.collections('c1', 'app'),
+      queryKeys.collectionStats('c1', 'app', 'users')
+    ]
+    const untouched = [
+      queryKeys.find('c1', 'app', 'orders', '{}', '{}', '{}', 0, 100, 1),
+      queryKeys.collections('c1', 'audit'),
+      queryKeys.collectionStats('c1', 'app', 'orders'),
+      queryKeys.indexes('c1', 'app', 'users')
+    ]
+    for (const key of [...touched, ...untouched]) queryClient.setQueryData(key, 'cached')
+    await runWrite(writer(), openShellTab())
+    expect(invalidated()).toEqual(hashes(touched))
+  })
+
+  it('refreshes after a failed write too, since part of it may have been written', async () => {
+    write.mockRejectedValue(new ApiError({ code: 'driver_error', message: 'E11000 duplicate key' }))
+    const keys = [
+      queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1),
+      queryKeys.collections('c1', 'app'),
+      queryKeys.collectionStats('c1', 'app', 'users')
+    ]
+    for (const key of keys) queryClient.setQueryData(key, 'cached')
+    await expect(runWrite(writer(), openShellTab())).rejects.toThrow('E11000')
+    expect(write).toHaveBeenCalledTimes(1)
+    expect(invalidated()).toEqual(hashes(keys))
+  })
+
+  it('refreshes the $out target in another database, not the source collection', async () => {
+    const source = queryKeys.find('c1', 'app', 'users', '{}', '{}', '{}', 0, 100, 1)
+    const target = [
+      queryKeys.find('c1', 'archive', 'old', '{}', '{}', '{}', 0, 100, 1),
+      queryKeys.collections('c1', 'archive'),
+      queryKeys.collectionStats('c1', 'archive', 'old')
+    ]
+    for (const key of [source, ...target]) queryClient.setQueryData(key, 'cached')
+    const out: ShellWriteCommand = {
+      coll: 'users',
+      op: {
+        kind: 'write',
+        write: { method: 'aggregate', pipeline: '[{"$out":{"db":"archive","coll":"old"}}]' },
+        writes: { db: 'archive', coll: 'old' }
+      }
+    }
+    await runWrite(writer(), openShellTab(), out)
+    expect(invalidated()).toEqual(hashes(target))
+  })
+
+  it("drops a closed tab's write, also while it still runs, and keeps other tabs' writes", async () => {
+    const other = openShellTab()
+    await runWrite(writer(), other)
+    let finish!: (response: WriteResponse) => void
+    write.mockImplementation(() => new Promise((resolve) => (finish = resolve)))
+    const a = openShellTab()
+    const running = runWrite(writer(), a)
+    await settle()
+    expect(write).toHaveBeenCalledTimes(2)
+    expect(writeRuns().map((run) => run.tabId)).toEqual([other, a])
+
+    useTabsStore.getState().close(a)
+    expect(writeRuns().map((run) => run.tabId)).toEqual([other])
+    finish(WRITTEN)
+    await running
+    expect(writeRuns().map((run) => run.tabId)).toEqual([other])
+  })
+
+  it("a newer shell run of the tab drops the tab's write", async () => {
+    const a = openShellTab()
+    await runWrite(writer(), a)
+    useTabsStore.getState().setDraft(a, { shell: 'db.users.find()' })
+    useTabsStore.getState().run(a)
+    expect(writeRuns()).toEqual([])
+  })
+
+  it('keeps only the latest write when the tab runs writes back to back', async () => {
+    const a = openShellTab()
+    await runWrite(writer(), a)
+    await runWrite(writer(), a)
+    expect(write).toHaveBeenCalledTimes(2)
+    expect(writeRuns().map((run) => run.epoch)).toEqual([tabOf(a).applied.shell?.epoch])
+  })
+
+  it('keeps the write while tabs are activated, paged, renamed or another mode runs', async () => {
+    const a = openShellTab()
+    await runWrite(writer(), a)
+    const before = writeRuns()
+    const tabs = useTabsStore.getState()
+    tabs.setSkip(a, 100)
+    tabs.setDraft(a, { mode: 'simple', filter: '{ a: 1 }' })
+    tabs.run(a)
+    tabs.setDraft(a, { mode: 'aggregation', pipeline: '[]' })
+    tabs.run(a)
+    tabs.openNew(users)
+    tabs.duplicate(a)
+    tabs.activate(a)
+    tabs.renameCollection('c1', 'app', 'users', 'members')
+    expect(writeRuns()).toEqual(before)
+    expect(write).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/src/renderer/src/lib/queryClient.ts b/src/renderer/src/lib/queryClient.ts
index 7bc6cb1..b2517c0 100644
--- a/src/renderer/src/lib/queryClient.ts
+++ b/src/renderer/src/lib/queryClient.ts
@@ -1,15 +1,39 @@
-import { QueryClient } from '@tanstack/react-query'
+import {
+  QueryClient,
+  skipToken,
+  type MutationOptions,
+  type QueryKey,
+  type UseQueryOptions
+} from '@tanstack/react-query'
 import type { ErrorCode } from '@shared/result'
+import type { CollectionRef, DatabaseRef } from '@shared/types'
+import { useAppStore } from '@/store'
+import { useTabsStore, type AppliedSource, type QueryMode } from '@/store/tabs'
 import { ApiError } from './api'
+import { cancelRequests, withRequestId } from './queryCancellation'
+import {
+  runShellWrite,
+  writtenCollection,
+  type ShellWriteCommand,
+  type ShellWriteResult
+} from './queryRun'
 
 /** Retrying these cannot change the answer — the input has to change first. */
 const NEVER_RETRIED = new Set<ErrorCode>([
   'validation_error',
   'auth_failed',
   'ssh_auth_failed',
-  'ssh_host_key_mismatch'
+  'ssh_host_key_mismatch',
+  'cloudflared_not_found',
+  'cloudflared_auth_failed',
+  'cancelled',
+  // The driver itself retries the server errors that a repeat can fix.
+  'driver_error'
 ])
 
+// Requests reach main over IPC, so the OS reporting no network must not pause them.
+const networkMode = 'always'
+
 export const queryClient = new QueryClient({
   defaultOptions: {
     queries: {
@@ -18,10 +42,12 @@ export const queryClient = new QueryClient({
         return failureCount < 1
       },
       staleTime: 30_000,
-      refetchOnWindowFocus: false
+      refetchOnWindowFocus: false,
+      networkMode
     },
     mutations: {
-      retry: false
+      retry: false,
+      networkMode
     }
   }
 })
@@ -34,9 +60,14 @@ export const queryKeys = {
     ['collection-stats', connectionId, db, coll] as const,
   indexes: (connectionId: string, db: string, coll: string) =>
     ['indexes', connectionId, db, coll] as const,
-  fieldPaths: (connectionId: string, db: string, coll: string) =>
-    ['field-paths', connectionId, db, coll] as const,
+  // Nested under indexes() so every invalidation of the list also refreshes the stats.
+  indexStats: (connectionId: string, db: string, coll: string) =>
+    ['indexes', connectionId, db, coll, 'stats'] as const,
+  collectionSchema: (connectionId: string, db: string, coll: string) =>
+    ['collection-schema', connectionId, db, coll] as const,
   users: (connectionId: string, db: string) => ['users', connectionId, db] as const,
+  roles: (connectionId: string, db: string) => ['roles', connectionId, db] as const,
+  cloudflaredVersion: (binaryPath: string) => ['cloudflared-version', binaryPath] as const,
   serverStats: (connectionId: string) => ['server-stats', connectionId] as const,
   find: (
     connectionId: string,
@@ -49,10 +80,252 @@ export const queryKeys = {
     limit: number,
     epoch: number
   ) => ['find', connectionId, db, coll, { filter, projection, sort, skip, limit, epoch }] as const,
-  aggregate: (connectionId: string, db: string, coll: string, pipeline: string, epoch: number) =>
-    ['aggregate', connectionId, db, coll, { pipeline, epoch }] as const,
-  shell: (connectionId: string, db: string, coll: string, command: string, epoch: number) =>
-    ['shell', connectionId, db, coll, { command, epoch }] as const,
-  count: (connectionId: string, db: string, coll: string, filter: string) =>
-    ['count', connectionId, db, coll, { filter }] as const
+  // Aggregation and shell results belong to one tab, so closing it can drop them.
+  aggregate: (
+    tabId: string,
+    connectionId: string,
+    db: string,
+    coll: string,
+    pipeline: string,
+    epoch: number
+  ) => ['aggregate', tabId, connectionId, db, coll, { pipeline, epoch }] as const,
+  shell: (tabId: string, connectionId: string, db: string, command: string, epoch: number) =>
+    ['shell', tabId, connectionId, db, { command, epoch }] as const,
+  count: (connectionId: string, db: string, coll: string, filter: string, epoch: number) =>
+    ['count', connectionId, db, coll, { filter, epoch }] as const
+}
+
+export const mutationKeys = {
+  shellWrite: ['shell-write'] as const
+}
+
+/** One shell write: what it executes, and the tab and applied shell run (epoch) it belongs to. */
+export type ShellWriteVariables = {
+  tabId: string
+  epoch: number
+  target: DatabaseRef
+  command: ShellWriteCommand
+}
+
+/** Simple find / count: re-run only by Run, paging or a write; released with their epoch. */
+export const simpleRunOptions = {
+  refetchOnMount: false,
+  staleTime: Infinity,
+  gcTime: Infinity
+} as const
+
+/** Explicitly run results: kept until replaced or closed, re-run only by Run or a write. */
+export const explicitRunOptions = {
+  gcTime: Infinity,
+  staleTime: Infinity,
+  retry: false,
+  retryOnMount: false,
+  refetchOnMount: false,
+  refetchOnReconnect: false
+} as const
+
+/** A run's result key and its execution under a request id that `query.cancel` can abort. */
+export type RunnableQuery<T> = { key: QueryKey; execute: (requestId: string) => Promise<T> }
+
+/**
+ * Options of a tab's result query for `run`; without one it observes an idle placeholder.
+ * @param executes false keeps a hidden mode's result observed without ever executing it
+ */
+export function runQueryOptions<T>(
+  tabId: string,
+  run: RunnableQuery<T> | null,
+  policy: typeof simpleRunOptions | typeof explicitRunOptions,
+  executes = true
+): UseQueryOptions<T, Error, T, QueryKey> {
+  if (run === null) return { queryKey: ['idle', tabId], queryFn: skipToken }
+  return {
+    queryKey: run.key,
+    queryFn: () => withRequestId(run.key, run.execute),
+    // A result without data counts as stale, so showing a failed or cancelled run's key again (tab or
+    // mode switch) would re-execute it; it stays failed until Run creates a new key.
+    enabled: (query) => executes && query.state.status !== 'error',
+    ...policy
+  }
+}
+
+type KeyFamily = {
+  /** Index of the connectionId; db and coll follow for `depth` levels. */
+  at: number
+  depth: number
+  /** Mode whose runs fill it: Simple results are shared by epoch, the others belong to one tab. */
+  run?: QueryMode
+}
+
+// Shell keys stop at the database: a command may read any of its collections. Aggregation and
+// shell keys hold their tab id right before the connectionId.
+const KEY_FAMILIES = new Map<string, KeyFamily>([
+  ['databases', { at: 1, depth: 1 }],
+  ['collections', { at: 1, depth: 2 }],
+  ['users', { at: 1, depth: 2 }],
+  ['roles', { at: 1, depth: 2 }],
+  ['collection-stats', { at: 1, depth: 3 }],
+  ['indexes', { at: 1, depth: 3 }],
+  ['collection-schema', { at: 1, depth: 3 }],
+  ['find', { at: 1, depth: 3, run: 'simple' }],
+  ['count', { at: 1, depth: 3, run: 'simple' }],
+  ['aggregate', { at: 2, depth: 3, run: 'aggregation' }],
+  ['shell', { at: 2, depth: 2, run: 'shell' }]
+])
+
+function familyOf(key: QueryKey): KeyFamily | undefined {
+  const name = key[0]
+  return typeof name === 'string' ? KEY_FAMILIES.get(name) : undefined
+}
+
+const keyWithin = (key: QueryKey, at: number, scope: readonly string[]): boolean =>
+  scope.every((part, i) => key[at + i] === part)
+
+const isTabRun = (run: QueryMode | undefined): boolean => run === 'aggregation' || run === 'shell'
+
+function tabOf(key: QueryKey): unknown {
+  const family = familyOf(key)
+  return family && isTabRun(family.run) ? key[family.at - 1] : undefined
+}
+
+// Every run key ends with its options object, which carries the epoch.
+const epochOf = (key: QueryKey): unknown => (key[key.length - 1] as { epoch?: unknown }).epoch
+
+/**
+ * Removes the cached queries of a dropped, renamed or disconnected namespace.
+ * @param db Omit to cover the whole connection.
+ * @param coll Omit to cover the whole database.
+ */
+export function removeNamespaceQueries(
+  qc: QueryClient,
+  connectionId: string,
+  db?: string,
+  coll?: string
+): void {
+  const scope =
+    db === undefined
+      ? [connectionId]
+      : coll === undefined
+        ? [connectionId, db]
+        : [connectionId, db, coll]
+  qc.removeQueries({
+    predicate: ({ queryKey }) => {
+      const family = familyOf(queryKey)
+      // Coarser families stay: removing a mounted shell result would re-run it.
+      return (
+        family !== undefined &&
+        family.depth >= scope.length &&
+        keyWithin(queryKey, family.at, scope)
+      )
+    }
+  })
+}
+
+/**
+ * Refreshes what a write to the collection may have changed; call it after every write.
+ * @returns Settles once the shown results that may read the collection have refetched.
+ */
+export function invalidateWrittenCollection(
+  qc: QueryClient,
+  { connectionId, db, coll }: CollectionRef
+): Promise<void> {
+  const scope = [connectionId, db, coll]
+  const readingRun = (key: QueryKey): QueryMode | undefined => {
+    const family = familyOf(key)
+    return family && keyWithin(key, family.at, scope.slice(0, family.depth))
+      ? family.run
+      : undefined
+  }
+  return Promise.all([
+    qc.invalidateQueries({ predicate: ({ queryKey }) => readingRun(queryKey) === 'simple' }),
+    // A hidden aggregation or shell result marked stale would re-run on its next tab or mode switch.
+    qc.refetchQueries({
+      type: 'active',
+      predicate: ({ queryKey }) => isTabRun(readingRun(queryKey))
+    }),
+    // An insert or $out may have created the collection.
+    qc.invalidateQueries({ queryKey: queryKeys.collections(connectionId, db) }),
+    qc.invalidateQueries({ queryKey: queryKeys.collectionStats(connectionId, db, coll) })
+  ]).then(() => undefined)
+}
+
+/**
+ * Options of the shell write mutation: each `mutate` runs its write once; no query can re-run it.
+ * @param qc Refreshed after every write, failed ones included.
+ */
+export function shellWriteOptions(
+  qc: QueryClient
+): MutationOptions<ShellWriteResult, Error, ShellWriteVariables> {
+  return {
+    mutationKey: mutationKeys.shellWrite,
+    mutationFn: ({ target, command }) => runShellWrite(target, command),
+    // A failed ordered insertMany or bulkWrite may have written its first documents.
+    onSettled: (_result, _error, { target, command }) => {
+      void invalidateWrittenCollection(qc, writtenCollection(target, command))
+    },
+    // Shown until its tab closes or a newer shell run replaces it.
+    gcTime: Infinity
+  }
+}
+
+function releaseRuns(matches: (key: QueryKey) => boolean): void {
+  cancelRequests(matches)
+  queryClient.removeQueries({ predicate: (query) => matches(query.queryKey) })
+}
+
+// A write still running finishes on the server; only its result is dropped.
+function releaseWrites(matches: (run: ShellWriteVariables) => boolean): void {
+  const cache = queryClient.getMutationCache()
+  for (const mutation of cache.findAll({ mutationKey: mutationKeys.shellWrite })) {
+    const run = mutation.state.variables as ShellWriteVariables | undefined
+    if (run && matches(run)) cache.remove(mutation)
+  }
+}
+
+/** Drops a closed tab's aggregation / shell results and shell writes; aborts its running reads. */
+export function releaseTabResults(tabId: string): void {
+  releaseRuns((key) => tabOf(key) === tabId)
+  releaseWrites((run) => run.tabId === tabId)
 }
+
+/** Forgets a disconnected or deleted connection: its connected state, tabs and cached queries. */
+export function releaseConnection(qc: QueryClient, connectionId: string): void {
+  useAppStore.getState().markDisconnected(connectionId)
+  useTabsStore.getState().closeForConnection(connectionId)
+  removeNamespaceQueries(qc, connectionId)
+}
+
+function releaseSuperseded(
+  mode: 'aggregation' | 'shell',
+  tabId: string,
+  current: AppliedSource | null
+): void {
+  releaseRuns(
+    (key) => familyOf(key)?.run === mode && tabOf(key) === tabId && epochOf(key) !== current?.epoch
+  )
+}
+
+// Every close, Run, lookup and rename ends up here; a run no open tab can show again is released.
+useTabsStore.subscribe((state, prev) => {
+  if (state.tabs === prev.tabs) return
+  const open = new Map(state.tabs.map((t) => [t.id, t.applied]))
+  // Duplicates share a simple epoch, so its pages and count stay while any tab holds it.
+  const heldEpochs = new Set(state.tabs.map((t) => t.applied.simple.epoch))
+  for (const { id, applied } of prev.tabs) {
+    const next = open.get(id)
+    if (!next) {
+      releaseTabResults(id)
+    } else {
+      if (next.aggregation !== applied.aggregation) {
+        releaseSuperseded('aggregation', id, next.aggregation)
+      }
+      if (next.shell !== applied.shell) {
+        releaseSuperseded('shell', id, next.shell)
+        releaseWrites((run) => run.tabId === id && run.epoch !== next.shell?.epoch)
+      }
+    }
+    const { epoch } = applied.simple
+    if (!heldEpochs.has(epoch)) {
+      releaseRuns((key) => familyOf(key)?.run === 'simple' && epochOf(key) === epoch)
+    }
+  }
+})
diff --git a/src/renderer/src/lib/queryModelUri.test.ts b/src/renderer/src/lib/queryModelUri.test.ts
new file mode 100644
index 0000000..95a4f2d
--- /dev/null
+++ b/src/renderer/src/lib/queryModelUri.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { queryModelTabId, queryModelUri, type QueryEditorSlot } from './queryModelUri'
+
+// Monaco's Uri exposes the same scheme / authority / path split as WHATWG URL for these URIs.
+const parts = (uri: string) => {
+  const url = new URL(uri)
+  return { scheme: url.protocol.replace(/:$/, ''), authority: url.host, path: url.pathname }
+}
+
+describe('queryModelUri', () => {
+  it('puts the tab id and slot in the path', () => {
+    expect(queryModelUri('t3', 'filter')).toBe('mongobench://query/t3/filter')
+  })
+
+  it.each<QueryEditorSlot>(['filter', 'projection', 'sort', 'pipeline', 'shell'])(
+    'round-trips the %s slot',
+    (slot) => {
+      expect(queryModelTabId(parts(queryModelUri('t12', slot)))).toBe('t12')
+    }
+  )
+})
+
+describe('queryModelTabId', () => {
+  it.each([
+    'inmemory://model/1',
+    'mongobench://other/t1/filter',
+    'mongobench://query/t1/limit',
+    'mongobench://query/t1/filter/extra',
+    'mongobench://query//filter',
+    'mongobench://query/t1',
+    'file:///query/t1/filter'
+  ])('returns null for %s', (uri) => {
+    expect(queryModelTabId(parts(uri))).toBeNull()
+  })
+})
diff --git a/src/renderer/src/lib/queryModelUri.ts b/src/renderer/src/lib/queryModelUri.ts
new file mode 100644
index 0000000..7fc5bce
--- /dev/null
+++ b/src/renderer/src/lib/queryModelUri.ts
@@ -0,0 +1,25 @@
+const SLOTS = ['filter', 'projection', 'sort', 'pipeline', 'shell'] as const
+
+export type QueryEditorSlot = (typeof SLOTS)[number]
+
+const isSlot = (value: string): value is QueryEditorSlot =>
+  (SLOTS as readonly string[]).includes(value)
+
+/** Model path of one query editor of a tab, passed to @monaco-editor/react `path`. */
+export function queryModelUri(tabId: string, slot: QueryEditorSlot): string {
+  // The tab id goes in the path because URIs print their authority lowercased.
+  return `mongobench://query/${tabId}/${slot}`
+}
+
+/** Tab id of a query-editor model; null for any other model (e.g. the document editor's). */
+export function queryModelTabId(uri: {
+  scheme: string
+  authority: string
+  path: string
+}): string | null {
+  if (uri.scheme !== 'mongobench' || uri.authority !== 'query') return null
+  const match = /^\/([^/]+)\/([a-z]+)$/.exec(uri.path)
+  const tabId = match?.[1]
+  const slot = match?.[2]
+  return tabId !== undefined && slot !== undefined && isSlot(slot) ? tabId : null
+}
diff --git a/src/renderer/src/lib/queryRun.test.ts b/src/renderer/src/lib/queryRun.test.ts
new file mode 100644
index 0000000..2cca0cc
--- /dev/null
+++ b/src/renderer/src/lib/queryRun.test.ts
@@ -0,0 +1,542 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { RESULT_CAP, type DocumentEnvelope, type WriteOp } from '@shared/types'
+import type { AppliedSimple } from '@/store/tabs'
+import {
+  boundedFindLimit,
+  compileFind,
+  runAggregation,
+  runFind,
+  runShellCommand,
+  runShellWrite,
+  writtenCollection,
+  type ShellReadCommand,
+  type ShellWriteCommand
+} from './queryRun'
+
+const { find, aggregate, count, distinct, write } = vi.hoisted(() => ({
+  find: vi.fn(),
+  aggregate: vi.fn(),
+  count: vi.fn(),
+  distinct: vi.fn(),
+  write: vi.fn()
+}))
+vi.mock('./api', () => ({ api: { query: { find, aggregate, count, distinct, write } } }))
+
+const CONN = '00000000-0000-4000-8000-000000000001'
+const REQUEST = '00000000-0000-4000-8000-0000000000aa'
+const DB = { connectionId: CONN, db: 'app' }
+const USERS = { ...DB, coll: 'users' }
+
+const envelope = (n: number): DocumentEnvelope => ({
+  id: `{"$numberInt":"${n}"}`,
+  data: { _id: n },
+  canonical: `{"_id":{"$numberInt":"${n}"}}`,
+  hash: 'h'
+})
+const rows = (n: number): DocumentEnvelope[] => Array.from({ length: n }, (_, i) => envelope(i))
+
+const applied = (patch: Partial<AppliedSimple> = {}): AppliedSimple => ({
+  filter: '{}',
+  projection: '{}',
+  sort: '{}',
+  skip: 0,
+  limit: 100,
+  epoch: 1,
+  ...patch
+})
+
+beforeEach(() => {
+  find.mockReset().mockResolvedValue({ documents: rows(2), tookMs: 7 })
+  aggregate.mockReset().mockResolvedValue({ documents: rows(2), tookMs: 8, truncated: false })
+  count.mockReset().mockResolvedValue({ count: 42, estimated: false, tookMs: 3 })
+  distinct.mockReset().mockResolvedValue({ documents: rows(2), tookMs: 4, truncated: false })
+  write.mockReset().mockResolvedValue({ tookMs: 11, counts: {}, ids: [], idsTruncated: false })
+})
+
+describe('boundedFindLimit', () => {
+  it.each([
+    [null, RESULT_CAP + 1],
+    [1, 1],
+    [50, 50],
+    [RESULT_CAP, RESULT_CAP],
+    [RESULT_CAP + 1, RESULT_CAP + 1],
+    [5000, RESULT_CAP + 1]
+  ])('maps %s to %s', (limit, expected) => {
+    expect(boundedFindLimit(limit)).toBe(expected)
+  })
+})
+
+describe('compileFind', () => {
+  it('compiles the editor texts to EJSON and keeps paging', () => {
+    const result = compileFind(
+      applied({ filter: '{ age: { $gt: 5 } }', sort: '{ a: -1 }', skip: 20, limit: 10 })
+    )
+    expect(result).toEqual({
+      ok: true,
+      find: { filter: '{"age":{"$gt":5}}', projection: '{}', sort: '{"a":-1}', skip: 20, limit: 10 }
+    })
+  })
+
+  it('names the editor that fails to parse', () => {
+    expect(compileFind(applied({ projection: '{ a: }' }))).toMatchObject({
+      ok: false,
+      error: expect.stringMatching(/^Projection: /)
+    })
+    expect(compileFind(applied({ filter: '{', sort: '{ a: }' }))).toMatchObject({
+      ok: false,
+      error: expect.stringMatching(/^Filter: /)
+    })
+  })
+})
+
+describe('runFind', () => {
+  const compiled = (patch: Record<string, unknown> = {}) => ({
+    filter: '{}',
+    projection: '{}',
+    sort: '{}',
+    skip: 0,
+    limit: 100,
+    ...patch
+  })
+
+  it('sends the query with its request id and wraps whole documents as full rows', async () => {
+    const result = await runFind(USERS, compiled({ skip: 200 }), REQUEST)
+    expect(find).toHaveBeenCalledWith({
+      ...USERS,
+      filter: '{}',
+      projection: '{}',
+      sort: '{}',
+      skip: 200,
+      limit: 100,
+      requestId: REQUEST
+    })
+    expect(result).toEqual({
+      kind: 'documents',
+      origin: 'find',
+      documents: rows(2),
+      tookMs: 7,
+      truncated: false,
+      rowAccess: 'full',
+      coll: 'users'
+    })
+  })
+
+  it('omits a zero limit and empty editors', async () => {
+    await runFind(USERS, compiled({ filter: '', projection: '', sort: '', limit: 0 }), REQUEST)
+    expect(find).toHaveBeenCalledWith({ ...USERS, skip: 0, requestId: REQUEST })
+  })
+
+  it('gives projected rows byId access', async () => {
+    const result = await runFind(USERS, compiled({ projection: '{"name":1}' }), REQUEST)
+    expect(result).toMatchObject({ rowAccess: 'byId' })
+  })
+
+  it('treats an empty projection as whole documents', async () => {
+    expect(await runFind(USERS, compiled({ projection: '' }), REQUEST)).toMatchObject({
+      rowAccess: 'full'
+    })
+  })
+})
+
+describe('runAggregation', () => {
+  it('sends the compiled pipeline with its request id', async () => {
+    await runAggregation(USERS, { ejson: '[{"$match":{}}]', documentPreserving: true }, REQUEST)
+    expect(aggregate).toHaveBeenCalledWith({
+      ...USERS,
+      pipeline: '[{"$match":{}}]',
+      requestId: REQUEST
+    })
+  })
+
+  it('gives full access only to document-preserving pipelines', async () => {
+    const preserving = await runAggregation(
+      USERS,
+      { ejson: '[]', documentPreserving: true },
+      REQUEST
+    )
+    const derived = await runAggregation(
+      USERS,
+      { ejson: '[{"$group":{"_id":"$a"}}]', documentPreserving: false },
+      REQUEST
+    )
+    expect(preserving).toMatchObject({ kind: 'documents', origin: 'aggregate', rowAccess: 'full' })
+    expect(derived).toMatchObject({ rowAccess: 'none' })
+  })
+
+  it('reports truncation from the response', async () => {
+    aggregate.mockResolvedValue({ documents: rows(RESULT_CAP), tookMs: 9, truncated: true })
+    const result = await runAggregation(USERS, { ejson: '[]', documentPreserving: true }, REQUEST)
+    expect(result).toMatchObject({ truncated: true, tookMs: 9, coll: 'users' })
+  })
+})
+
+describe('runShellCommand', () => {
+  const shell = (coll: string, op: ShellReadCommand['op']): ShellReadCommand => ({ coll, op })
+  const findOp = (patch: Record<string, unknown> = {}): ShellReadCommand['op'] => ({
+    kind: 'find',
+    filter: '{"a":1}',
+    projection: null,
+    sort: null,
+    skip: 0,
+    limit: null,
+    ...patch
+  })
+
+  it('caps a find without a limit at RESULT_CAP + 1 and targets the command collection', async () => {
+    await runShellCommand(DB, shell('orders', findOp({ skip: 30 })), REQUEST)
+    expect(find).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      filter: '{"a":1}',
+      skip: 30,
+      limit: RESULT_CAP + 1,
+      requestId: REQUEST
+    })
+  })
+
+  it('passes projection, sort and a small limit through', async () => {
+    await runShellCommand(
+      DB,
+      shell('orders', findOp({ projection: '{"b":1}', sort: '{"c":-1}', limit: 5 })),
+      REQUEST
+    )
+    expect(find).toHaveBeenCalledWith(
+      expect.objectContaining({ projection: '{"b":1}', sort: '{"c":-1}', limit: 5 })
+    )
+  })
+
+  it('cuts RESULT_CAP + 1 rows to RESULT_CAP and marks the result truncated', async () => {
+    find.mockResolvedValue({ documents: rows(RESULT_CAP + 1), tookMs: 5 })
+    const result = await runShellCommand(DB, shell('orders', findOp()), REQUEST)
+    expect(result).toMatchObject({ kind: 'documents', origin: 'find', truncated: true })
+    expect(result.kind === 'documents' && result.documents).toHaveLength(RESULT_CAP)
+  })
+
+  it('does not mark exactly RESULT_CAP rows as truncated', async () => {
+    find.mockResolvedValue({ documents: rows(RESULT_CAP), tookMs: 5 })
+    const result = await runShellCommand(DB, shell('orders', findOp()), REQUEST)
+    expect(result).toMatchObject({ truncated: false, coll: 'orders' })
+  })
+
+  it('derives row access from the projection', async () => {
+    const whole = await runShellCommand(DB, shell('orders', findOp()), REQUEST)
+    const partial = await runShellCommand(
+      DB,
+      shell('orders', findOp({ projection: '{"b":1}' })),
+      REQUEST
+    )
+    expect(whole).toMatchObject({ rowAccess: 'full' })
+    expect(partial).toMatchObject({ rowAccess: 'byId' })
+  })
+
+  it('runs findOne as a find with limit 1', async () => {
+    const result = await runShellCommand(
+      DB,
+      shell('orders', { kind: 'findOne', filter: '{}', projection: '{"x":1}' }),
+      REQUEST
+    )
+    expect(find).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      filter: '{}',
+      projection: '{"x":1}',
+      skip: 0,
+      limit: 1,
+      requestId: REQUEST
+    })
+    expect(result).toMatchObject({ origin: 'find', rowAccess: 'byId', truncated: false })
+  })
+
+  it('maps aggregate with its preserving flag and response truncation', async () => {
+    aggregate.mockResolvedValue({ documents: rows(1), tookMs: 2, truncated: true })
+    const result = await runShellCommand(
+      DB,
+      shell('orders', { kind: 'aggregate', pipeline: '[]', documentPreserving: false }),
+      REQUEST
+    )
+    expect(aggregate).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      pipeline: '[]',
+      requestId: REQUEST
+    })
+    expect(result).toMatchObject({ origin: 'aggregate', rowAccess: 'none', truncated: true })
+  })
+
+  it('counts exactly for countDocuments', async () => {
+    const result = await runShellCommand(
+      DB,
+      shell('orders', { kind: 'count', method: 'countDocuments', filter: '{}' }),
+      REQUEST
+    )
+    expect(count).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      filter: '{}',
+      exact: true,
+      requestId: REQUEST
+    })
+    expect(result).toEqual({
+      kind: 'count',
+      method: 'countDocuments',
+      count: 42,
+      estimated: false,
+      tookMs: 3,
+      coll: 'orders'
+    })
+  })
+
+  it('lets legacy count estimate an empty filter', async () => {
+    count.mockResolvedValue({ count: 10, estimated: true, tookMs: 1 })
+    const result = await runShellCommand(
+      DB,
+      shell('orders', { kind: 'count', method: 'count', filter: '{}' }),
+      REQUEST
+    )
+    expect(count).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      filter: '{}',
+      exact: false,
+      requestId: REQUEST
+    })
+    expect(result).toMatchObject({ method: 'count', estimated: true })
+  })
+
+  it('sends no filter for estimatedDocumentCount', async () => {
+    count.mockResolvedValue({ count: 10, estimated: true, tookMs: 1 })
+    await runShellCommand(
+      DB,
+      shell('orders', { kind: 'count', method: 'estimatedDocumentCount', filter: null }),
+      REQUEST
+    )
+    expect(count).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      exact: false,
+      requestId: REQUEST
+    })
+  })
+
+  it('runs distinct without a request id and never grants row access', async () => {
+    distinct.mockResolvedValue({ documents: rows(3), tookMs: 6, truncated: true })
+    const result = await runShellCommand(
+      DB,
+      shell('orders', { kind: 'distinct', field: 'status', filter: '{"a":1}' }),
+      REQUEST
+    )
+    expect(distinct).toHaveBeenCalledWith({
+      ...DB,
+      coll: 'orders',
+      field: 'status',
+      filter: '{"a":1}'
+    })
+    expect(result).toMatchObject({
+      kind: 'documents',
+      origin: 'distinct',
+      rowAccess: 'none',
+      truncated: true,
+      tookMs: 6
+    })
+  })
+
+  it('omits an absent distinct filter', async () => {
+    await runShellCommand(
+      DB,
+      shell('orders', { kind: 'distinct', field: 'status', filter: null }),
+      REQUEST
+    )
+    expect(distinct).toHaveBeenCalledWith({ ...DB, coll: 'orders', field: 'status' })
+  })
+})
+
+describe('runShellWrite', () => {
+  const writeCommand = (
+    coll: string,
+    op: WriteOp,
+    writes: ShellWriteCommand['op']['writes'] = { db: null, coll }
+  ): ShellWriteCommand => ({ coll, op: { kind: 'write', write: op, writes } })
+
+  it('sends the write op for the command collection and maps the response', async () => {
+    write.mockResolvedValue({
+      tookMs: 9,
+      counts: { inserted: 2 },
+      ids: ['{"$oid":"65f0a0a0a0a0a0a0a0a0a0a1"}', '{"$numberInt":"7"}'],
+      idsTruncated: false
+    })
+    const op: WriteOp = { method: 'insertMany', documents: ['{}', '{"_id":{"$numberInt":"7"}}'] }
+    const result = await runShellWrite(DB, writeCommand('orders', op))
+    expect(write).toHaveBeenCalledWith({ ...DB, coll: 'orders', op })
+    expect(result).toEqual({
+      method: 'insertMany',
+      counts: { inserted: 2 },
+      ids: ['{"$oid":"65f0a0a0a0a0a0a0a0a0a0a1"}', '{"$numberInt":"7"}'],
+      idsTruncated: false,
+      returned: null,
+      writes: { ...DB, coll: 'orders' },
+      tookMs: 9
+    })
+  })
+
+  it.each<WriteOp>([
+    { method: 'insertOne', document: '{}' },
+    { method: 'updateOne', filter: '{}', update: '{"$set":{"a":{"$numberInt":"1"}}}' },
+    { method: 'updateMany', filter: '{}', update: '[{"$set":{"a":"$b"}}]' },
+    { method: 'replaceOne', filter: '{}', replacement: '{"a":{"$numberInt":"1"}}' },
+    { method: 'deleteOne', filter: '{"a":{"$numberInt":"1"}}' },
+    { method: 'deleteMany', filter: '{}' },
+    {
+      method: 'bulkWrite',
+      operations: '[{"deleteOne":{"filter":{}}}]',
+      options: '{"ordered":false}'
+    }
+  ])('returns no document for $method', async (op) => {
+    write.mockResolvedValue({ tookMs: 1, counts: { deleted: 1 }, ids: [], idsTruncated: false })
+    const result = await runShellWrite(DB, writeCommand('orders', op))
+    expect(write).toHaveBeenCalledWith({ ...DB, coll: 'orders', op })
+    expect(result).toMatchObject({ method: op.method, counts: { deleted: 1 }, returned: null })
+  })
+
+  it('keeps the truncation of the ids', async () => {
+    write.mockResolvedValue({
+      tookMs: 1,
+      counts: { inserted: RESULT_CAP + 5 },
+      ids: Array.from({ length: RESULT_CAP }, (_, i) => `{"$numberInt":"${i}"}`),
+      idsTruncated: true
+    })
+    const op: WriteOp = { method: 'insertMany', documents: ['{}'] }
+    const result = await runShellWrite(DB, writeCommand('orders', op))
+    expect(result.idsTruncated).toBe(true)
+    expect(result.ids).toHaveLength(RESULT_CAP)
+  })
+
+  it('reports the $out / $merge target of an aggregation as the written collection', async () => {
+    const op: WriteOp = {
+      method: 'aggregate',
+      pipeline: '[{"$out":{"db":"archive","coll":"old"}}]'
+    }
+    const result = await runShellWrite(
+      DB,
+      writeCommand('orders', op, { db: 'archive', coll: 'old' })
+    )
+    expect(write).toHaveBeenCalledWith({ ...DB, coll: 'orders', op })
+    expect(result).toMatchObject({
+      method: 'aggregate',
+      returned: null,
+      writes: { connectionId: CONN, db: 'archive', coll: 'old' }
+    })
+  })
+
+  describe('returned document', () => {
+    const doc = envelope(1)
+
+    // Main decodes the returned document with value promotion, so it is never edited as is.
+    it.each<{ name: string; op: WriteOp; rowAccess: 'byId' | 'none' }>([
+      {
+        name: 'findOneAndDelete',
+        op: { method: 'findOneAndDelete', filter: '{}' },
+        rowAccess: 'none'
+      },
+      {
+        name: 'findOneAndDelete returning a projection',
+        op: { method: 'findOneAndDelete', filter: '{}', options: '{"projection":{"a":1}}' },
+        rowAccess: 'none'
+      },
+      {
+        name: 'findOneAndUpdate returning the document before the update',
+        op: { method: 'findOneAndUpdate', filter: '{}', update: '{"$set":{"a":1}}' },
+        rowAccess: 'byId'
+      },
+      {
+        name: 'findOneAndUpdate with returnDocument "after"',
+        op: {
+          method: 'findOneAndUpdate',
+          filter: '{}',
+          update: '{"$set":{"a":1}}',
+          options: '{"returnDocument":"after"}'
+        },
+        rowAccess: 'byId'
+      },
+      {
+        name: 'findOneAndUpdate with returnNewDocument true',
+        op: {
+          method: 'findOneAndUpdate',
+          filter: '{}',
+          update: '{"$set":{"a":1}}',
+          options: '{"returnNewDocument":true,"upsert":true}'
+        },
+        rowAccess: 'byId'
+      },
+      {
+        name: 'findOneAndUpdate with an empty projection of the new document',
+        op: {
+          method: 'findOneAndUpdate',
+          filter: '{}',
+          update: '{"$set":{"a":1}}',
+          options: '{"returnDocument":"after","projection":{}}'
+        },
+        rowAccess: 'byId'
+      },
+      {
+        name: 'findOneAndReplace returning the replaced document',
+        op: { method: 'findOneAndReplace', filter: '{}', replacement: '{}' },
+        rowAccess: 'byId'
+      },
+      {
+        name: 'findOneAndReplace with returnDocument "after"',
+        op: {
+          method: 'findOneAndReplace',
+          filter: '{}',
+          replacement: '{}',
+          options: '{"returnDocument":"after"}'
+        },
+        rowAccess: 'byId'
+      }
+    ])('$name gives $rowAccess access', async ({ op, rowAccess }) => {
+      write.mockResolvedValue({
+        tookMs: 1,
+        counts: {},
+        ids: [],
+        idsTruncated: false,
+        document: doc
+      })
+      const result = await runShellWrite(DB, writeCommand('orders', op))
+      expect(result.returned).toEqual({ document: doc, rowAccess })
+    })
+
+    it('reports a findOneAnd* that matched nothing as a null document', async () => {
+      write.mockResolvedValue({
+        tookMs: 1,
+        counts: {},
+        ids: [],
+        idsTruncated: false,
+        document: null
+      })
+      const op: WriteOp = { method: 'findOneAndDelete', filter: '{"a":1}' }
+      const result = await runShellWrite(DB, writeCommand('orders', op))
+      expect(result.returned).toEqual({ document: null, rowAccess: 'none' })
+    })
+  })
+})
+
+describe('writtenCollection', () => {
+  const command = (writes: ShellWriteCommand['op']['writes']): ShellWriteCommand => ({
+    coll: 'orders',
+    op: { kind: 'write', write: { method: 'aggregate', pipeline: '[]' }, writes }
+  })
+
+  it('resolves a target without a database to the tab database', () => {
+    expect(writtenCollection(DB, command({ db: null, coll: 'summary' }))).toEqual({
+      ...DB,
+      coll: 'summary'
+    })
+  })
+
+  it('keeps a target in another database', () => {
+    expect(writtenCollection(DB, command({ db: 'archive', coll: 'summary' }))).toEqual({
+      connectionId: CONN,
+      db: 'archive',
+      coll: 'summary'
+    })
+  })
+})
diff --git a/src/renderer/src/lib/queryRun.ts b/src/renderer/src/lib/queryRun.ts
new file mode 100644
index 0000000..ff71652
--- /dev/null
+++ b/src/renderer/src/lib/queryRun.ts
@@ -0,0 +1,291 @@
+import {
+  RESULT_CAP,
+  type CollectionRef,
+  type DatabaseRef,
+  type DocumentEnvelope,
+  type FindRequest,
+  type WriteOp,
+  type WriteResponse
+} from '@shared/types'
+import type { AppliedSimple } from '@/store/tabs'
+import type { CompiledPipeline } from './aggregationPipeline'
+import { api } from './api'
+import { parseMongoQuery } from './mongoQueryLang'
+import type { ShellCountMethod, ShellOp } from './shellParser'
+
+/** How rows relate to stored documents of the result's collection. */
+export type RowAccess = 'full' | 'byId' | 'none'
+
+/** A shell command that reads; it runs as a cancellable query. */
+export type ShellReadCommand = { coll: string; op: Exclude<ShellOp, { kind: 'write' }> }
+
+/** A shell command that writes; it runs once per Run, as a mutation. */
+export type ShellWriteCommand = { coll: string; op: Extract<ShellOp, { kind: 'write' }> }
+
+/** What a shell write did; `writes` is the collection it changed. */
+export type ShellWriteResult = {
+  method: WriteOp['method']
+  /** Counters that apply to the method. */
+  counts: WriteResponse['counts']
+  /** Canonical EJSON of the inserted or upserted `_id`s. */
+  ids: string[]
+  /** More ids were written than `ids` holds. */
+  idsTruncated: boolean
+  /** findOneAnd*: the returned document (null when none matched) and its row access; else null. */
+  returned: { document: DocumentEnvelope | null; rowAccess: RowAccess } | null
+  writes: CollectionRef
+  tookMs: number
+}
+
+/** What a run displays; `coll` is the collection the rows belong to. */
+export type QueryResult =
+  | {
+      kind: 'documents'
+      origin: 'find' | 'aggregate' | 'distinct'
+      documents: DocumentEnvelope[]
+      tookMs: number
+      /** More rows existed than RESULT_CAP; only the first RESULT_CAP are included. */
+      truncated: boolean
+      rowAccess: RowAccess
+      coll: string
+    }
+  | {
+      kind: 'count'
+      method: ShellCountMethod
+      count: number
+      estimated: boolean
+      tookMs: number
+      coll: string
+    }
+
+/** A Simple-mode query as EJSON; empty strings mean "not given". */
+export type CompiledFind = {
+  filter: string
+  projection: string
+  sort: string
+  skip: number
+  /** 0 = no limit. */
+  limit: number
+}
+
+/** Compiles an applied Simple query; the error names the editor that failed to parse. */
+export function compileFind(
+  applied: AppliedSimple
+): { ok: true; find: CompiledFind } | { ok: false; error: string } {
+  const filter = parseMongoQuery(applied.filter)
+  if (!filter.ok) return { ok: false, error: `Filter: ${filter.error}` }
+  const projection = parseMongoQuery(applied.projection)
+  if (!projection.ok) return { ok: false, error: `Projection: ${projection.error}` }
+  const sort = parseMongoQuery(applied.sort)
+  if (!sort.ok) return { ok: false, error: `Sort: ${sort.error}` }
+  return {
+    ok: true,
+    find: {
+      filter: filter.ejson,
+      projection: projection.ejson,
+      sort: sort.ejson,
+      skip: applied.skip,
+      limit: applied.limit
+    }
+  }
+}
+
+/** Limit sent for a shell find: at most RESULT_CAP rows shown, one extra detects truncation. */
+export function boundedFindLimit(limit: number | null): number {
+  return limit !== null && limit <= RESULT_CAP ? limit : RESULT_CAP + 1
+}
+
+const isWholeDocument = (projection: string | null): boolean =>
+  projection === null || projection === '' || projection === '{}'
+
+/**
+ * Runs a Simple-mode find; uncapped, it pages with its own skip and limit.
+ * @param requestId Lets `query.cancel` abort the server op.
+ */
+export async function runFind(
+  ref: CollectionRef,
+  find: CompiledFind,
+  requestId: string
+): Promise<QueryResult> {
+  const response = await api.query.find({
+    connectionId: ref.connectionId,
+    db: ref.db,
+    coll: ref.coll,
+    ...(find.filter ? { filter: find.filter } : {}),
+    ...(find.projection ? { projection: find.projection } : {}),
+    ...(find.sort ? { sort: find.sort } : {}),
+    skip: find.skip,
+    ...(find.limit > 0 ? { limit: find.limit } : {}),
+    requestId
+  })
+  return {
+    kind: 'documents',
+    origin: 'find',
+    documents: response.documents,
+    tookMs: response.tookMs,
+    truncated: false,
+    rowAccess: isWholeDocument(find.projection) ? 'full' : 'byId',
+    coll: ref.coll
+  }
+}
+
+/**
+ * Runs an aggregation-mode pipeline on the tab's collection; main caps it at RESULT_CAP.
+ * @param requestId Lets `query.cancel` abort the server op.
+ */
+export async function runAggregation(
+  ref: CollectionRef,
+  compiled: CompiledPipeline,
+  requestId: string
+): Promise<QueryResult> {
+  const response = await api.query.aggregate({
+    connectionId: ref.connectionId,
+    db: ref.db,
+    coll: ref.coll,
+    pipeline: compiled.ejson,
+    requestId
+  })
+  return {
+    kind: 'documents',
+    origin: 'aggregate',
+    documents: response.documents,
+    tookMs: response.tookMs,
+    truncated: response.truncated,
+    rowAccess: compiled.documentPreserving ? 'full' : 'none',
+    coll: ref.coll
+  }
+}
+
+/**
+ * Runs a parsed shell read against any collection of the database.
+ * @param requestId Lets `query.cancel` abort the server op; distinct ignores it.
+ */
+export async function runShellCommand(
+  target: DatabaseRef,
+  command: ShellReadCommand,
+  requestId: string
+): Promise<QueryResult> {
+  const ref: CollectionRef = {
+    connectionId: target.connectionId,
+    db: target.db,
+    coll: command.coll
+  }
+  const { op } = command
+  switch (op.kind) {
+    case 'find':
+      return runShellFind(ref, op, boundedFindLimit(op.limit), requestId)
+    case 'findOne':
+      return runShellFind(ref, { ...op, sort: null, skip: 0 }, 1, requestId)
+    case 'aggregate':
+      return runAggregation(
+        ref,
+        { ejson: op.pipeline, documentPreserving: op.documentPreserving },
+        requestId
+      )
+    case 'count': {
+      const response = await api.query.count({
+        ...ref,
+        ...(op.filter !== null ? { filter: op.filter } : {}),
+        // countDocuments is always exact; legacy count() estimates an empty filter, like mongosh.
+        exact: op.method === 'countDocuments',
+        requestId
+      })
+      return {
+        kind: 'count',
+        method: op.method,
+        count: response.count,
+        estimated: response.estimated,
+        tookMs: response.tookMs,
+        coll: ref.coll
+      }
+    }
+    case 'distinct': {
+      const response = await api.query.distinct({
+        ...ref,
+        field: op.field,
+        ...(op.filter !== null ? { filter: op.filter } : {})
+      })
+      return {
+        kind: 'documents',
+        origin: 'distinct',
+        documents: response.documents,
+        tookMs: response.tookMs,
+        truncated: response.truncated,
+        rowAccess: 'none',
+        coll: ref.coll
+      }
+    }
+  }
+}
+
+/** The collection a shell write changes: the command's own, or the $out / $merge target. */
+export function writtenCollection(target: DatabaseRef, command: ShellWriteCommand): CollectionRef {
+  const { writes } = command.op
+  return { connectionId: target.connectionId, db: writes.db ?? target.db, coll: writes.coll }
+}
+
+/** Runs a shell write against any collection of the database; the driver cannot abort writes. */
+export async function runShellWrite(
+  target: DatabaseRef,
+  command: ShellWriteCommand
+): Promise<ShellWriteResult> {
+  const { write } = command.op
+  const response = await api.query.write({
+    connectionId: target.connectionId,
+    db: target.db,
+    coll: command.coll,
+    op: write
+  })
+  return {
+    method: write.method,
+    counts: response.counts,
+    ids: response.ids,
+    idsTruncated: response.idsTruncated,
+    returned: returnedDocument(write, response.document ?? null),
+    writes: writtenCollection(target, command),
+    tookMs: response.tookMs
+  }
+}
+
+function returnedDocument(
+  write: WriteOp,
+  document: DocumentEnvelope | null
+): ShellWriteResult['returned'] {
+  switch (write.method) {
+    case 'findOneAndDelete':
+      return { document, rowAccess: 'none' }
+    case 'findOneAndUpdate':
+    case 'findOneAndReplace':
+      // An integral Double may arrive as Int32 (main promotes values), so edits load the stored one.
+      return { document, rowAccess: 'byId' }
+    default:
+      return null
+  }
+}
+
+async function runShellFind(
+  ref: CollectionRef,
+  op: { filter: string; projection: string | null; sort: string | null; skip: number },
+  limit: number,
+  requestId: string
+): Promise<QueryResult> {
+  const request: FindRequest = {
+    ...ref,
+    filter: op.filter,
+    ...(op.projection !== null ? { projection: op.projection } : {}),
+    ...(op.sort !== null ? { sort: op.sort } : {}),
+    skip: op.skip,
+    limit,
+    requestId
+  }
+  const response = await api.query.find(request)
+  return {
+    kind: 'documents',
+    origin: 'find',
+    documents: response.documents.slice(0, RESULT_CAP),
+    tookMs: response.tookMs,
+    truncated: response.documents.length > RESULT_CAP,
+    rowAccess: isWholeDocument(op.projection) ? 'full' : 'byId',
+    coll: ref.coll
+  }
+}
diff --git a/src/renderer/src/lib/reorder.test.ts b/src/renderer/src/lib/reorder.test.ts
new file mode 100644
index 0000000..31571dc
--- /dev/null
+++ b/src/renderer/src/lib/reorder.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { reorderIds } from './reorder'
+
+const ids = ['A', 'B', 'C', 'D']
+
+describe('reorderIds', () => {
+  it.each<[string, string, 'before' | 'after', string[]]>([
+    ['A', 'C', 'before', ['B', 'A', 'C', 'D']],
+    ['A', 'C', 'after', ['B', 'C', 'A', 'D']],
+    ['A', 'D', 'after', ['B', 'C', 'D', 'A']],
+    ['D', 'B', 'before', ['A', 'D', 'B', 'C']],
+    ['D', 'B', 'after', ['A', 'B', 'D', 'C']],
+    ['D', 'A', 'before', ['D', 'A', 'B', 'C']]
+  ])('moves %s %s → %s %s', (drag, over, pos, expected) => {
+    expect(reorderIds(ids, drag, over, pos)).toEqual(expected)
+  })
+
+  it.each<[string, string, 'before' | 'after']>([
+    ['A', 'B', 'before'],
+    ['B', 'A', 'after'],
+    ['B', 'B', 'before'],
+    ['X', 'B', 'before'],
+    ['A', 'X', 'after']
+  ])('returns null when dropping %s on %s (%s) keeps the order', (drag, over, pos) => {
+    expect(reorderIds(ids, drag, over, pos)).toBeNull()
+  })
+
+  it('leaves the input untouched', () => {
+    const input = [...ids]
+    reorderIds(input, 'A', 'D', 'after')
+    expect(input).toEqual(ids)
+  })
+})
diff --git a/src/renderer/src/lib/reorder.ts b/src/renderer/src/lib/reorder.ts
new file mode 100644
index 0000000..20462b1
--- /dev/null
+++ b/src/renderer/src/lib/reorder.ts
@@ -0,0 +1,18 @@
+/** `ids` with `dragId` moved before / after `overId`; null when the order would not change. */
+export function reorderIds(
+  ids: readonly string[],
+  dragId: string,
+  overId: string,
+  pos: 'before' | 'after'
+): string[] | null {
+  const fromIdx = ids.indexOf(dragId)
+  const overIdx = ids.indexOf(overId)
+  if (fromIdx < 0 || overIdx < 0 || fromIdx === overIdx) return null
+  // Taking the dragged id out shifts every later index down by one.
+  const target = fromIdx < overIdx ? overIdx - 1 : overIdx
+  const insertAt = pos === 'after' ? target + 1 : target
+  if (insertAt === fromIdx) return null
+  const next = ids.filter((id) => id !== dragId)
+  next.splice(insertAt, 0, dragId)
+  return next
+}
diff --git a/src/renderer/src/lib/shellParser.test.ts b/src/renderer/src/lib/shellParser.test.ts
index 835c7db..94cfecd 100644
--- a/src/renderer/src/lib/shellParser.test.ts
+++ b/src/renderer/src/lib/shellParser.test.ts
@@ -1,95 +1,160 @@
 import { describe, expect, it } from 'vitest'
-import { parseShellCommand } from './shellParser'
+import { MAX_INSERT_DOCUMENTS, WRITE_METHODS } from '@shared/types'
+import {
+  formatShellCommand,
+  parseShellCommand,
+  shellCollectionAccessor,
+  SHELL_AGGREGATE_CURSOR_METHODS,
+  SHELL_COLLECTION_METHODS,
+  SHELL_CURSOR_METHODS,
+  SHELL_READ_METHODS,
+  writeConfirmation,
+  writeTargetName,
+  type ShellCommand
+} from './shellParser'
+
+const parseOk = (input: string): ShellCommand => {
+  const r = parseShellCommand(input)
+  if (!r.ok) throw new Error(`expected ok for ${input}: ${r.error}`)
+  return r.command
+}
+
+const parseError = (input: string): { error: string; offset: number } => {
+  const r = parseShellCommand(input)
+  if (r.ok) throw new Error(`expected an error for ${input}`)
+  return { error: r.error, offset: r.offset }
+}
 
 describe('parseShellCommand', () => {
   it('parses a bare find()', () => {
-    const r = parseShellCommand('db.users.find()')
-    expect(r.ok).toBe(true)
-    if (!r.ok) return
-    expect(r.coll).toBe('users')
-    expect(r.op).toEqual({
-      kind: 'find',
-      filter: '{}',
-      projection: null,
-      sort: null,
-      skip: null,
-      limit: null
+    expect(parseOk('db.users.find()')).toEqual({
+      coll: 'users',
+      op: { kind: 'find', filter: '{}', projection: null, sort: null, skip: 0, limit: null }
     })
   })
 
   it('parses find with filter and projection', () => {
-    const r = parseShellCommand('db.orders.find({ status: "active" }, { _id: 0, total: 1 })')
-    expect(r.ok).toBe(true)
-    if (!r.ok) return
-    expect(r.op.kind).toBe('find')
-    if (r.op.kind !== 'find') return
-    expect(JSON.parse(r.op.filter)).toEqual({ status: 'active' })
-    expect(r.op.projection && JSON.parse(r.op.projection)).toEqual({ _id: 0, total: 1 })
+    const { op } = parseOk('db.orders.find({ status: "active" }, { _id: 0, total: 1 })')
+    expect(op.kind).toBe('find')
+    if (op.kind !== 'find') return
+    expect(JSON.parse(op.filter)).toEqual({ status: 'active' })
+    expect(op.projection && JSON.parse(op.projection)).toEqual({ _id: 0, total: 1 })
+  })
+
+  it('treats an empty projection as none', () => {
+    const { op } = parseOk('db.orders.find({}, {})')
+    expect(op.kind === 'find' && op.projection).toBeNull()
   })
 
   it('parses find with chained .sort.skip.limit', () => {
-    const r = parseShellCommand('db.users.find({}).sort({ createdAt: -1 }).skip(20).limit(10)')
-    expect(r.ok).toBe(true)
-    if (!r.ok || r.op.kind !== 'find') return
-    expect(JSON.parse(r.op.sort!)).toEqual({ createdAt: -1 })
-    expect(r.op.skip).toBe(20)
-    expect(r.op.limit).toBe(10)
+    const { op } = parseOk('db.users.find({}).sort({ createdAt: -1 }).skip(20).limit(10)')
+    if (op.kind !== 'find') throw new Error('expected find')
+    expect(JSON.parse(op.sort!)).toEqual({ createdAt: -1 })
+    expect(op.skip).toBe(20)
+    expect(op.limit).toBe(10)
+  })
+
+  it('reads .limit(0) as no limit', () => {
+    const { op } = parseOk('db.users.find().limit(0)')
+    expect(op.kind === 'find' && op.limit).toBeNull()
   })
 
-  it('parses aggregate with a pipeline', () => {
-    const r = parseShellCommand(
-      'db.events.aggregate([{ $match: { type: "click" } }, { $count: "n" }])'
+  it('accepts .projection() and the no-op .toArray() / .pretty()', () => {
+    const { op } = parseOk('db.users.find({ a: 1 }).projection({ name: 1 }).pretty().toArray()')
+    if (op.kind !== 'find') throw new Error('expected find')
+    expect(op.projection && JSON.parse(op.projection)).toEqual({ name: 1 })
+  })
+
+  it('parses aggregate with a pipeline and flags reshaping output', () => {
+    const { op } = parseOk(
+      'db.events.aggregate([{ $match: { type: "click" } }, { $count: "n" }]).toArray()'
     )
-    expect(r.ok).toBe(true)
-    if (!r.ok || r.op.kind !== 'aggregate') return
-    expect(JSON.parse(r.op.pipeline)).toEqual([{ $match: { type: 'click' } }, { $count: 'n' }])
+    if (op.kind !== 'aggregate') throw new Error('expected aggregate')
+    expect(JSON.parse(op.pipeline)).toEqual([{ $match: { type: 'click' } }, { $count: 'n' }])
+    expect(op.documentPreserving).toBe(false)
   })
 
-  it('parses findOne and countDocuments', () => {
-    const a = parseShellCommand('db.x.findOne({ id: 1 })')
-    expect(a.ok && a.op.kind === 'findOne').toBe(true)
-    const b = parseShellCommand('db.x.countDocuments({ active: true })')
-    expect(b.ok && b.op.kind === 'countDocuments').toBe(true)
-    const c = parseShellCommand('db.x.count()')
-    expect(c.ok && c.op.kind === 'countDocuments').toBe(true)
+  it('flags $match-only aggregations as document-preserving', () => {
+    const { op } = parseOk('db.events.aggregate([{ $match: { a: 1 } }, { $limit: 5 }])')
+    expect(op.kind === 'aggregate' && op.documentPreserving).toBe(true)
   })
 
-  it('handles ObjectId() and ISODate() inside args', () => {
-    const r = parseShellCommand('db.users.find({ _id: ObjectId("507f1f77bcf86cd799439011") })')
-    expect(r.ok).toBe(true)
-    if (!r.ok || r.op.kind !== 'find') return
-    expect(JSON.parse(r.op.filter)).toEqual({
-      _id: { $oid: '507f1f77bcf86cd799439011' }
+  it('parses findOne with filter and projection', () => {
+    expect(parseOk('db.x.findOne({ id: 1 }, { name: 1 })')).toEqual({
+      coll: 'x',
+      op: { kind: 'findOne', filter: '{"id":1}', projection: '{"name":1}' }
+    })
+    expect(parseOk('db.x.findOne()').op).toEqual({
+      kind: 'findOne',
+      filter: '{}',
+      projection: null
     })
   })
 
-  it('respects parens / braces inside string literals', () => {
-    const r = parseShellCommand('db.x.find({ msg: "a) ) (" })')
-    expect(r.ok).toBe(true)
-    if (!r.ok || r.op.kind !== 'find') return
-    expect(JSON.parse(r.op.filter)).toEqual({ msg: 'a) ) (' })
+  it('parses the count methods with their filters', () => {
+    expect(parseOk('db.x.countDocuments({ active: true })').op).toEqual({
+      kind: 'count',
+      method: 'countDocuments',
+      filter: '{"active":true}'
+    })
+    expect(parseOk('db.x.count()').op).toEqual({ kind: 'count', method: 'count', filter: '{}' })
+    expect(parseOk('db.x.estimatedDocumentCount()').op).toEqual({
+      kind: 'count',
+      method: 'estimatedDocumentCount',
+      filter: null
+    })
   })
 
-  it('rejects unsupported methods', () => {
-    const r = parseShellCommand('db.x.insertOne({})')
-    expect(r.ok).toBe(false)
-    if (r.ok) return
-    expect(r.error).toMatch(/Unsupported method/)
+  it('parses distinct with and without a filter', () => {
+    expect(parseOk("db.x.distinct('a')").op).toEqual({ kind: 'distinct', field: 'a', filter: null })
+    expect(parseOk('db.x.distinct("a.b", { n: { $gt: 1 } })').op).toEqual({
+      kind: 'distinct',
+      field: 'a.b',
+      filter: '{"n":{"$gt":1}}'
+    })
   })
 
-  it('rejects malformed input', () => {
-    expect(parseShellCommand('foo bar').ok).toBe(false)
-    expect(parseShellCommand('db.x.find(').ok).toBe(false)
-    expect(parseShellCommand('db.x.find()garbage').ok).toBe(false)
+  it('handles ObjectId() inside args', () => {
+    const { op } = parseOk('db.users.find({ _id: ObjectId("507f1f77bcf86cd799439011") })')
+    expect(op.kind === 'find' && JSON.parse(op.filter)).toEqual({
+      _id: { $oid: '507f1f77bcf86cd799439011' }
+    })
+  })
+
+  it('respects parens and quotes inside strings and regexes', () => {
+    const a = parseOk('db.x.find({ msg: "a) ) (" })').op
+    expect(a.kind === 'find' && JSON.parse(a.filter)).toEqual({ msg: 'a) ) (' })
+    const b = parseOk('db.x.find({ name: /a)/ })').op
+    expect(b.kind === 'find' && JSON.parse(b.filter)).toEqual({
+      name: { $regularExpression: { pattern: 'a)', options: '' } }
+    })
+    const c = parseOk("db.x.find({ name: /it's/i })").op
+    expect(c.kind === 'find' && JSON.parse(c.filter)).toEqual({
+      name: { $regularExpression: { pattern: "it's", options: 'i' } }
+    })
+  })
+
+  it('ignores leading, inline and trailing comments', () => {
+    const command = parseOk(`// don't panic
+      db.x.find({ /* inline */ a: 1 }) // trailing
+      /* block */`)
+    expect(command).toEqual({
+      coll: 'x',
+      op: { kind: 'find', filter: '{"a":1}', projection: null, sort: null, skip: 0, limit: null }
+    })
   })
 
-  it('rejects skip / limit with non-integer', () => {
-    expect(parseShellCommand('db.x.find().limit(1.5)').ok).toBe(false)
-    expect(parseShellCommand('db.x.find().skip(-1)').ok).toBe(false)
+  it('accepts a trailing semicolon but only one command', () => {
+    expect(parseOk('db.x.find();').coll).toBe('x')
+    const input = 'db.x.find(); db.y.find()'
+    expect(parseError(input)).toEqual({
+      error: 'Only one command per run',
+      offset: input.indexOf('db.y')
+    })
   })
 
   it('accepts whitespace and newlines anywhere', () => {
-    const r = parseShellCommand(`
+    const command = parseOk(`
       db
         .users
         .find({
@@ -97,14 +162,775 @@ describe('parseShellCommand', () => {
         })
         .limit(5)
     `)
-    expect(r.ok).toBe(true)
-    if (!r.ok || r.op.kind !== 'find') return
-    expect(r.coll).toBe('users')
-    expect(r.op.limit).toBe(5)
+    expect(command.coll).toBe('users')
+    expect(command.op.kind === 'find' && command.op.limit).toBe(5)
+  })
+
+  it('addresses collections through getCollection, brackets and dotted names', () => {
+    expect(parseOk("db.getCollection('my-coll').find()").coll).toBe('my-coll')
+    expect(parseOk('db["my-coll"].countDocuments()').coll).toBe('my-coll')
+    expect(parseOk('db["a b"].aggregate([])').coll).toBe('a b')
+    expect(parseOk('db.a.b.find()').coll).toBe('a.b')
+    expect(parseOk('db.getCollection("player-data").find({ a: 1 }).limit(5)')).toEqual({
+      coll: 'player-data',
+      op: { kind: 'find', filter: '{"a":1}', projection: null, sort: null, skip: 0, limit: 5 }
+    })
+  })
+
+  it('rejects empty collection names', () => {
+    expect(parseError("db.getCollection('').find()").error).toBe(
+      'Collection name must not be empty'
+    )
+    expect(parseError('db[""].find()').error).toBe('Collection name must not be empty')
+  })
+
+  it('points names that are not identifiers at getCollection', () => {
+    for (const input of ['db.player-data.find()', 'db.2024_logs.find()', 'db.logs.2024.find()']) {
+      expect(parseError(input).error, input).toMatch(/db\.getCollection\("name"\)/)
+    }
+    expect(parseError('db.player-data.find()').offset).toBe('db.player'.length)
+  })
+
+  it('rejects database-level calls', () => {
+    expect(parseError('db.getSiblingDB("admin").users.find()').error).toBe(
+      "`db.getSiblingDB()` isn't supported; use db.<collection>.<method>(…)"
+    )
+    expect(parseError('db.runCommand({ ping: 1 })').error).toMatch(
+      /`db\.runCommand\(\)` isn't supported/
+    )
+  })
+
+  it('points legacy write methods at their replacements', () => {
+    for (const [method, replacement] of [
+      ['insert', 'insertOne or insertMany'],
+      ['update', 'updateOne, updateMany or replaceOne'],
+      ['remove', 'deleteOne or deleteMany'],
+      ['save', 'insertOne, or replaceOne with upsert: true'],
+      ['findAndModify', 'findOneAndUpdate, findOneAndReplace or findOneAndDelete']
+    ] as const) {
+      expect(parseError(`db.x.${method}({})`), method).toEqual({
+        error: `\`${method}()\` is a legacy method; use ${replacement}`,
+        offset: 'db.x.'.length
+      })
+    }
+  })
+
+  it('points collection administration at the explorer', () => {
+    for (const [method, item] of [
+      ['drop', 'Drop…'],
+      ['createIndex', 'Indexes…'],
+      ['createIndexes', 'Indexes…'],
+      ['dropIndex', 'Indexes…'],
+      ['dropIndexes', 'Indexes…'],
+      ['renameCollection', 'Rename…']
+    ] as const) {
+      expect(parseError(`db.x.${method}()`), method).toEqual({
+        error: `\`${method}()\` isn't supported here; use ${item} in the explorer's collection menu`,
+        offset: 'db.x.'.length
+      })
+    }
+  })
+
+  it('rejects unknown methods and lists the supported ones', () => {
+    expect(parseError('db.x.mapReduce()').error).toBe(
+      `Unsupported method \`mapReduce\`. Supported: ${SHELL_COLLECTION_METHODS.join(', ')}.`
+    )
+    expect(parseError('db.x.toString()').error).toMatch(/^Unsupported method `toString`/)
+  })
+
+  it('runs the read methods and then every write method', () => {
+    expect(SHELL_COLLECTION_METHODS.slice(-WRITE_METHODS.length)).toEqual([...WRITE_METHODS])
+    expect(SHELL_COLLECTION_METHODS.slice(0, 2)).toEqual(['find', 'findOne'])
+  })
+
+  it('lists as read methods exactly the methods that are not write methods', () => {
+    expect(SHELL_READ_METHODS).toEqual([
+      'find',
+      'findOne',
+      'aggregate',
+      'countDocuments',
+      'count',
+      'estimatedDocumentCount',
+      'distinct'
+    ])
+    expect(
+      SHELL_READ_METHODS.filter((m) => (WRITE_METHODS as readonly string[]).includes(m))
+    ).toEqual([])
+  })
+
+  it('rejects unsupported cursor methods at their position', () => {
+    const input = 'db.x.find().hint({ a: 1 })'
+    expect(parseError(input)).toEqual({
+      error: `Unsupported cursor method .hint(). Supported: ${SHELL_CURSOR_METHODS.join(', ')}`,
+      offset: input.indexOf('hint')
+    })
+  })
+
+  it('points a cursor .count() at countDocuments', () => {
+    expect(parseError('db.users.find({ a: 1 }).count()').error).toBe(
+      "Cursor .count() isn't supported; use db.users.countDocuments(filter)"
+    )
+  })
+
+  it('rejects chained calls after non-cursor methods', () => {
+    expect(parseError('db.x.aggregate([]).limit(5)').error).toBe(
+      "`.limit()` can't follow aggregate(…)"
+    )
+    expect(parseError('db.x.findOne({}).sort({ a: 1 })').error).toBe(
+      "`.sort()` can't follow findOne(…)"
+    )
+    expect(parseError('db.x.countDocuments().skip(3)').error).toBe(
+      "`.skip()` can't follow countDocuments(…)"
+    )
+    expect(parseError('db.x.distinct("a").toArray()').error).toBe(
+      "`.toArray()` can't follow distinct(…)"
+    )
+  })
+
+  it('rejects invalid skip and limit values', () => {
+    for (const input of [
+      'db.x.find().limit(1.5)',
+      'db.x.find().limit(-1)',
+      'db.x.find().limit(NumberInt(5))',
+      'db.x.find().limit("5")',
+      'db.x.find().limit()',
+      'db.x.find().skip(-1)'
+    ]) {
+      expect(parseError(input).error, input).toMatch(
+        /expects (a non-negative integer|one argument)/
+      )
+    }
+  })
+
+  it('rejects duplicate chained calls', () => {
+    expect(parseError('db.x.find().limit(1).limit(2)').error).toBe('.limit() specified twice')
+  })
+
+  it('rejects a projection given twice', () => {
+    const input = 'db.x.find({}, { a: 1 }).projection({ b: 1 })'
+    expect(parseError(input)).toEqual({
+      error: 'Projection given twice: pass it to find(…) or .projection(…), not both',
+      offset: input.indexOf('projection(')
+    })
+  })
+
+  it('checks argument counts and types', () => {
+    const tooMany = 'db.x.find({}, {}, {})'
+    expect(parseError(tooMany)).toEqual({
+      error: "Too many arguments; options aren't supported. Use find(filter, projection)",
+      offset: tooMany.lastIndexOf('{}')
+    })
+    expect(parseError('db.x.estimatedDocumentCount(1)').error).toBe(
+      "Too many arguments; options aren't supported. Use estimatedDocumentCount()"
+    )
+    expect(parseError('db.x.aggregate([], { allowDiskUse: true })').error).toBe(
+      "Too many arguments; options aren't supported. Use aggregate(pipeline)"
+    )
+    expect(parseError('db.x.find([])').error).toBe('find() filter must be an object')
+    expect(parseError('db.x.countDocuments(5)').error).toBe(
+      'countDocuments() filter must be an object'
+    )
+    expect(parseError('db.x.distinct(1)').error).toBe('distinct() expects a field name string')
+    expect(parseError('db.x.distinct()').error).toBe('distinct() expects a field name string')
+    expect(parseError('db.x.find().toArray(1)').error).toBe('.toArray() takes no arguments')
+  })
+
+  it('validates aggregate pipelines', () => {
+    const input = 'db.x.aggregate([{ $out: "copy" }, { $match: {} }])'
+    expect(parseError(input)).toEqual({
+      error: 'Stage 1: $out must be the last stage',
+      offset: input.indexOf('[')
+    })
+    expect(parseError('db.x.aggregate({ $match: {} })').error).toBe(
+      'Pipeline must be an array of stages, e.g. [{ $match: { … } }]'
+    )
+    expect(parseError('db.x.aggregate()').error).toBe(
+      'aggregate() expects the pipeline array, e.g. aggregate([{ $match: { … } }])'
+    )
+  })
+
+  it('rejects a change stream pipeline', () => {
+    const input = 'db.x.aggregate([{ $changeStream: {} }])'
+    expect(parseError(input)).toEqual({
+      error: 'Stage 1: $changeStream never ends, so it cannot run here',
+      offset: input.indexOf('[')
+    })
+  })
+
+  it('accepts every aggregate cursor method after aggregate(…)', () => {
+    for (const method of SHELL_AGGREGATE_CURSOR_METHODS) {
+      expect(parseOk(`db.x.aggregate([]).${method}()`).op.kind, method).toBe('aggregate')
+    }
+  })
+
+  it('rejects malformed input', () => {
+    expect(parseError('foo bar').error).toBe('Expected `db.<collection>.<method>(…)`')
+    expect(parseError('').error).toBe('Expected `db.<collection>.<method>(…)`')
+    expect(parseError('db.users').error).toBe('Expected `db.<collection>.<method>(…)`')
+    expect(parseShellCommand('db.x.find(').ok).toBe(false)
+    expect(parseShellCommand('db.x.find()garbage').ok).toBe(false)
+    expect(parseShellCommand('db.x.find({}, {}').ok).toBe(false)
+  })
+
+  it('reports tokenizer errors at the offending character', () => {
+    expect(parseError('db.x.find({ a: # })').offset).toBe('db.x.find({ a: '.length)
+  })
+})
+
+describe('parseShellCommand write commands', () => {
+  const writes = { db: null, coll: 'users' }
+
+  it('parses insertOne with and without options', () => {
+    expect(parseOk('db.users.insertOne({ name: "ada", n: 5.0 })')).toEqual({
+      coll: 'users',
+      op: {
+        kind: 'write',
+        write: { method: 'insertOne', document: '{"name":"ada","n":{"$numberDouble":"5.0"}}' },
+        writes
+      }
+    })
+    expect(parseOk('db.users.insertOne({}, { bypassDocumentValidation: true })').op).toEqual({
+      kind: 'write',
+      write: {
+        method: 'insertOne',
+        document: '{}',
+        options: '{"bypassDocumentValidation":true}'
+      },
+      writes
+    })
+  })
+
+  it('keeps shell helper values as EJSON', () => {
+    const { op } = parseOk(
+      'db.users.insertOne({ _id: ObjectId("507f1f77bcf86cd799439011"), at: ISODate("2024-01-01T00:00:00.000Z"), n: NumberLong("5") })'
+    )
+    expect(op.kind === 'write' && op.write).toEqual({
+      method: 'insertOne',
+      document:
+        '{"_id":{"$oid":"507f1f77bcf86cd799439011"},"at":{"$date":"2024-01-01T00:00:00.000Z"},"n":{"$numberLong":"5"}}'
+    })
+  })
+
+  it('parses insertMany', () => {
+    expect(parseOk('db.users.insertMany([{ a: 1 }, { a: 2 }], { ordered: false })').op).toEqual({
+      kind: 'write',
+      write: {
+        method: 'insertMany',
+        documents: ['{"a":1}', '{"a":2}'],
+        options: '{"ordered":false}'
+      },
+      writes
+    })
+  })
+
+  it('parses updateOne, updateMany and findOneAndUpdate', () => {
+    expect(
+      parseOk('db.users.updateOne({ _id: 1 }, { $set: { a: 1 } }, { upsert: true })').op
+    ).toEqual({
+      kind: 'write',
+      write: {
+        method: 'updateOne',
+        filter: '{"_id":1}',
+        update: '{"$set":{"a":1}}',
+        options: '{"upsert":true}'
+      },
+      writes
+    })
+    expect(
+      parseOk('db.users.updateMany({}, [{ $set: { total: { $add: ["$a", "$b"] } } }])').op
+    ).toEqual({
+      kind: 'write',
+      write: {
+        method: 'updateMany',
+        filter: '{}',
+        update: '[{"$set":{"total":{"$add":["$a","$b"]}}}]'
+      },
+      writes
+    })
+    expect(
+      parseOk(
+        'db.users.findOneAndUpdate({ _id: 1 }, { $inc: { n: 1 } }, { returnNewDocument: true, projection: { n: 1 } })'
+      ).op
+    ).toEqual({
+      kind: 'write',
+      write: {
+        method: 'findOneAndUpdate',
+        filter: '{"_id":1}',
+        update: '{"$inc":{"n":1}}',
+        options: '{"returnNewDocument":true,"projection":{"n":1}}'
+      },
+      writes
+    })
+  })
+
+  it('parses arrayFilters options', () => {
+    const { op } = parseOk(
+      'db.users.updateMany({}, { $set: { "items.$[e].ok": true } }, { arrayFilters: [{ "e.n": { $gt: 1 } }] })'
+    )
+    expect(op.kind === 'write' && op.write).toEqual({
+      method: 'updateMany',
+      filter: '{}',
+      update: '{"$set":{"items.$[e].ok":true}}',
+      options: '{"arrayFilters":[{"e.n":{"$gt":1}}]}'
+    })
+  })
+
+  it('parses replaceOne and findOneAndReplace', () => {
+    expect(parseOk('db.users.replaceOne({ _id: 1 }, { name: "x" }, { upsert: true })').op).toEqual({
+      kind: 'write',
+      write: {
+        method: 'replaceOne',
+        filter: '{"_id":1}',
+        replacement: '{"name":"x"}',
+        options: '{"upsert":true}'
+      },
+      writes
+    })
+    expect(
+      parseOk(
+        'db.users.findOneAndReplace({ _id: 1 }, { a: 1 }, { returnDocument: "after", sort: { a: 1 } })'
+      ).op
+    ).toEqual({
+      kind: 'write',
+      write: {
+        method: 'findOneAndReplace',
+        filter: '{"_id":1}',
+        replacement: '{"a":1}',
+        options: '{"returnDocument":"after","sort":{"a":1}}'
+      },
+      writes
+    })
+  })
+
+  it('parses deleteOne, deleteMany and findOneAndDelete', () => {
+    expect(parseOk('db.users.deleteOne({ a: 1 })').op).toEqual({
+      kind: 'write',
+      write: { method: 'deleteOne', filter: '{"a":1}' },
+      writes
+    })
+    expect(parseOk('db.users.deleteMany({ status: "old" }, { hint: "status_1" })').op).toEqual({
+      kind: 'write',
+      write: { method: 'deleteMany', filter: '{"status":"old"}', options: '{"hint":"status_1"}' },
+      writes
+    })
+    expect(parseOk('db.users.findOneAndDelete({ a: 1 }, { sort: { at: 1 } })').op).toEqual({
+      kind: 'write',
+      write: { method: 'findOneAndDelete', filter: '{"a":1}', options: '{"sort":{"at":1}}' },
+      writes
+    })
+  })
+
+  it('parses bulkWrite', () => {
+    const { op } = parseOk(`db.users.bulkWrite([
+      { insertOne: { document: { a: 1 } } },
+      { updateMany: { filter: {}, update: { $set: { b: 1 } }, upsert: true } },
+      { deleteOne: { filter: { a: 1 } } }
+    ], { ordered: false })`)
+    expect(op).toEqual({
+      kind: 'write',
+      write: {
+        method: 'bulkWrite',
+        operations:
+          '[{"insertOne":{"document":{"a":1}}},{"updateMany":{"filter":{},"update":{"$set":{"b":1}},"upsert":true}},{"deleteOne":{"filter":{"a":1}}}]',
+        options: '{"ordered":false}'
+      },
+      writes
+    })
+  })
+
+  it('writes to the collection the command addresses', () => {
+    expect(parseOk('db.getCollection("player-data").deleteOne({ a: 1 })')).toEqual({
+      coll: 'player-data',
+      op: {
+        kind: 'write',
+        write: { method: 'deleteOne', filter: '{"a":1}' },
+        writes: { db: null, coll: 'player-data' }
+      }
+    })
+  })
+
+  it('reports a missing argument at the method', () => {
+    for (const [input, error] of [
+      ['db.x.insertOne()', 'Missing document. Use insertOne(document, options)'],
+      ['db.x.insertMany()', 'Missing documents. Use insertMany(documents, options)'],
+      ['db.x.updateOne({ a: 1 })', 'Missing update. Use updateOne(filter, update, options)'],
+      ['db.x.replaceOne({})', 'Missing replacement. Use replaceOne(filter, replacement, options)'],
+      ['db.x.deleteMany()', 'Missing filter. Use deleteMany(filter, options)'],
+      ['db.x.findOneAndDelete()', 'Missing filter. Use findOneAndDelete(filter, options)'],
+      ['db.x.bulkWrite()', 'Missing operations. Use bulkWrite(operations, options)']
+    ] as const) {
+      expect(parseError(input), input).toEqual({ error, offset: 'db.x.'.length })
+    }
+  })
+
+  it('reports surplus arguments at the first one', () => {
+    const input = 'db.x.deleteOne({}, {}, {})'
+    expect(parseError(input)).toEqual({
+      error: 'Too many arguments. Use deleteOne(filter, options)',
+      offset: input.lastIndexOf('{}')
+    })
+  })
+
+  it('reports invalid documents at their argument', () => {
+    for (const [input, arg, error] of [
+      ['db.x.insertOne([{ a: 1 }])', '[', 'Each inserted document must be an object'],
+      ['db.x.insertMany({ a: 1 })', '{', 'insertMany() expects a non-empty array of documents'],
+      ['db.x.insertMany([])', '[', 'insertMany() expects a non-empty array of documents'],
+      ['db.x.insertMany([{}, 5])', '[', 'Each inserted document must be an object'],
+      ['db.x.deleteOne("a")', '"', 'deleteOne() filter must be an object'],
+      ['db.x.updateOne([], { $set: { a: 1 } })', '[', 'updateOne() filter must be an object']
+    ] as const) {
+      expect(parseError(input), input).toEqual({ error, offset: input.indexOf(arg) })
+    }
+  })
+
+  it('limits insertMany to one request worth of documents', () => {
+    const docs = (n: number): string => `db.x.insertMany([${Array(n).fill('{}').join(',')}])`
+    expect(parseShellCommand(docs(MAX_INSERT_DOCUMENTS)).ok).toBe(true)
+    expect(parseError(docs(MAX_INSERT_DOCUMENTS + 1))).toEqual({
+      error: 'insertMany() takes at most 10,000 documents per run',
+      offset: docs(1).indexOf('[')
+    })
+  })
+
+  it('checks updates and replacements with the shared rules', () => {
+    for (const [input, error] of [
+      [
+        'db.x.updateOne({ a: 1 }, { a: 2 })',
+        'The update needs operators such as $set; replaceOne replaces whole documents'
+      ],
+      ['db.x.updateMany({}, {})', 'The update needs at least one operator such as $set'],
+      [
+        'db.x.findOneAndUpdate({}, [{ $match: {} }])',
+        'Update pipeline stage 1 must be one of $addFields, $set, $project, $unset, $replaceRoot, $replaceWith'
+      ],
+      [
+        'db.x.replaceOne({}, { $set: { a: 1 } })',
+        "A replacement can't contain update operators; updateOne applies operators"
+      ],
+      ['db.x.findOneAndReplace({}, [])', 'The replacement must be a document']
+    ] as const) {
+      expect(parseError(input), input).toEqual({ error, offset: input.indexOf(', ') + 2 })
+    }
+  })
+
+  it('checks bulkWrite operations with the shared rules', () => {
+    const input = 'db.x.bulkWrite([{ updateOne: { filter: {} } }])'
+    expect(parseError(input)).toEqual({
+      error: 'bulkWrite() operation 1: updateOne needs "update"',
+      offset: input.indexOf('[')
+    })
+    expect(parseError('db.x.bulkWrite([])').error).toBe(
+      'bulkWrite() expects a non-empty array of operations'
+    )
+  })
+
+  it('checks options at their argument', () => {
+    for (const [input, options, error] of [
+      [
+        'db.x.insertOne({}, { ordered: true })',
+        '{ ordered',
+        'insertOne() options: unknown option "ordered"; supported: bypassDocumentValidation'
+      ],
+      [
+        'db.x.updateOne({}, { $set: { a: 1 } }, { upsert: "yes" })',
+        '{ upsert',
+        'updateOne() options: "upsert" must be true or false'
+      ],
+      ['db.x.deleteMany({}, true)', 'true', 'deleteMany() options must be an object'],
+      [
+        'db.x.findOneAndUpdate({}, { $set: { a: 1 } }, { returnDocument: "new" })',
+        '{ returnDocument',
+        'findOneAndUpdate() options: "returnDocument" must be "before" or "after"'
+      ],
+      [
+        'db.x.findOneAndReplace({}, {}, { returnDocument: "after", returnNewDocument: true })',
+        '{ returnDocument',
+        'findOneAndReplace() options: use returnDocument or returnNewDocument, not both'
+      ],
+      [
+        'db.x.findOneAndDelete({}, { returnDocument: "after" })',
+        '{ returnDocument',
+        'findOneAndDelete() options: unknown option "returnDocument"; supported: collation, hint, let, projection, sort'
+      ]
+    ] as const) {
+      expect(parseError(input), input).toEqual({ error, offset: input.indexOf(options) })
+    }
+  })
+
+  it('checks arguments in source order', () => {
+    const input = 'db.x.updateOne({}, { a: 1 }, { upsert: "yes" })'
+    expect(parseError(input).offset).toBe(input.indexOf('{ a'))
+  })
+
+  it('rejects chained calls after a write', () => {
+    const input = 'db.x.insertOne({}).toArray()'
+    expect(parseError(input)).toEqual({
+      error: "`.toArray()` can't follow insertOne(…)",
+      offset: input.indexOf('toArray')
+    })
+  })
+
+  it('parses an aggregation ending in $out as a write to that collection', () => {
+    expect(parseOk('db.users.aggregate([{ $match: { a: 1 } }, { $out: "archive" }])')).toEqual({
+      coll: 'users',
+      op: {
+        kind: 'write',
+        write: { method: 'aggregate', pipeline: '[{"$match":{"a":1}},{"$out":"archive"}]' },
+        writes: { db: null, coll: 'archive' }
+      }
+    })
+  })
+
+  it('reads the output collection of every $out and $merge form', () => {
+    for (const [stage, target] of [
+      ['{ $out: { db: "reports", coll: "daily" } }', { db: 'reports', coll: 'daily' }],
+      ['{ $merge: "totals" }', { db: null, coll: 'totals' }],
+      ['{ $merge: { into: "totals", on: "_id" } }', { db: null, coll: 'totals' }],
+      [
+        '{ $merge: { into: { db: "reports", coll: "totals" } } }',
+        { db: 'reports', coll: 'totals' }
+      ],
+      ['{ $merge: { into: { coll: "totals" } } }', { db: null, coll: 'totals' }]
+    ] as const) {
+      const { op } = parseOk(`db.users.aggregate([${stage}])`)
+      expect(op.kind === 'write' && op.writes, stage).toEqual(target)
+    }
+  })
+
+  it('allows the aggregate cursor methods after an aggregation that writes', () => {
+    expect(parseOk('db.users.aggregate([{ $out: "copy" }]).toArray()').op.kind).toBe('write')
+  })
+
+  it('rejects a $out or $merge without an output collection', () => {
+    for (const [stage, error] of [
+      ['{ $out: 5 }', 'Stage 2: $out must name the output collection, e.g. { $out: "name" }'],
+      ['{ $out: "" }', 'Stage 2: $out must name the output collection, e.g. { $out: "name" }'],
+      [
+        '{ $out: { db: "reports" } }',
+        'Stage 2: $out must name the output collection, e.g. { $out: "name" }'
+      ],
+      [
+        '{ $merge: { on: "_id" } }',
+        'Stage 2: $merge must name the output collection, e.g. { $merge: { into: "name" } }'
+      ],
+      [
+        '{ $merge: { into: { db: 5, coll: "t" } } }',
+        'Stage 2: $merge must name the output collection, e.g. { $merge: { into: "name" } }'
+      ]
+    ] as const) {
+      const input = `db.users.aggregate([{ $match: {} }, ${stage}])`
+      expect(parseError(input), stage).toEqual({ error, offset: input.indexOf('[') })
+    }
+  })
+})
+
+describe('writeConfirmation', () => {
+  const confirmation = (input: string): string | null => writeConfirmation(parseOk(input), 'app')
+
+  it('asks before updateMany or deleteMany with an empty filter', () => {
+    expect(confirmation('db.users.updateMany({}, { $set: { a: 1 } })')).toBe(
+      'updateMany with an empty filter updates every document in users.'
+    )
+    expect(confirmation('db.getCollection("player-data").deleteMany({})')).toBe(
+      'deleteMany with an empty filter deletes every document in player-data.'
+    )
+  })
+
+  it('runs filtered and single-document writes right away', () => {
+    for (const input of [
+      'db.users.updateMany({ a: 1 }, { $set: { a: 2 } })',
+      'db.users.deleteMany({ a: 1 })',
+      'db.users.updateOne({}, { $set: { a: 1 } })',
+      'db.users.deleteOne({})',
+      'db.users.findOneAndDelete({})',
+      'db.users.replaceOne({}, { a: 1 })',
+      'db.users.insertMany([{ a: 1 }])',
+      'db.users.aggregate([{ $merge: "totals" }])'
+    ]) {
+      expect(confirmation(input), input).toBeNull()
+    }
+  })
+
+  it('asks before a bulkWrite with an unfiltered updateMany or deleteMany', () => {
+    expect(
+      confirmation(
+        'db.users.bulkWrite([{ deleteMany: { filter: { a: 1 } } }, { deleteMany: { filter: {} } }])'
+      )
+    ).toBe(
+      'bulkWrite operation 2: deleteMany with an empty filter deletes every document in users.'
+    )
+    expect(
+      confirmation(
+        'db.users.bulkWrite([{ updateMany: { filter: {}, update: { $set: { a: 1 } } } }])'
+      )
+    ).toBe(
+      'bulkWrite operation 1: updateMany with an empty filter updates every document in users.'
+    )
+    expect(
+      confirmation(
+        'db.users.bulkWrite([{ deleteOne: { filter: {} } }, { updateMany: { filter: { a: 1 }, update: { $set: { a: 2 } } } }])'
+      )
+    ).toBeNull()
+  })
+
+  it('asks before $out replaces a collection', () => {
+    expect(confirmation('db.users.aggregate([{ $match: {} }, { $out: "archive" }])')).toBe(
+      '$out replaces the collection archive with the pipeline output.'
+    )
+    expect(confirmation('db.users.aggregate([{ $out: { db: "reports", coll: "daily" } }])')).toBe(
+      '$out replaces the collection reports.daily with the pipeline output.'
+    )
+    expect(confirmation('db.users.aggregate([{ $out: { db: "app", coll: "daily" } }])')).toBe(
+      '$out replaces the collection daily with the pipeline output.'
+    )
+  })
+
+  it('never asks for reads', () => {
+    expect(confirmation('db.users.find({})')).toBeNull()
+    expect(confirmation('db.users.aggregate([{ $match: {} }])')).toBeNull()
+  })
+})
+
+describe('writeTargetName', () => {
+  it('names the database only when it is not the tab database', () => {
+    expect(writeTargetName({ db: null, coll: 'daily' }, 'app')).toBe('daily')
+    expect(writeTargetName({ db: 'app', coll: 'daily' }, 'app')).toBe('daily')
+    expect(writeTargetName({ db: 'reports', coll: 'daily' }, 'app')).toBe('reports.daily')
+  })
+})
+
+describe('shellCollectionAccessor', () => {
+  it('uses dot access for identifier paths and getCollection otherwise', () => {
+    expect(shellCollectionAccessor('users')).toBe('db.users')
+    expect(shellCollectionAccessor('system.profile')).toBe('db.system.profile')
+    expect(shellCollectionAccessor('$cmd')).toBe('db.$cmd')
+    expect(shellCollectionAccessor('player-data')).toBe('db.getCollection("player-data")')
+    expect(shellCollectionAccessor('2024_logs')).toBe('db.getCollection("2024_logs")')
+    expect(shellCollectionAccessor('a..b')).toBe('db.getCollection("a..b")')
+  })
+
+  it('produces accessors the parser reads back', () => {
+    for (const coll of ['users', 'system.profile', 'player-data', 'a b', 'getCollection', 'x"y']) {
+      expect(parseOk(`${shellCollectionAccessor(coll)}.find()`).coll, coll).toBe(coll)
+    }
+  })
+})
+
+describe('formatShellCommand', () => {
+  const options = { timezone: 'UTC', uuidEncoding: 'default' as const, indent: 2, printWidth: 80 }
+
+  it('puts each chained call on its own line', () => {
+    expect(
+      formatShellCommand('db.users.find({a:1}).sort({createdAt:-1}).limit(10);', options)
+    ).toBe('db.users.find({ a: 1 })\n  .sort({ createdAt: -1 })\n  .limit(10)')
+  })
+
+  it('hugs a pipeline that does not fit on the first line', () => {
+    expect(
+      formatShellCommand(
+        'db.orders.aggregate([{$match:{status:"A"}},{$group:{_id:"$cust",n:{$sum:1}}}])',
+        options
+      )
+    ).toBe(
+      [
+        'db.orders.aggregate([',
+        '  { $match: { status: "A" } },',
+        '  { $group: { _id: "$cust", n: { $sum: 1 } } }',
+        '])'
+      ].join('\n')
+    )
+  })
+
+  it('indents a broken argument of a chained call', () => {
+    const long = 'x'.repeat(70)
+    expect(formatShellCommand(`db.c.find().sort({ ${long}: 1, b: -1 })`, options)).toBe(
+      ['db.c.find()', '  .sort({', `    ${long}: 1,`, '    b: -1', '  })'].join('\n')
+    )
+  })
+
+  it('keeps the accessor style', () => {
+    expect(formatShellCommand("db['my-coll'].find( )", options)).toBe('db["my-coll"].find()')
+    expect(formatShellCommand("db.getCollection('x').countDocuments()", options)).toBe(
+      'db.getCollection("x").countDocuments()'
+    )
+    expect(formatShellCommand('db . a . b . find ( )', options)).toBe('db.a.b.find()')
+  })
+
+  it('preserves shell helpers and drops comments', () => {
+    const input = `db.c.find({ // who
+      _id: ObjectId("507f1f77bcf86cd799439011"), at: ISODate("2024-01-01T00:00:00.000Z"),
+      n: NumberLong("5"), d: 5.0, re: /^a/i, u: JUUID("550e8400-e29b-41d4-a716-446655440000")
+    })`
+    expect(formatShellCommand(input, { ...options, uuidEncoding: 'java' })).toBe(
+      [
+        'db.c.find({',
+        '  _id: ObjectId("507f1f77bcf86cd799439011"),',
+        '  at: ISODate("2024-01-01T00:00:00.000Z"),',
+        '  n: NumberLong("5"),',
+        '  d: 5.0,',
+        '  re: /^a/i,',
+        '  u: JUUID("550e8400-e29b-41d4-a716-446655440000")',
+        '})'
+      ].join('\n')
+    )
+  })
+
+  it('round-trips to the same command', () => {
+    for (const input of [
+      'db.users.find({ a: { $in: [1, 2.5, 3.0] }, b: /x\\/y/ }, { a: 1 }).sort({ b: -1 }).skip(5).limit(0)',
+      'db["a b"].aggregate([{ $match: { at: { $gte: ISODate("2024-01-01T00:00:00.000Z") } } }, { $group: { _id: "$k", n: { $sum: 1 } } }]).toArray()',
+      'db.getCollection("x").distinct("tags", { n: NumberDecimal("1.5") })',
+      'db.c.findOne({ u: UUID("550e8400-e29b-41d4-a716-446655440000"), t: Timestamp(1700000000, 7) })'
+    ]) {
+      const formatted = formatShellCommand(input, options)
+      expect(formatted, input).not.toBeNull()
+      expect(parseShellCommand(formatted!), input).toEqual(parseShellCommand(input))
+    }
+  })
+
+  it('formats write commands with their options', () => {
+    expect(formatShellCommand('db.x.deleteMany({a:1},{hint:"a_1"})', options)).toBe(
+      'db.x.deleteMany({ a: 1 }, { hint: "a_1" })'
+    )
+    expect(
+      formatShellCommand(
+        'db.users.updateMany({status:"old"},{$set:{archived:true,at:ISODate("2024-01-01T00:00:00.000Z")}},{upsert:true})',
+        options
+      )
+    ).toBe(
+      [
+        'db.users.updateMany({ status: "old" }, {',
+        '  $set: { archived: true, at: ISODate("2024-01-01T00:00:00.000Z") }',
+        '}, { upsert: true })'
+      ].join('\n')
+    )
+  })
+
+  it('round-trips write commands', () => {
+    for (const input of [
+      'db.x.insertOne({ _id: ObjectId("507f1f77bcf86cd799439011"), n: NumberLong("5"), d: 1.0 }, { bypassDocumentValidation: true })',
+      'db.x.insertMany([{ a: 1 }, { a: 2.5 }], { ordered: false })',
+      'db.x.updateMany({}, [{ $set: { total: { $add: ["$a", "$b"] } } }])',
+      'db["a b"].findOneAndUpdate({ _id: 1 }, { $inc: { n: 1 } }, { returnDocument: "after", projection: { n: 1 } })',
+      'db.x.replaceOne({ _id: 1 }, { a: /x/i }, { upsert: true })',
+      'db.x.bulkWrite([{ insertOne: { document: { a: 1 } } }, { deleteMany: { filter: { a: { $lt: 0 } } } }], { ordered: false })',
+      'db.x.aggregate([{ $match: { a: 1 } }, { $merge: { into: { db: "r", coll: "t" }, on: "_id" } }])'
+    ]) {
+      const formatted = formatShellCommand(input, options)
+      expect(formatted, input).not.toBeNull()
+      expect(parseShellCommand(formatted!), input).toEqual(parseShellCommand(input))
+    }
+  })
+
+  it('formats syntactically valid commands the shell would not run', () => {
+    expect(formatShellCommand('db.x.remove({a:1})', options)).toBe('db.x.remove({ a: 1 })')
   })
 
-  it('rejects more than 2 args to find', () => {
-    const r = parseShellCommand('db.x.find({}, {}, {})')
-    expect(r.ok).toBe(false)
+  it('returns null for blank or invalid input', () => {
+    expect(formatShellCommand('', options)).toBeNull()
+    expect(formatShellCommand('   ', options)).toBeNull()
+    expect(formatShellCommand('db.x.find(', options)).toBeNull()
+    expect(formatShellCommand('{ a: 1 }', options)).toBeNull()
   })
 })
diff --git a/src/renderer/src/lib/shellParser.ts b/src/renderer/src/lib/shellParser.ts
index e272d3d..ef2e179 100644
--- a/src/renderer/src/lib/shellParser.ts
+++ b/src/renderer/src/lib/shellParser.ts
@@ -1,302 +1,652 @@
-import { parseMongoQuery } from './mongoQueryLang'
+import { checkPipeline } from './aggregationPipeline'
+import { ParseError, Parser, tokenize, type PunctValue, type Token } from './mongoQueryLang'
+import { serializeMongoValue, type SerializeOptions } from './mongoQuerySerialize'
+import { finalWriteStage } from '@shared/pipeline'
+import { MAX_INSERT_DOCUMENTS, WRITE_METHODS, type WriteMethod, type WriteOp } from '@shared/types'
+import {
+  WRITE_ARGUMENTS,
+  bulkWriteError,
+  filterError,
+  insertDocumentError,
+  isDocument,
+  replacementError,
+  updateError,
+  writeOptionsError
+} from '@shared/writeOps'
 
 /**
- * Parses a small subset of mongosh syntax into a structured request the
- * renderer can dispatch through the existing `query.find` /
- * `query.aggregate` IPC channels.
+ * Parses the subset of mongosh that Shell mode runs, reads and writes:
  *
- * Supported shapes (whitespace and newlines anywhere are fine):
+ *   db.<coll>.find(filter?, projection?)[.sort(s)][.skip(n)][.limit(n)][.projection(p)][.toArray()][.pretty()]
+ *   db.<coll>.findOne(filter?, projection?)
+ *   db.<coll>.aggregate(pipeline)[.toArray()]          (a final $out / $merge makes it a write)
+ *   db.<coll>.countDocuments(filter?)  /  count(filter?)  /  estimatedDocumentCount()
+ *   db.<coll>.distinct(field, filter?)
+ *   db.<coll>.insertOne(document, options?)  /  insertMany(documents, options?)
+ *   db.<coll>.updateOne / updateMany / findOneAndUpdate(filter, update, options?)
+ *   db.<coll>.replaceOne / findOneAndReplace(filter, replacement, options?)
+ *   db.<coll>.deleteOne / deleteMany / findOneAndDelete(filter, options?)
+ *   db.<coll>.bulkWrite(operations, options?)
  *
- *   db.coll.find(<filter>?, <projection>?)[.sort(<sort>)][.skip(<n>)][.limit(<n>)]
- *   db.coll.findOne(<filter>?)
- *   db.coll.countDocuments(<filter>?)
- *   db.coll.count(<filter>?)
- *   db.coll.aggregate(<pipeline>)
- *
- * The collection name in the source is informational only — callers know
- * which tab they're in and pass that explicitly to the API. Mismatch
- * surfaces as a "wrong collection" parse error so the user notices.
+ * `<coll>` is any collection of the tab's database, written `db.name`, `db.a.b`,
+ * `db["name"]` or `db.getCollection("name")`. Comments and a trailing `;` are allowed.
+ * Write arguments are checked with the rules of `@shared/writeOps`, which main applies too.
  */
 
+/** Collection methods Shell mode runs that read; `aggregate` writes only when it ends in $out / $merge. */
+export const SHELL_READ_METHODS = [
+  'find',
+  'findOne',
+  'aggregate',
+  'countDocuments',
+  'count',
+  'estimatedDocumentCount',
+  'distinct'
+] as const
+/** Collection methods Shell mode runs, reads then writes; also the list error messages and completion offer. */
+export const SHELL_COLLECTION_METHODS = [...SHELL_READ_METHODS, ...WRITE_METHODS] as const
+/** Calls that may follow `find(…)`. */
+export const SHELL_CURSOR_METHODS = [
+  'sort',
+  'skip',
+  'limit',
+  'projection',
+  'toArray',
+  'pretty'
+] as const
+/** Calls that may follow `aggregate(…)`. */
+export const SHELL_AGGREGATE_CURSOR_METHODS = ['toArray', 'pretty'] as const
+
+export type ShellCountMethod = 'countDocuments' | 'count' | 'estimatedDocumentCount'
+
+/** A command the shell can run; filters, projections, sorts, pipelines and write arguments are EJSON strings. */
 export type ShellOp =
   | {
       kind: 'find'
       filter: string
+      /** null when absent or empty: whole documents. */
       projection: string | null
       sort: string | null
-      skip: number | null
+      skip: number
+      /** null when absent or `.limit(0)`: no limit. */
       limit: number | null
     }
-  | { kind: 'findOne'; filter: string }
-  | { kind: 'countDocuments'; filter: string }
-  | { kind: 'aggregate'; pipeline: string }
+  | { kind: 'findOne'; filter: string; projection: string | null }
+  | { kind: 'aggregate'; pipeline: string; documentPreserving: boolean }
+  | {
+      kind: 'count'
+      method: ShellCountMethod
+      /** null only for estimatedDocumentCount. */
+      filter: string | null
+    }
+  | { kind: 'distinct'; field: string; filter: string | null }
+  | {
+      kind: 'write'
+      write: WriteOp
+      /** Collection the write changes: the command's own, or the $out / $merge output (db null = same database). */
+      writes: { db: string | null; coll: string }
+    }
+
+export type ShellCommand = { coll: string; op: ShellOp }
 
 export type ShellParseResult =
-  { ok: true; coll: string; op: ShellOp } | { ok: false; error: string }
+  { ok: true; command: ShellCommand } | { ok: false; error: string; offset: number }
 
-const HEAD_RE = /^\s*db\s*\.\s*([A-Za-z_$][\w.$]*)\s*\.\s*([A-Za-z_$][\w$]*)\s*\(/
+type CollectionMethod = (typeof SHELL_COLLECTION_METHODS)[number]
+type CursorMethod = (typeof SHELL_CURSOR_METHODS)[number]
+type Arg = { value: unknown; offset: number }
+type Call = { name: string; offset: number; args: Arg[] }
+type Target = { name: string; accessor: 'dot' | 'bracket' | 'getCollection' }
+type ShellAst = { target: Target; method: Call; chain: Call[] }
 
+const EXPECTED_COMMAND = 'Expected `db.<collection>.<method>(…)`'
+const NON_IDENTIFIER_NAME =
+  'Collection names that aren\'t plain identifiers need db.getCollection("name") or db["name"]'
+const EMPTY_NAME = 'Collection name must not be empty'
+
+// Maps, not object literals: a method name like `toString` must not hit the prototype.
+const LEGACY_METHODS: ReadonlyMap<string, string> = new Map([
+  ['insert', 'insertOne or insertMany'],
+  ['update', 'updateOne, updateMany or replaceOne'],
+  ['remove', 'deleteOne or deleteMany'],
+  ['save', 'insertOne, or replaceOne with upsert: true'],
+  ['findAndModify', 'findOneAndUpdate, findOneAndReplace or findOneAndDelete']
+])
+const ADMIN_METHODS: ReadonlyMap<string, string> = new Map([
+  ['drop', 'Drop…'],
+  ['createIndex', 'Indexes…'],
+  ['createIndexes', 'Indexes…'],
+  ['dropIndex', 'Indexes…'],
+  ['dropIndexes', 'Indexes…'],
+  ['renameCollection', 'Rename…']
+])
+
+// Matches the source up to a tokenizer stop that is still inside `db.<a>.<b>`.
+const DOTTED_HEAD_RE = /^\s*db(?:\s*\.\s*[A-Za-z_$][\w$]*)+$/
+const DOTTED_IDENTIFIER_RE = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/
+
+/** Parses and checks one command; an error's offset points at the offending token. */
 export function parseShellCommand(input: string): ShellParseResult {
-  const head = HEAD_RE.exec(input)
-  if (!head) {
-    return {
-      ok: false,
-      error: 'Expected `db.<collection>.<method>(…)`'
+  try {
+    return { ok: true, command: compileShellAst(parseShellAst(input)) }
+  } catch (e) {
+    if (e instanceof ParseError) return { ok: false, error: e.message, offset: e.offset }
+    return { ok: false, error: e instanceof Error ? e.message : String(e), offset: 0 }
+  }
+}
+
+/**
+ * Why a write must be confirmed before it runs: it changes a whole collection; null otherwise.
+ * @param db The tab's database; see `writeTargetName`.
+ */
+export function writeConfirmation(command: ShellCommand, db: string): string | null {
+  const { op } = command
+  if (op.kind !== 'write') return null
+  const { write, writes } = op
+  const target = writeTargetName(writes, db)
+  switch (write.method) {
+    case 'updateMany':
+    case 'deleteMany':
+      return isEmptyDocument(JSON.parse(write.filter))
+        ? `${everyDocument(write.method, target)}.`
+        : null
+    case 'bulkWrite': {
+      const operations = JSON.parse(write.operations) as Record<string, { filter?: unknown }>[]
+      for (const [index, operation] of operations.entries()) {
+        for (const [name, body] of Object.entries(operation)) {
+          if ((name === 'updateMany' || name === 'deleteMany') && isEmptyDocument(body.filter)) {
+            return `bulkWrite operation ${index + 1}: ${everyDocument(name, target)}.`
+          }
+        }
+      }
+      return null
     }
+    case 'aggregate':
+      return finalWriteStage(JSON.parse(write.pipeline) as unknown[]) === '$out'
+        ? `$out replaces the collection ${target} with the pipeline output.`
+        : null
+    default:
+      return null
   }
-  const coll = head[1]!
-  const method = head[2]!
+}
+
+/** The collection a write changes, prefixed with its database only when that isn't `db`, the tab's. */
+export function writeTargetName(writes: { db: string | null; coll: string }, db: string): string {
+  return writes.db === null || writes.db === db ? writes.coll : `${writes.db}.${writes.coll}`
+}
 
-  const argsStart = head.index + head[0].length
-  const argsEnd = matchClosingParen(input, argsStart - 1)
-  if (argsEnd < 0) {
-    return { ok: false, error: 'Missing closing `)` for method call' }
+/** Re-prints a syntactically valid command; null on syntax errors. Comments are dropped. */
+export function formatShellCommand(input: string, options: SerializeOptions): string | null {
+  let ast: ShellAst
+  try {
+    ast = parseShellAst(input)
+  } catch (e) {
+    if (e instanceof ParseError) return null
+    throw e
   }
-  const argsSrc = input.slice(argsStart, argsEnd).trim()
-
-  switch (method) {
-    case 'find': {
-      const split = splitTopLevelArgs(argsSrc)
-      if (!split.ok) return { ok: false, error: split.error }
-      if (split.parts.length > 2) {
-        return { ok: false, error: '`find` accepts at most 2 arguments' }
-      }
-      const filter = compileObject(split.parts[0] ?? '{}', 'filter')
-      if (!filter.ok) return { ok: false, error: filter.error }
-      const projection =
-        split.parts[1] === undefined ? null : compileObject(split.parts[1], 'projection')
-      if (projection !== null && !projection.ok) {
-        return { ok: false, error: projection.error }
-      }
+  const pad = ' '.repeat(options.indent ?? 2)
+  // Chained calls are printed at column 0 and shifted by `pad`, so they get that much less width.
+  const chainOptions =
+    options.printWidth === undefined
+      ? options
+      : { ...options, printWidth: options.printWidth - pad.length }
+  const lines = [printCall(`${printTarget(ast.target)}.`, ast.method, options)]
+  for (const call of ast.chain) {
+    lines.push(pad + printCall('.', call, chainOptions).replace(/\n/g, `\n${pad}`))
+  }
+  return lines.join('\n')
+}
 
-      const trailer = parseTrailer(input.slice(argsEnd + 1))
-      if (!trailer.ok) return { ok: false, error: trailer.error }
+/** `db.name` when `coll` is a dotted identifier path, else `db.getCollection("…")`. */
+export function shellCollectionAccessor(coll: string): string {
+  return DOTTED_IDENTIFIER_RE.test(coll)
+    ? `db.${coll}`
+    : `db.getCollection(${JSON.stringify(coll)})`
+}
 
-      return {
-        ok: true,
-        coll,
-        op: {
-          kind: 'find',
-          filter: filter.ejson,
-          projection: projection ? projection.ejson : null,
-          sort: trailer.sort,
-          skip: trailer.skip,
-          limit: trailer.limit
+function parseShellAst(input: string): ShellAst {
+  const parser = new Parser(tokenizeCommand(input), input)
+  const end = input.length
+  const head = parser.advance()
+  if (head?.type !== 'ident' || head.value !== 'db') {
+    throw new ParseError(EXPECTED_COMMAND, head?.offset ?? end)
+  }
+  const { target, method } = parseTarget(parser, end)
+  const ast: ShellAst = { target, method: { ...method, args: parser.parseArgs() }, chain: [] }
+  while (isPunct(parser.peek(), '.')) {
+    const call = methodAfterDot(parser, end)
+    ast.chain.push({ ...call, args: parser.parseArgs() })
+  }
+  let terminated = false
+  while (isPunct(parser.peek(), ';')) {
+    parser.advance()
+    terminated = true
+  }
+  const rest = parser.peek()
+  if (rest && terminated) throw new ParseError('Only one command per run', rest.offset)
+  parser.expectEnd()
+  return ast
+}
+
+function tokenizeCommand(input: string): Token[] {
+  try {
+    return tokenize(input, { shell: true })
+  } catch (e) {
+    // e.g. the "-" in db.player-data
+    if (e instanceof ParseError && DOTTED_HEAD_RE.test(input.slice(0, e.offset))) {
+      throw new ParseError(NON_IDENTIFIER_NAME, e.offset)
+    }
+    throw e
+  }
+}
+
+function parseTarget(
+  parser: Parser,
+  end: number
+): { target: Target; method: { name: string; offset: number } } {
+  const next = parser.peek()
+  if (isPunct(next, '[')) {
+    parser.advance()
+    const name = parser.advance()
+    if (name?.type !== 'string') {
+      throw new ParseError(
+        'Expected the collection name as a string, e.g. db["name"]',
+        name?.offset ?? end
+      )
+    }
+    if (name.value === '') throw new ParseError(EMPTY_NAME, name.offset)
+    parser.expectPunct(']')
+    return {
+      target: { name: name.value, accessor: 'bracket' },
+      method: methodAfterDot(parser, end)
+    }
+  }
+  if (!isPunct(next, '.')) {
+    // `db.2024_logs` tokenizes as `db` followed by the number `.2024`.
+    const dottedNumber = next?.type === 'number' && next.value.startsWith('.')
+    throw new ParseError(dottedNumber ? NON_IDENTIFIER_NAME : EXPECTED_COMMAND, next?.offset ?? end)
+  }
+  const names: string[] = []
+  for (;;) {
+    parser.advance()
+    const segment = parser.advance()
+    if (segment?.type !== 'ident') {
+      throw new ParseError(
+        segment?.type === 'number' ? NON_IDENTIFIER_NAME : EXPECTED_COMMAND,
+        segment?.offset ?? end
+      )
+    }
+    const after = parser.peek()
+    if (isPunct(after, '(')) {
+      if (names.length > 0) {
+        return {
+          target: { name: names.join('.'), accessor: 'dot' },
+          method: { name: segment.value, offset: segment.offset }
         }
       }
+      if (segment.value === 'getCollection') {
+        const name = getCollectionName(parser, segment.offset)
+        return { target: { name, accessor: 'getCollection' }, method: methodAfterDot(parser, end) }
+      }
+      throw new ParseError(
+        `\`db.${segment.value}()\` isn't supported; use db.<collection>.<method>(…)`,
+        segment.offset
+      )
     }
+    names.push(segment.value)
+    if (isPunct(after, '.')) continue
+    if (after === undefined) throw new ParseError(EXPECTED_COMMAND, end)
+    throw new ParseError(
+      after.type === 'punct' ? EXPECTED_COMMAND : NON_IDENTIFIER_NAME,
+      after.offset
+    )
+  }
+}
+
+function getCollectionName(parser: Parser, offset: number): string {
+  const args = parser.parseArgs()
+  const arg = args[0]
+  if (args.length !== 1 || typeof arg?.value !== 'string') {
+    throw new ParseError(
+      'db.getCollection() expects the collection name as a string',
+      arg?.offset ?? offset
+    )
+  }
+  if (arg.value === '') throw new ParseError(EMPTY_NAME, arg.offset)
+  return arg.value
+}
+
+function methodAfterDot(parser: Parser, end: number): { name: string; offset: number } {
+  parser.expectPunct('.')
+  const name = parser.advance()
+  if (name?.type !== 'ident') {
+    throw new ParseError('Expected a method name after "."', name?.offset ?? end)
+  }
+  return { name: name.value, offset: name.offset }
+}
+
+function compileShellAst(ast: ShellAst): ShellCommand {
+  const { method } = ast
+  if (!isCollectionMethod(method.name)) {
+    throw new ParseError(unsupportedMethodMessage(method.name), method.offset)
+  }
+  return { coll: ast.target.name, op: compileOp(method.name, ast) }
+}
+
+function unsupportedMethodMessage(name: string): string {
+  const replacement = LEGACY_METHODS.get(name)
+  if (replacement !== undefined) return `\`${name}()\` is a legacy method; use ${replacement}`
+  const menuItem = ADMIN_METHODS.get(name)
+  if (menuItem !== undefined) {
+    return `\`${name}()\` isn't supported here; use ${menuItem} in the explorer's collection menu`
+  }
+  return `Unsupported method \`${name}\`. Supported: ${SHELL_COLLECTION_METHODS.join(', ')}.`
+}
+
+function compileOp(name: CollectionMethod, ast: ShellAst): ShellOp {
+  const { method } = ast
+  switch (name) {
+    case 'find':
+      return compileFind(ast)
     case 'findOne': {
-      const split = splitTopLevelArgs(argsSrc)
-      if (!split.ok) return { ok: false, error: split.error }
-      if (split.parts.length > 1) {
-        return { ok: false, error: '`findOne` accepts at most 1 argument' }
+      rejectChain(ast)
+      const [filter, projection] = argsUpTo(method, 2, 'findOne(filter, projection)')
+      return {
+        kind: 'findOne',
+        filter: filterOf(filter, 'findOne()'),
+        projection: projectionOf(projection, 'findOne() projection')
       }
-      const filter = compileObject(split.parts[0] ?? '{}', 'filter')
-      if (!filter.ok) return { ok: false, error: filter.error }
-      const trailer = expectNoTrailer(input.slice(argsEnd + 1))
-      if (!trailer.ok) return { ok: false, error: trailer.error }
-      return { ok: true, coll, op: { kind: 'findOne', filter: filter.ejson } }
     }
-    case 'count':
-    case 'countDocuments': {
-      const split = splitTopLevelArgs(argsSrc)
-      if (!split.ok) return { ok: false, error: split.error }
-      if (split.parts.length > 1) {
-        return { ok: false, error: `\`${method}\` accepts at most 1 argument` }
+    case 'aggregate': {
+      for (const call of ast.chain) {
+        if (!isAggregateCursorMethod(call.name)) {
+          throw new ParseError(`\`.${call.name}()\` can't follow aggregate(…)`, call.offset)
+        }
+        rejectArgs(call)
+      }
+      const [pipeline] = argsUpTo(method, 1, 'aggregate(pipeline)')
+      if (pipeline === undefined) {
+        throw new ParseError(
+          'aggregate() expects the pipeline array, e.g. aggregate([{ $match: { … } }])',
+          method.offset
+        )
+      }
+      const checked = checkPipeline(pipeline.value, { allowFinalWrite: true })
+      if (!checked.ok) throw new ParseError(checked.error, pipeline.offset)
+      const stages = pipeline.value as unknown[]
+      if (finalWriteStage(stages) === null) {
+        return {
+          kind: 'aggregate',
+          pipeline: checked.ejson,
+          documentPreserving: checked.documentPreserving
+        }
+      }
+      return {
+        kind: 'write',
+        write: { method: 'aggregate', pipeline: checked.ejson },
+        writes: outputCollection(stages, pipeline.offset)
       }
-      const filter = compileObject(split.parts[0] ?? '{}', 'filter')
-      if (!filter.ok) return { ok: false, error: filter.error }
-      const trailer = expectNoTrailer(input.slice(argsEnd + 1))
-      if (!trailer.ok) return { ok: false, error: trailer.error }
-      return { ok: true, coll, op: { kind: 'countDocuments', filter: filter.ejson } }
     }
-    case 'aggregate': {
-      const split = splitTopLevelArgs(argsSrc)
-      if (!split.ok) return { ok: false, error: split.error }
-      if (split.parts.length !== 1) {
-        return { ok: false, error: '`aggregate` expects exactly 1 argument: the pipeline array' }
+    case 'countDocuments':
+    case 'count': {
+      rejectChain(ast)
+      const [filter] = argsUpTo(method, 1, `${name}(filter)`)
+      return { kind: 'count', method: name, filter: filterOf(filter, `${name}()`) }
+    }
+    case 'estimatedDocumentCount':
+      rejectChain(ast)
+      argsUpTo(method, 0, 'estimatedDocumentCount()')
+      return { kind: 'count', method: name, filter: null }
+    case 'distinct': {
+      rejectChain(ast)
+      const [field, filter] = argsUpTo(method, 2, 'distinct(field, filter)')
+      if (typeof field?.value !== 'string' || field.value === '') {
+        throw new ParseError(
+          'distinct() expects a field name string',
+          field?.offset ?? method.offset
+        )
       }
-      const parsed = parseMongoQuery(split.parts[0]!)
-      if (!parsed.ok) return { ok: false, error: `pipeline: ${parsed.error}` }
-      if (!Array.isArray(parsed.value)) {
-        return { ok: false, error: 'pipeline must be an array' }
+      return {
+        kind: 'distinct',
+        field: field.value,
+        filter: filter === undefined ? null : objectOf(filter, 'distinct() filter')
       }
-      const trailer = expectNoTrailer(input.slice(argsEnd + 1))
-      if (!trailer.ok) return { ok: false, error: trailer.error }
-      return { ok: true, coll, op: { kind: 'aggregate', pipeline: parsed.ejson } }
     }
     default:
+      rejectChain(ast)
       return {
-        ok: false,
-        error: `Unsupported method: ${method}. Try find, findOne, aggregate, count, countDocuments.`
+        kind: 'write',
+        write: compileWrite(name, method),
+        writes: { db: null, coll: ast.target.name }
       }
   }
 }
 
-type CompiledObject = { ok: true; ejson: string } | { ok: false; error: string }
+function compileWrite(name: WriteMethod, call: Call): WriteOp {
+  const params = WRITE_ARGUMENTS[name]
+  const usage = `Use ${name}(${[...params, 'options'].join(', ')})`
+  const extra = call.args[params.length + 1]
+  if (extra !== undefined) throw new ParseError(`Too many arguments. ${usage}`, extra.offset)
+  const missing = params[call.args.length]
+  if (missing !== undefined) throw new ParseError(`Missing ${missing}. ${usage}`, call.offset)
+  const first = call.args[0]!
+  const optionsArg = call.args[params.length]
+  // Called last in each literal below, so arguments are checked in source order.
+  const options = (): { options?: string } =>
+    optionsArg === undefined
+      ? {}
+      : { options: ejsonOf(optionsArg, (value) => writeOptionsError(name, value)) }
+  switch (name) {
+    case 'insertOne':
+      return { method: name, document: ejsonOf(first, insertDocumentError), ...options() }
+    case 'insertMany':
+      return { method: name, documents: insertManyDocuments(first), ...options() }
+    case 'updateOne':
+    case 'updateMany':
+    case 'findOneAndUpdate':
+      return {
+        method: name,
+        filter: ejsonOf(first, (value) => filterError(name, value)),
+        update: ejsonOf(call.args[1]!, updateError),
+        ...options()
+      }
+    case 'replaceOne':
+    case 'findOneAndReplace':
+      return {
+        method: name,
+        filter: ejsonOf(first, (value) => filterError(name, value)),
+        replacement: ejsonOf(call.args[1]!, replacementError),
+        ...options()
+      }
+    case 'deleteOne':
+    case 'deleteMany':
+    case 'findOneAndDelete':
+      return {
+        method: name,
+        filter: ejsonOf(first, (value) => filterError(name, value)),
+        ...options()
+      }
+    case 'bulkWrite':
+      return { method: name, operations: ejsonOf(first, bulkWriteError), ...options() }
+  }
+}
 
-function compileObject(src: string, label: string): CompiledObject {
-  if (src.trim().length === 0) return { ok: true, ejson: '{}' }
-  const parsed = parseMongoQuery(src)
-  if (!parsed.ok) return { ok: false, error: `${label}: ${parsed.error}` }
-  if (parsed.value === null || typeof parsed.value !== 'object' || Array.isArray(parsed.value)) {
-    return { ok: false, error: `${label}: must be an object` }
+function insertManyDocuments(arg: Arg): string[] {
+  if (!Array.isArray(arg.value) || arg.value.length === 0) {
+    throw new ParseError('insertMany() expects a non-empty array of documents', arg.offset)
   }
-  return { ok: true, ejson: parsed.ejson }
+  if (arg.value.length > MAX_INSERT_DOCUMENTS) {
+    throw new ParseError(
+      `insertMany() takes at most ${MAX_INSERT_DOCUMENTS.toLocaleString('en-US')} documents per run`,
+      arg.offset
+    )
+  }
+  return arg.value.map((value: unknown) =>
+    ejsonOf({ value, offset: arg.offset }, insertDocumentError)
+  )
 }
 
-type TrailerResult =
-  | { ok: true; sort: string | null; skip: number | null; limit: number | null }
-  | { ok: false; error: string }
+function ejsonOf(arg: Arg, error: (value: unknown) => string | null): string {
+  const message = error(arg.value)
+  if (message !== null) throw new ParseError(message, arg.offset)
+  return JSON.stringify(arg.value)
+}
 
-function parseTrailer(rest: string): TrailerResult {
-  let s = rest.trim()
+function outputCollection(stages: unknown[], offset: number): { db: string | null; coll: string } {
+  const [operator, spec] = Object.entries(stages[stages.length - 1] as object)[0]!
+  const target = operator === '$merge' && isDocument(spec) ? spec['into'] : spec
+  if (isName(target)) return { db: null, coll: target }
+  if (isDocument(target) && isName(target['coll'])) {
+    const db = target['db']
+    if (db === undefined || isName(db)) return { db: db ?? null, coll: target['coll'] }
+  }
+  const example = operator === '$merge' ? '{ $merge: { into: "name" } }' : '{ $out: "name" }'
+  throw new ParseError(
+    `Stage ${stages.length}: ${operator} must name the output collection, e.g. ${example}`,
+    offset
+  )
+}
+
+function compileFind(ast: ShellAst): ShellOp {
+  const [filterArg, projectionArg] = argsUpTo(ast.method, 2, 'find(filter, projection)')
+  let projection = projectionOf(projectionArg, 'find() projection')
   let sort: string | null = null
-  let skip: number | null = null
+  let skip = 0
   let limit: number | null = null
-
-  while (s.length > 0) {
-    if (!s.startsWith('.')) {
-      return { ok: false, error: `Unexpected trailing content: ${truncate(s)}` }
+  const seen = new Set<string>()
+  for (const call of ast.chain) {
+    if (!isCursorMethod(call.name)) {
+      throw new ParseError(
+        call.name === 'count'
+          ? `Cursor .count() isn't supported; use ${shellCollectionAccessor(ast.target.name)}.countDocuments(filter)`
+          : `Unsupported cursor method .${call.name}(). Supported: ${SHELL_CURSOR_METHODS.join(', ')}`,
+        call.offset
+      )
     }
-    const callMatch = /^\.\s*([A-Za-z_$][\w$]*)\s*\(/.exec(s)
-    if (!callMatch) return { ok: false, error: `Expected chained method call after '.'` }
-    const name = callMatch[1]!
-    const argsStart = callMatch[0].length
-    const argsEnd = matchClosingParen(s, argsStart - 1)
-    if (argsEnd < 0) return { ok: false, error: `Missing closing ')' on .${name}(...)` }
-    const argSrc = s.slice(argsStart, argsEnd).trim()
-
-    switch (name) {
-      case 'sort': {
-        if (sort !== null) return { ok: false, error: '.sort() specified twice' }
-        const compiled = compileObject(argSrc, 'sort')
-        if (!compiled.ok) return { ok: false, error: compiled.error }
-        sort = compiled.ejson
+    if (seen.has(call.name)) throw new ParseError(`.${call.name}() specified twice`, call.offset)
+    seen.add(call.name)
+    switch (call.name) {
+      case 'sort':
+        sort = objectOf(onlyArg(call), '.sort() argument')
         break
-      }
-      case 'skip': {
-        if (skip !== null) return { ok: false, error: '.skip() specified twice' }
-        const n = parseNonNegativeInt(argSrc, 'skip')
-        if (n === null) return { ok: false, error: '.skip() expects a non-negative integer' }
-        skip = n
+      case 'projection':
+        if (projectionArg !== undefined) {
+          throw new ParseError(
+            'Projection given twice: pass it to find(…) or .projection(…), not both',
+            call.offset
+          )
+        }
+        projection = projectionOf(onlyArg(call), '.projection() argument')
+        break
+      case 'skip':
+        skip = countArg(call)
         break
-      }
       case 'limit': {
-        if (limit !== null) return { ok: false, error: '.limit() specified twice' }
-        const n = parseNonNegativeInt(argSrc, 'limit')
-        if (n === null) return { ok: false, error: '.limit() expects a non-negative integer' }
-        limit = n
+        // As in mongosh, limit(0) means no limit.
+        const n = countArg(call)
+        limit = n === 0 ? null : n
         break
       }
       case 'toArray':
       case 'pretty':
-        // No-ops in this client — silently accept.
-        if (argSrc.length > 0) return { ok: false, error: `.${name}() takes no arguments` }
+        rejectArgs(call)
         break
-      default:
-        return {
-          ok: false,
-          error: `Unsupported chained method: .${name}(). Try sort, skip, limit.`
-        }
     }
-    s = s.slice(argsEnd + 1).trim()
   }
+  return { kind: 'find', filter: filterOf(filterArg, 'find()'), projection, sort, skip, limit }
+}
 
-  return { ok: true, sort, skip, limit }
+function argsUpTo(call: Call, max: number, signature: string): Arg[] {
+  const extra = call.args[max]
+  if (extra !== undefined) {
+    throw new ParseError(
+      `Too many arguments; options aren't supported. Use ${signature}`,
+      extra.offset
+    )
+  }
+  return call.args
 }
 
-function expectNoTrailer(rest: string): TrailerResult {
-  const r = parseTrailer(rest)
-  if (!r.ok) return r
-  // Ignore the read fields; just propagate ok-ness.
-  return { ok: true, sort: null, skip: null, limit: null }
+function onlyArg(call: Call): Arg {
+  const [arg, extra] = call.args
+  if (arg === undefined || extra !== undefined) {
+    throw new ParseError(`.${call.name}() expects one argument`, (extra ?? call).offset)
+  }
+  return arg
 }
 
-function parseNonNegativeInt(src: string, _label: string): number | null {
-  if (!/^\d+$/.test(src.trim())) return null
-  const n = Number.parseInt(src.trim(), 10)
-  if (!Number.isFinite(n) || n < 0) return null
-  return n
+function rejectArgs(call: Call): void {
+  const [arg] = call.args
+  if (arg !== undefined) throw new ParseError(`.${call.name}() takes no arguments`, arg.offset)
 }
 
-/**
- * Returns the index of the `)` matching the `(` at `openIdx`, ignoring
- * parens inside string literals. -1 if unbalanced.
- */
-function matchClosingParen(src: string, openIdx: number): number {
-  let depth = 0
-  let i = openIdx
-  while (i < src.length) {
-    const ch = src[i]!
-    if (ch === '"' || ch === "'") {
-      i = skipString(src, i)
-      if (i < 0) return -1
-      continue
-    }
-    if (ch === '(') depth++
-    else if (ch === ')') {
-      depth--
-      if (depth === 0) return i
-    }
-    i++
+function rejectChain(ast: ShellAst): void {
+  const [call] = ast.chain
+  if (call !== undefined) {
+    throw new ParseError(`\`.${call.name}()\` can't follow ${ast.method.name}(…)`, call.offset)
   }
-  return -1
 }
 
-/**
- * Walk past a `"..."` or `'...'` string literal starting at `i` (which
- * must point at the opening quote). Returns the index past the closing
- * quote, or -1 if unterminated.
- */
-function skipString(src: string, i: number): number {
-  const quote = src[i]
-  i++
-  while (i < src.length) {
-    const ch = src[i]
-    if (ch === '\\') {
-      i += 2
-      continue
-    }
-    if (ch === quote) return i + 1
-    i++
+function countArg(call: Call): number {
+  const arg = onlyArg(call)
+  if (typeof arg.value !== 'number' || !Number.isSafeInteger(arg.value) || arg.value < 0) {
+    throw new ParseError(`.${call.name}() expects a non-negative integer`, arg.offset)
   }
-  return -1
+  return arg.value
 }
 
-type SplitResult = { ok: true; parts: string[] } | { ok: false; error: string }
+function objectOf(arg: Arg, what: string): string {
+  if (!isDocument(arg.value)) throw new ParseError(`${what} must be an object`, arg.offset)
+  return JSON.stringify(arg.value)
+}
 
-/**
- * Split arguments by top-level commas, respecting nested (), [], {}, and
- * string literals. Handles `find({a: 1}, {a: 0})` correctly.
- */
-function splitTopLevelArgs(src: string): SplitResult {
-  if (src.length === 0) return { ok: true, parts: [] }
-  const parts: string[] = []
-  let depth = 0
-  let start = 0
-  for (let i = 0; i < src.length; i++) {
-    const ch = src[i]!
-    if (ch === '"' || ch === "'") {
-      const next = skipString(src, i)
-      if (next < 0) return { ok: false, error: 'Unterminated string literal' }
-      i = next - 1
-      continue
-    }
-    if (ch === '(' || ch === '[' || ch === '{') depth++
-    else if (ch === ')' || ch === ']' || ch === '}') {
-      depth--
-      if (depth < 0) return { ok: false, error: 'Unmatched bracket in arguments' }
-    } else if (ch === ',' && depth === 0) {
-      parts.push(src.slice(start, i).trim())
-      start = i + 1
-    }
+function filterOf(arg: Arg | undefined, method: string): string {
+  return arg === undefined ? '{}' : objectOf(arg, `${method} filter`)
+}
+
+function projectionOf(arg: Arg | undefined, what: string): string | null {
+  if (arg === undefined) return null
+  const ejson = objectOf(arg, what)
+  return ejson === '{}' ? null : ejson
+}
+
+function printTarget(target: Target): string {
+  switch (target.accessor) {
+    case 'dot':
+      return `db.${target.name}`
+    case 'bracket':
+      return `db[${JSON.stringify(target.name)}]`
+    case 'getCollection':
+      return `db.getCollection(${JSON.stringify(target.name)})`
   }
-  if (depth !== 0) return { ok: false, error: 'Unmatched bracket in arguments' }
-  parts.push(src.slice(start).trim())
-  return { ok: true, parts }
 }
 
-function truncate(s: string): string {
-  return s.length > 40 ? s.slice(0, 37) + '…' : s
+function printCall(head: string, call: Call, options: SerializeOptions): string {
+  let text = `${head}${call.name}(`
+  for (const [index, arg] of call.args.entries()) {
+    if (index > 0) text += ', '
+    const startColumn = text.length - text.lastIndexOf('\n') - 1
+    text += serializeMongoValue(arg.value, { ...options, startColumn })
+  }
+  return `${text})`
 }
+
+const everyDocument = (method: 'updateMany' | 'deleteMany', coll: string): string =>
+  `${method} with an empty filter ${method === 'updateMany' ? 'updates' : 'deletes'} every document in ${coll}`
+
+const isEmptyDocument = (value: unknown): boolean =>
+  isDocument(value) && Object.keys(value).length === 0
+
+const isName = (value: unknown): value is string => typeof value === 'string' && value !== ''
+
+const isPunct = (token: Token | undefined, value: PunctValue): boolean =>
+  token?.type === 'punct' && token.value === value
+
+const isCollectionMethod = (name: string): name is CollectionMethod =>
+  (SHELL_COLLECTION_METHODS as readonly string[]).includes(name)
+
+const isCursorMethod = (name: string): name is CursorMethod =>
+  (SHELL_CURSOR_METHODS as readonly string[]).includes(name)
+
+const isAggregateCursorMethod = (name: string): boolean =>
+  (SHELL_AGGREGATE_CURSOR_METHODS as readonly string[]).includes(name)
diff --git a/src/renderer/src/lib/suggestions.test.ts b/src/renderer/src/lib/suggestions.test.ts
new file mode 100644
index 0000000..0c9bb66
--- /dev/null
+++ b/src/renderer/src/lib/suggestions.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest'
+import { rankSuggestions } from './suggestions'
+
+describe('rankSuggestions', () => {
+  it('returns the pool in its original order for an empty input', () => {
+    expect(rankSuggestions('', ['zeta', 'alpha', 'mid'])).toEqual(['zeta', 'alpha', 'mid'])
+    expect(rankSuggestions('   ', ['zeta', 'alpha'])).toEqual(['zeta', 'alpha'])
+  })
+
+  it('caps an empty-input result at the limit', () => {
+    const pool = Array.from({ length: 80 }, (_, i) => `f${i}`)
+    expect(rankSuggestions('', pool)).toEqual(pool.slice(0, 50))
+    expect(rankSuggestions('', pool, 3)).toEqual(['f0', 'f1', 'f2'])
+  })
+
+  it('matches substrings case-insensitively', () => {
+    expect(rankSuggestions('WRITE', ['read', 'readWrite', 'writer', 'dbOwner'])).toEqual([
+      'writer',
+      'readWrite'
+    ])
+  })
+
+  it('puts prefix matches before infix matches, each group alphabetical', () => {
+    expect(rankSuggestions('ad', ['readAnyDatabase', 'admin', 'dbAdmin', 'adHoc'])).toEqual([
+      'adHoc',
+      'admin',
+      'dbAdmin',
+      'readAnyDatabase'
+    ])
+  })
+
+  it('trims the input before matching', () => {
+    expect(rankSuggestions('  user ', ['userAdmin', 'name'])).toEqual(['userAdmin'])
+  })
+
+  it('returns nothing once the value equals the only match', () => {
+    expect(rankSuggestions('dbOwner', ['dbOwner', 'read'])).toEqual([])
+    expect(rankSuggestions(' dbOwner ', ['dbOwner', 'read'])).toEqual([])
+  })
+
+  it('keeps an exact match while other candidates remain', () => {
+    expect(rankSuggestions('read', ['read', 'readWrite'])).toEqual(['read', 'readWrite'])
+  })
+
+  it('caps a filtered result at the limit', () => {
+    const pool = Array.from({ length: 60 }, (_, i) => `role${String(i).padStart(2, '0')}`)
+    expect(rankSuggestions('role', pool)).toHaveLength(50)
+    expect(rankSuggestions('role', pool, 2)).toEqual(['role00', 'role01'])
+  })
+
+  it('does not mutate the pool', () => {
+    const pool = ['b', 'ab', 'a']
+    rankSuggestions('a', pool)
+    expect(pool).toEqual(['b', 'ab', 'a'])
+  })
+})
diff --git a/src/renderer/src/lib/suggestions.ts b/src/renderer/src/lib/suggestions.ts
new file mode 100644
index 0000000..3f5183c
--- /dev/null
+++ b/src/renderer/src/lib/suggestions.ts
@@ -0,0 +1,35 @@
+type PoolEntry = { text: string; lower: string }
+
+// Orders like a default localeCompare, without resolving the locale on every comparison.
+const collator = new Intl.Collator()
+// Pools are memoized arrays ranked on every keystroke; lowercase each one once.
+const loweredPools = new WeakMap<readonly string[], PoolEntry[]>()
+
+function lowered(pool: readonly string[]): PoolEntry[] {
+  let entries = loweredPools.get(pool)
+  if (entries === undefined) {
+    entries = pool.map((text) => ({ text, lower: text.toLowerCase() }))
+    loweredPools.set(pool, entries)
+  }
+  return entries
+}
+
+/** Case-insensitive substring matches, prefix matches first; empty once value equals the only match. */
+export function rankSuggestions(value: string, pool: readonly string[], limit = 50): string[] {
+  const trimmed = value.trim()
+  const needle = trimmed.toLowerCase()
+  let ranked: readonly string[] = pool
+  if (needle) {
+    const prefix: string[] = []
+    const infix: string[] = []
+    for (const { text, lower } of lowered(pool)) {
+      const at = lower.indexOf(needle)
+      if (at === 0) prefix.push(text)
+      else if (at > 0) infix.push(text)
+    }
+    ranked = [...prefix.sort(collator.compare), ...infix.sort(collator.compare)]
+  }
+  // Nothing left to complete once the value matches the only candidate.
+  if (ranked.length === 1 && ranked[0] === trimmed) return []
+  return ranked.slice(0, limit)
+}
diff --git a/src/renderer/src/lib/userRoles.test.ts b/src/renderer/src/lib/userRoles.test.ts
new file mode 100644
index 0000000..69cf056
--- /dev/null
+++ b/src/renderer/src/lib/userRoles.test.ts
@@ -0,0 +1,242 @@
+import { describe, expect, it } from 'vitest'
+import type { DatabaseRoleInfo, DatabaseUser, DatabaseUserRole } from '@shared/types'
+import {
+  addRole,
+  COMMON_DB_ROLES,
+  databaseSuggestions,
+  diffRoles,
+  groupRoles,
+  hasRole,
+  matchesRoleFilter,
+  orderRoles,
+  removeRole,
+  roleEntries,
+  roleKey,
+  roleLabel,
+  roleSuggestions
+} from './userRoles'
+
+const r = (role: string, db: string): DatabaseUserRole => ({ role, db })
+
+const user = (name: string, roles: DatabaseUserRole[]): DatabaseUser => ({
+  user: name,
+  db: 'admin',
+  roles
+})
+
+describe('roleKey', () => {
+  it('keeps role and db apart even when dots could make them collide', () => {
+    expect(roleKey(r('b.c', 'a'))).not.toBe(roleKey(r('c', 'a.b')))
+  })
+
+  it('is the same for equal roles', () => {
+    expect(roleKey(r('read', 'shop'))).toBe(roleKey({ db: 'shop', role: 'read' }))
+  })
+})
+
+describe('roleLabel', () => {
+  it('reads role@db', () => {
+    expect(roleLabel(r('readWrite', 'shop'))).toBe('readWrite@shop')
+  })
+})
+
+describe('hasRole', () => {
+  it('needs both role and db to match', () => {
+    const roles = [r('read', 'shop')]
+    expect(hasRole(roles, r('read', 'shop'))).toBe(true)
+    expect(hasRole(roles, r('read', 'admin'))).toBe(false)
+    expect(hasRole(roles, r('readWrite', 'shop'))).toBe(false)
+  })
+})
+
+describe('addRole', () => {
+  it('appends a role that is not assigned yet', () => {
+    expect(addRole([r('read', 'shop')], r('dbOwner', 'shop'))).toEqual([
+      r('read', 'shop'),
+      r('dbOwner', 'shop')
+    ])
+  })
+
+  it('never adds a duplicate', () => {
+    const roles = [r('read', 'shop')]
+    const next = addRole(roles, r('read', 'shop'))
+    expect(next).toEqual([r('read', 'shop')])
+    expect(next).not.toBe(roles)
+  })
+})
+
+describe('removeRole', () => {
+  it('removes only the exact role on that db', () => {
+    const roles = [r('read', 'shop'), r('read', 'logs'), r('dbOwner', 'shop')]
+    expect(removeRole(roles, r('read', 'shop'))).toEqual([r('read', 'logs'), r('dbOwner', 'shop')])
+    expect(roles).toHaveLength(3)
+  })
+})
+
+describe('diffRoles', () => {
+  it('reports nothing when only the order differs', () => {
+    const initial = [r('read', 'a'), r('readWrite', 'b')]
+    expect(diffRoles(initial, [r('readWrite', 'b'), r('read', 'a')])).toEqual({
+      added: [],
+      removed: []
+    })
+  })
+
+  it('reports added and removed roles', () => {
+    const initial = [r('read', 'a'), r('readWrite', 'b')]
+    const current = [r('readWrite', 'b'), r('dbOwner', 'a')]
+    expect(diffRoles(initial, current)).toEqual({
+      added: [r('dbOwner', 'a')],
+      removed: [r('read', 'a')]
+    })
+  })
+
+  it('treats the same role on another db as a different role', () => {
+    expect(diffRoles([r('read', 'a')], [r('read', 'b')])).toEqual({
+      added: [r('read', 'b')],
+      removed: [r('read', 'a')]
+    })
+  })
+})
+
+describe('orderRoles', () => {
+  it('puts the current db first, then sorts by db and role', () => {
+    const roles = [r('read', 'zoo'), r('readWrite', 'app'), r('read', 'app'), r('dbOwner', 'shop')]
+    expect(orderRoles(roles, 'shop')).toEqual([
+      r('dbOwner', 'shop'),
+      r('read', 'app'),
+      r('readWrite', 'app'),
+      r('read', 'zoo')
+    ])
+  })
+
+  it('does not change its input', () => {
+    const roles = [r('read', 'b'), r('read', 'a')]
+    orderRoles(roles, 'x')
+    expect(roles).toEqual([r('read', 'b'), r('read', 'a')])
+  })
+})
+
+describe('matchesRoleFilter', () => {
+  it('matches everything for an empty or blank filter', () => {
+    expect(matchesRoleFilter(r('read', 'shop'), '')).toBe(true)
+    expect(matchesRoleFilter(r('read', 'shop'), '   ')).toBe(true)
+  })
+
+  it('matches the role name case-insensitively', () => {
+    expect(matchesRoleFilter(r('readWrite', 'shop'), 'WRITE')).toBe(true)
+  })
+
+  it('matches the db name', () => {
+    expect(matchesRoleFilter(r('read', 'tenant_42'), 'tenant')).toBe(true)
+  })
+
+  it('matches the role@db form', () => {
+    expect(matchesRoleFilter(r('readWrite', 'sh'), ' readwrite@sh ')).toBe(true)
+    expect(matchesRoleFilter(r('readWrite', 'sh'), 'te@s')).toBe(true)
+  })
+
+  it('rejects roles that match nowhere', () => {
+    expect(matchesRoleFilter(r('read', 'shop'), 'owner')).toBe(false)
+  })
+})
+
+describe('groupRoles', () => {
+  it('marks kept, added and removed roles and keeps removed ones visible', () => {
+    const initial = [r('read', 'shop'), r('dbOwner', 'shop')]
+    const current = [r('read', 'shop'), r('readWrite', 'shop')]
+    expect(groupRoles(roleEntries(initial, current, 'shop'), '')).toEqual([
+      {
+        db: 'shop',
+        roles: [
+          { role: r('dbOwner', 'shop'), status: 'removed' },
+          { role: r('read', 'shop'), status: 'kept' },
+          { role: r('readWrite', 'shop'), status: 'added' }
+        ]
+      }
+    ])
+  })
+
+  it('puts the current db group first and sorts the rest by db', () => {
+    const current = [r('read', 'zoo'), r('read', 'app'), r('read', 'shop')]
+    expect(groupRoles(roleEntries([], current, 'shop'), '').map((g) => g.db)).toEqual([
+      'shop',
+      'app',
+      'zoo'
+    ])
+  })
+
+  it('drops groups the filter leaves empty', () => {
+    const current = [r('read', 'shop'), r('dbOwner', 'logs')]
+    expect(groupRoles(roleEntries([], current, 'shop'), 'owner')).toEqual([
+      { db: 'logs', roles: [{ role: r('dbOwner', 'logs'), status: 'added' }] }
+    ])
+  })
+
+  it('returns no groups without roles', () => {
+    expect(groupRoles(roleEntries([], [], 'shop'), '')).toEqual([])
+  })
+})
+
+describe('roleSuggestions', () => {
+  const serverRoles: DatabaseRoleInfo[] = [
+    { role: 'read', db: 'shop', isBuiltin: true },
+    { role: 'orderClerk', db: 'shop', isBuiltin: false },
+    { role: '__system', db: 'shop', isBuiltin: true },
+    { role: 'reportViewer', db: 'logs', isBuiltin: false }
+  ]
+
+  it('takes only the target db roles from the server and skips internal ones', () => {
+    const out = roleSuggestions('shop', { serverRoles, users: [], assigned: [] })
+    expect(out).toContain('orderClerk')
+    expect(out).not.toContain('reportViewer')
+    expect(out).not.toContain('__system')
+  })
+
+  it('includes roles seen on other users for that db', () => {
+    const users = [user('a', [r('auditor', 'shop'), r('archiver', 'logs')])]
+    const out = roleSuggestions('shop', { users, assigned: [] })
+    expect(out).toContain('auditor')
+    expect(out).not.toContain('archiver')
+  })
+
+  it('always offers the common roles, also without server roles', () => {
+    const out = roleSuggestions('shop', { users: [], assigned: [] })
+    expect(out).toEqual([...COMMON_DB_ROLES].sort((a, b) => a.localeCompare(b)))
+  })
+
+  it('leaves out roles already assigned on the target db only', () => {
+    const assigned = [r('read', 'shop'), r('dbOwner', 'logs')]
+    const out = roleSuggestions('shop', { serverRoles, users: [], assigned })
+    expect(out).not.toContain('read')
+    expect(out).toContain('dbOwner')
+  })
+
+  it('dedupes and sorts', () => {
+    const users = [user('a', [r('orderClerk', 'shop')]), user('b', [r('readWrite', 'shop')])]
+    expect(roleSuggestions('shop', { serverRoles, users, assigned: [] })).toEqual([
+      'dbAdmin',
+      'dbOwner',
+      'orderClerk',
+      'read',
+      'readWrite',
+      'userAdmin'
+    ])
+  })
+})
+
+describe('databaseSuggestions', () => {
+  it('unites listed databases, admin, the current db and role dbs, deduped and sorted', () => {
+    const users = [user('a', [r('read', 'logs'), r('read', 'shop'), r('read', 'legacy')])]
+    expect(
+      databaseSuggestions('shop', {
+        databases: [{ name: 'shop' }, { name: 'logs' }, { name: 'config' }],
+        users
+      })
+    ).toEqual(['admin', 'config', 'legacy', 'logs', 'shop'])
+  })
+
+  it('works before the database list has loaded', () => {
+    expect(databaseSuggestions('shop', { users: [] })).toEqual(['admin', 'shop'])
+  })
+})
diff --git a/src/renderer/src/lib/userRoles.ts b/src/renderer/src/lib/userRoles.ts
new file mode 100644
index 0000000..3d6df36
--- /dev/null
+++ b/src/renderer/src/lib/userRoles.ts
@@ -0,0 +1,140 @@
+import type { DatabaseInfo, DatabaseRoleInfo, DatabaseUser, DatabaseUserRole } from '@shared/types'
+
+/** Built-in roles that exist on every database. */
+export const COMMON_DB_ROLES = ['read', 'readWrite', 'dbAdmin', 'dbOwner', 'userAdmin'] as const
+
+// Orders like a default localeCompare, without resolving the locale on every comparison.
+const collator = new Intl.Collator()
+
+/** Identity of a role assignment; NUL is valid in neither a role nor a database name. */
+export function roleKey(role: DatabaseUserRole): string {
+  return `${role.db}\u0000${role.role}`
+}
+
+/** Display form `role@db`. */
+export function roleLabel(role: DatabaseUserRole): string {
+  return `${role.role}@${role.db}`
+}
+
+/** Whether `role` is assigned on exactly its db. */
+export function hasRole(roles: readonly DatabaseUserRole[], role: DatabaseUserRole): boolean {
+  const key = roleKey(role)
+  return roles.some((r) => roleKey(r) === key)
+}
+
+/** Copy of `roles` with `role` appended unless it is already assigned. */
+export function addRole(
+  roles: readonly DatabaseUserRole[],
+  role: DatabaseUserRole
+): DatabaseUserRole[] {
+  return hasRole(roles, role) ? [...roles] : [...roles, role]
+}
+
+/** Copy of `roles` without `role` on its db; the same role on other dbs stays. */
+export function removeRole(
+  roles: readonly DatabaseUserRole[],
+  role: DatabaseUserRole
+): DatabaseUserRole[] {
+  const key = roleKey(role)
+  return roles.filter((r) => roleKey(r) !== key)
+}
+
+/** Roles only in `current` (added) and only in `initial` (removed); order is ignored. */
+export function diffRoles(
+  initial: readonly DatabaseUserRole[],
+  current: readonly DatabaseUserRole[]
+): { added: DatabaseUserRole[]; removed: DatabaseUserRole[] } {
+  const before = new Set(initial.map(roleKey))
+  const after = new Set(current.map(roleKey))
+  return {
+    added: current.filter((r) => !before.has(roleKey(r))),
+    removed: initial.filter((r) => !after.has(roleKey(r)))
+  }
+}
+
+function compareRoles(currentDb: string): (a: DatabaseUserRole, b: DatabaseUserRole) => number {
+  return (a, b) =>
+    Number(b.db === currentDb) - Number(a.db === currentDb) ||
+    collator.compare(a.db, b.db) ||
+    collator.compare(a.role, b.role)
+}
+
+/** Sorted copy: roles on `currentDb` first, then by db, then by role. */
+export function orderRoles(
+  roles: readonly DatabaseUserRole[],
+  currentDb: string
+): DatabaseUserRole[] {
+  return [...roles].sort(compareRoles(currentDb))
+}
+
+/** Case-insensitive substring match against `role@db`; a blank filter matches everything. */
+export function matchesRoleFilter(role: DatabaseUserRole, filter: string): boolean {
+  const needle = filter.trim().toLowerCase()
+  return needle === '' || roleLabel(role).toLowerCase().includes(needle)
+}
+
+export type RoleStatus = 'kept' | 'added' | 'removed'
+
+export type RoleEntry = { role: DatabaseUserRole; status: RoleStatus }
+
+export type RoleGroup = { db: string; roles: RoleEntry[] }
+
+/** Current roles plus removed initial ones, each with its status, in `orderRoles` order. */
+export function roleEntries(
+  initial: readonly DatabaseUserRole[],
+  current: readonly DatabaseUserRole[],
+  currentDb: string
+): RoleEntry[] {
+  const before = new Set(initial.map(roleKey))
+  const entries = new Map<string, RoleEntry>()
+  for (const role of current) {
+    const key = roleKey(role)
+    entries.set(key, { role, status: before.has(key) ? 'kept' : 'added' })
+  }
+  for (const role of initial) {
+    const key = roleKey(role)
+    if (!entries.has(key)) entries.set(key, { role, status: 'removed' })
+  }
+  const compare = compareRoles(currentDb)
+  return [...entries.values()].sort((a, b) => compare(a.role, b.role))
+}
+
+/** `roleEntries` output matching `filter`, grouped by db in its order. */
+export function groupRoles(entries: readonly RoleEntry[], filter: string): RoleGroup[] {
+  const groups = new Map<string, RoleGroup>()
+  for (const entry of entries) {
+    if (!matchesRoleFilter(entry.role, filter)) continue
+    const group = groups.get(entry.role.db) ?? { db: entry.role.db, roles: [] }
+    group.roles.push(entry)
+    groups.set(entry.role.db, group)
+  }
+  return [...groups.values()]
+}
+
+/** Assignable role names on `targetDb` that the user does not hold there yet, sorted. */
+export function roleSuggestions(
+  targetDb: string,
+  sources: {
+    serverRoles?: readonly DatabaseRoleInfo[]
+    users: readonly DatabaseUser[]
+    assigned: readonly DatabaseUserRole[]
+  }
+): string[] {
+  const names = new Set<string>(COMMON_DB_ROLES)
+  for (const r of sources.serverRoles ?? []) if (r.db === targetDb) names.add(r.role)
+  for (const u of sources.users) for (const r of u.roles) if (r.db === targetDb) names.add(r.role)
+  for (const r of sources.assigned) if (r.db === targetDb) names.delete(r.role)
+  // MongoDB documents __system and other __-prefixed roles as internal, never to be assigned.
+  return [...names].filter((name) => !name.startsWith('__')).sort(collator.compare)
+}
+
+/** Known database names (listed dbs, admin, the current db, dbs of listed roles), sorted. */
+export function databaseSuggestions(
+  currentDb: string,
+  sources: { databases?: readonly DatabaseInfo[]; users: readonly DatabaseUser[] }
+): string[] {
+  const names = new Set<string>(['admin', currentDb])
+  for (const d of sources.databases ?? []) names.add(d.name)
+  for (const u of sources.users) for (const r of u.roles) names.add(r.db)
+  return [...names].sort(collator.compare)
+}
diff --git a/src/renderer/src/store/tabs.test.ts b/src/renderer/src/store/tabs.test.ts
new file mode 100644
index 0000000..43a9b80
--- /dev/null
+++ b/src/renderer/src/store/tabs.test.ts
@@ -0,0 +1,646 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { CollectionRef } from '@shared/types'
+import {
+  activeCollectionKey,
+  collectionKey,
+  isDraftDirty,
+  ordinalLabel,
+  useTabsStore,
+  type AppliedQueries,
+  type QueryDraft
+} from './tabs'
+
+const users: CollectionRef = { connectionId: 'c1', db: 'app', coll: 'users' }
+const orders: CollectionRef = { connectionId: 'c1', db: 'app', coll: 'orders' }
+const logs: CollectionRef = { connectionId: 'c1', db: 'audit', coll: 'logs' }
+const remote: CollectionRef = { connectionId: 'c2', db: 'app', coll: 'users' }
+
+const store = () => useTabsStore.getState()
+const tab = (id: string) => {
+  const found = store().tabs.find((t) => t.id === id)
+  if (!found) throw new Error(`no tab ${id}`)
+  return found
+}
+const draft = (id: string): QueryDraft => {
+  const found = store().drafts[id]
+  if (!found) throw new Error(`no draft ${id}`)
+  return found
+}
+const activeId = (): string => {
+  const id = store().activeTabId
+  if (id === null) throw new Error('no active tab')
+  return id
+}
+const openNewId = (target: CollectionRef): string => {
+  store().openNew(target)
+  return activeId()
+}
+
+function assertInvariants(): void {
+  const s = store()
+  expect(Object.keys(s.drafts).sort()).toEqual(s.tabs.map((t) => t.id).sort())
+  if (s.activeTabId === null) {
+    expect(s.tabs).toHaveLength(0)
+  } else {
+    const active = tab(s.activeTabId)
+    for (const t of s.tabs) expect(t.lastActive).toBeLessThanOrEqual(active.lastActive)
+  }
+  const seen = new Set<string>()
+  for (const t of s.tabs) {
+    const key = `${t.connectionId}|${t.db}|${t.coll}|${t.ordinal}`
+    expect(seen.has(key)).toBe(false)
+    seen.add(key)
+  }
+}
+
+beforeEach(() => {
+  useTabsStore.setState(useTabsStore.getInitialState(), true)
+})
+
+describe('open', () => {
+  it('creates an active tab with the default draft and an already applied simple query', () => {
+    store().open(users)
+    const id = activeId()
+    expect(tab(id)).toMatchObject({ ...users, ordinal: 1 })
+    expect(draft(id)).toEqual({
+      mode: 'simple',
+      filter: '{}',
+      projection: '{}',
+      sort: '{}',
+      pipeline: '',
+      shell: '',
+      limit: '100'
+    })
+    expect(tab(id).applied).toEqual({
+      simple: {
+        filter: '{}',
+        projection: '{}',
+        sort: '{}',
+        skip: 0,
+        limit: 100,
+        epoch: expect.any(Number)
+      },
+      aggregation: null,
+      shell: null
+    })
+    expect(isDraftDirty(draft(id), tab(id).applied)).toBe(false)
+    assertInvariants()
+  })
+
+  it('focuses the existing tab instead of adding one', () => {
+    store().open(users)
+    const first = activeId()
+    store().open(orders)
+    store().open(users)
+    expect(store().tabs).toHaveLength(2)
+    expect(activeId()).toBe(first)
+    assertInvariants()
+  })
+
+  it('gives a reopened collection a fresh epoch, so it never shows an older cached result', () => {
+    store().open(users)
+    const firstEpoch = tab(activeId()).applied.simple.epoch
+    store().close(activeId())
+    store().open(users)
+    expect(tab(activeId()).applied.simple.epoch).toBeGreaterThan(firstEpoch)
+  })
+
+  it('copies the target fields instead of keeping the caller object', () => {
+    store().open({ ...users, extra: 'x' } as CollectionRef)
+    expect(Object.keys(tab(activeId())).sort()).toEqual(
+      ['applied', 'coll', 'connectionId', 'db', 'id', 'lastActive', 'ordinal'].sort()
+    )
+  })
+})
+
+describe('openNew', () => {
+  it('always adds a tab with the next ordinal and a distinct id', () => {
+    store().open(users)
+    const first = activeId()
+    const second = openNewId(users)
+    expect(second).not.toBe(first)
+    expect(tab(second).ordinal).toBe(2)
+    expect(store().tabs).toHaveLength(2)
+    assertInvariants()
+  })
+
+  it('uses URI-safe sequential ids', () => {
+    const a = openNewId(users)
+    const b = openNewId(orders)
+    expect(a).toMatch(/^t\d+$/)
+    expect(b).toMatch(/^t\d+$/)
+  })
+})
+
+describe('most recently active tab', () => {
+  it('open focuses the tab of the collection that was active last', () => {
+    const u1 = openNewId(users)
+    const u2 = openNewId(users)
+    const o = openNewId(orders)
+
+    store().activate(u2)
+    store().activate(o)
+    store().open(users)
+    expect(activeId()).toBe(u2)
+
+    store().activate(u1)
+    store().activate(o)
+    store().open(users)
+    expect(activeId()).toBe(u1)
+    assertInvariants()
+  })
+})
+
+describe('ordinals', () => {
+  it('reuses the smallest free number and never renumbers open tabs', () => {
+    const a = openNewId(users)
+    const b = openNewId(users)
+    const c = openNewId(users)
+    store().close(b)
+    const d = openNewId(users)
+    expect(tab(a).ordinal).toBe(1)
+    expect(tab(c).ordinal).toBe(3)
+    expect(tab(d).ordinal).toBe(2)
+    assertInvariants()
+  })
+
+  it('counts per collection and connection', () => {
+    openNewId(users)
+    expect(tab(openNewId(orders)).ordinal).toBe(1)
+    expect(tab(openNewId(remote)).ordinal).toBe(1)
+  })
+
+  it('ordinalLabel is null for a single tab and the ordinal when several share the collection', () => {
+    const a = openNewId(users)
+    openNewId(orders)
+    expect(ordinalLabel(store().tabs, tab(a))).toBeNull()
+    const b = openNewId(users)
+    expect(ordinalLabel(store().tabs, tab(a))).toBe(1)
+    expect(ordinalLabel(store().tabs, tab(b))).toBe(2)
+  })
+})
+
+describe('setDraft', () => {
+  it('changes only that draft and keeps the tabs array reference', () => {
+    const a = openNewId(users)
+    const b = openNewId(orders)
+    const tabsBefore = store().tabs
+    const otherBefore = draft(b)
+    store().setDraft(a, { filter: '{ a: 1 }' })
+    expect(draft(a).filter).toBe('{ a: 1 }')
+    expect(draft(b)).toBe(otherBefore)
+    expect(store().tabs).toBe(tabsBefore)
+    assertInvariants()
+  })
+
+  it('leaves the state identical for an unknown id', () => {
+    openNewId(users)
+    const before = store()
+    store().setDraft('t999', { filter: '{}' })
+    expect(store()).toBe(before)
+  })
+})
+
+describe('run', () => {
+  it('commits the simple draft and resets skip', () => {
+    const id = openNewId(users)
+    store().setSkip(id, 200)
+    store().setDraft(id, {
+      filter: '{ a: 1 }',
+      projection: '{ a: 1 }',
+      sort: '{ b: -1 }',
+      limit: '25'
+    })
+    store().run(id)
+    expect(tab(id).applied.simple).toMatchObject({
+      filter: '{ a: 1 }',
+      projection: '{ a: 1 }',
+      sort: '{ b: -1 }',
+      skip: 0,
+      limit: 25
+    })
+    expect(isDraftDirty(draft(id), tab(id).applied)).toBe(false)
+  })
+
+  it('commits only the visible mode', () => {
+    const id = openNewId(users)
+    const simpleBefore = tab(id).applied.simple
+    store().setDraft(id, {
+      mode: 'aggregation',
+      pipeline: '[{ $match: {} }]',
+      shell: 'db.x.find()'
+    })
+    store().run(id)
+    expect(tab(id).applied.simple).toBe(simpleBefore)
+    expect(tab(id).applied.aggregation).toEqual({
+      source: '[{ $match: {} }]',
+      epoch: expect.any(Number)
+    })
+    expect(tab(id).applied.shell).toBeNull()
+
+    store().setDraft(id, { mode: 'shell' })
+    store().run(id)
+    expect(tab(id).applied.shell?.source).toBe('db.x.find()')
+  })
+
+  it('issues strictly increasing epochs that are unique across tabs', () => {
+    const a = openNewId(users)
+    const b = openNewId(users)
+    const epochs = [tab(a).applied.simple.epoch, tab(b).applied.simple.epoch]
+    store().run(a)
+    epochs.push(tab(a).applied.simple.epoch)
+    store().run(b)
+    epochs.push(tab(b).applied.simple.epoch)
+    store().setDraft(a, { mode: 'aggregation' })
+    store().run(a)
+    epochs.push(tab(a).applied.aggregation?.epoch ?? -1)
+    for (let i = 1; i < epochs.length; i++) {
+      expect(epochs[i]).toBeGreaterThan(epochs[i - 1] ?? Infinity)
+    }
+  })
+
+  it.each<[string, number]>([
+    ['', 0],
+    ['0', 0],
+    ['25', 25],
+    ['abc', 0],
+    ['-5', 0]
+  ])('parses limit %j as %i', (limit, expected) => {
+    const id = openNewId(users)
+    store().setDraft(id, { limit })
+    store().run(id)
+    expect(tab(id).applied.simple.limit).toBe(expected)
+  })
+
+  it('returns the run it committed', () => {
+    const id = openNewId(users)
+    expect(store().run(id)).toBe(tab(id).applied.simple)
+    store().setDraft(id, { mode: 'shell', shell: 'db.users.deleteMany({})' })
+    const committed = store().run(id)
+    expect(committed).toEqual({ source: 'db.users.deleteMany({})', epoch: expect.any(Number) })
+    expect(committed).toBe(tab(id).applied.shell)
+  })
+
+  it('ignores an unknown id', () => {
+    openNewId(users)
+    const before = store()
+    expect(store().run('t999')).toBeNull()
+    expect(store()).toBe(before)
+  })
+})
+
+describe('mode switch', () => {
+  it('never changes the applied queries', () => {
+    const id = openNewId(users)
+    const appliedBefore = tab(id).applied
+    store().setDraft(id, { mode: 'aggregation' })
+    store().setDraft(id, { mode: 'shell' })
+    expect(tab(id).applied).toBe(appliedBefore)
+  })
+
+  it('is dirty only when the visible mode differs from its own last run', () => {
+    const id = openNewId(users)
+    store().setDraft(id, { mode: 'aggregation' })
+    expect(isDraftDirty(draft(id), tab(id).applied)).toBe(false)
+    store().setDraft(id, { pipeline: '[]' })
+    expect(isDraftDirty(draft(id), tab(id).applied)).toBe(true)
+    store().run(id)
+    expect(isDraftDirty(draft(id), tab(id).applied)).toBe(false)
+  })
+})
+
+describe('isDraftDirty', () => {
+  const applied: AppliedQueries = {
+    simple: { filter: '{}', projection: '{}', sort: '{}', skip: 40, limit: 100, epoch: 7 },
+    aggregation: { source: '[{ $limit: 1 }]', epoch: 8 },
+    shell: null
+  }
+  const clean: QueryDraft = {
+    mode: 'simple',
+    filter: '{}',
+    projection: '{}',
+    sort: '{}',
+    pipeline: '[{ $limit: 1 }]',
+    shell: '',
+    limit: '100'
+  }
+
+  it('compares the limit by its parsed value and ignores skip and epoch', () => {
+    expect(isDraftDirty(clean, applied)).toBe(false)
+    expect(isDraftDirty({ ...clean, limit: '0100' }, applied)).toBe(false)
+  })
+
+  it.each(['filter', 'projection', 'sort'] as const)('simple: %s text makes it dirty', (field) => {
+    expect(isDraftDirty({ ...clean, [field]: '{ a: 1 }' }, applied)).toBe(true)
+  })
+
+  it('simple: a different limit makes it dirty', () => {
+    expect(isDraftDirty({ ...clean, limit: '' }, applied)).toBe(true)
+  })
+
+  it('ignores the drafts of hidden modes', () => {
+    expect(isDraftDirty({ ...clean, pipeline: '[]', shell: 'db.a.find()' }, applied)).toBe(false)
+  })
+
+  it('aggregation and shell compare their source, an unrun mode against empty text', () => {
+    expect(isDraftDirty({ ...clean, mode: 'aggregation' }, applied)).toBe(false)
+    expect(isDraftDirty({ ...clean, mode: 'aggregation', pipeline: '[]' }, applied)).toBe(true)
+    expect(isDraftDirty({ ...clean, mode: 'shell' }, applied)).toBe(false)
+    expect(isDraftDirty({ ...clean, mode: 'shell', shell: 'db.a.find()' }, applied)).toBe(true)
+  })
+})
+
+describe('setSkip', () => {
+  it('pages the simple query and keeps its epoch', () => {
+    const id = openNewId(users)
+    const before = tab(id).applied.simple
+    store().setSkip(id, 300)
+    expect(tab(id).applied.simple).toEqual({ ...before, skip: 300 })
+  })
+
+  it('leaves aggregation and shell runs untouched', () => {
+    const id = openNewId(users)
+    store().setDraft(id, { mode: 'aggregation', pipeline: '[]' })
+    store().run(id)
+    const aggregation = tab(id).applied.aggregation
+    store().setSkip(id, 100)
+    expect(tab(id).applied.aggregation).toBe(aggregation)
+  })
+
+  it('ignores an unknown id', () => {
+    openNewId(users)
+    const before = store()
+    store().setSkip('t999', 100)
+    expect(store()).toBe(before)
+  })
+})
+
+describe('duplicate', () => {
+  it('inserts an active copy right after the source', () => {
+    const a = openNewId(users)
+    const b = openNewId(orders)
+    store().duplicate(a)
+    const copy = activeId()
+    expect(store().tabs.map((t) => t.id)).toEqual([a, copy, b])
+    expect(tab(copy)).toMatchObject({ ...users, ordinal: 2 })
+    assertInvariants()
+  })
+
+  it('copies the draft and the simple query, sharing its epoch', () => {
+    const a = openNewId(users)
+    store().setDraft(a, { filter: '{ a: 1 }', limit: '5' })
+    store().run(a)
+    store().setDraft(a, { filter: '{ a: 2 }' })
+    const sourceDraft = draft(a)
+    const sourceApplied = tab(a).applied
+    store().duplicate(a)
+    const copy = activeId()
+    expect(draft(copy)).toEqual(sourceDraft)
+    expect(draft(copy)).not.toBe(sourceDraft)
+    expect(tab(copy).applied.simple).toEqual(sourceApplied.simple)
+    expect(draft(a)).toBe(sourceDraft)
+    expect(tab(a).applied).toBe(sourceApplied)
+  })
+
+  it('does not copy aggregation or shell runs', () => {
+    const a = openNewId(users)
+    store().setDraft(a, { mode: 'aggregation', pipeline: '[{ $count: "n" }]' })
+    store().run(a)
+    store().setDraft(a, { mode: 'shell', shell: 'db.users.find()' })
+    store().run(a)
+    store().duplicate(a)
+    const copy = activeId()
+    expect(tab(copy).applied.aggregation).toBeNull()
+    expect(tab(copy).applied.shell).toBeNull()
+    expect(draft(copy).shell).toBe('db.users.find()')
+  })
+
+  it('ignores an unknown id', () => {
+    openNewId(users)
+    const before = store()
+    store().duplicate('t999')
+    expect(store()).toBe(before)
+  })
+})
+
+describe('openWithFilter', () => {
+  const lookup = '{ _id: ObjectId("65a1b2c3d4e5f60718293a4b") }'
+
+  it('opens a new applied simple tab instead of touching a dirty tab', () => {
+    const a = openNewId(users)
+    store().setDraft(a, { filter: '{ name: "x" }' })
+    const aDraft = draft(a)
+    const aApplied = tab(a).applied
+    store().openWithFilter(users, lookup)
+    const b = activeId()
+    expect(b).not.toBe(a)
+    expect(draft(b)).toMatchObject({ mode: 'simple', filter: lookup, projection: '{}', sort: '{}' })
+    expect(tab(b).applied.simple).toMatchObject({ filter: lookup, projection: '{}', skip: 0 })
+    expect(isDraftDirty(draft(b), tab(b).applied)).toBe(false)
+    expect(draft(a)).toBe(aDraft)
+    expect(tab(a).applied).toBe(aApplied)
+    assertInvariants()
+  })
+
+  it('never reuses a tab that shows another mode', () => {
+    const a = openNewId(users)
+    store().setDraft(a, { mode: 'aggregation' })
+    store().openWithFilter(users, '{}')
+    expect(activeId()).not.toBe(a)
+    expect(draft(a).mode).toBe('aggregation')
+  })
+
+  it('reuses the lookup tab with a fresh epoch on a repeated lookup', () => {
+    store().openWithFilter(users, lookup)
+    const b = activeId()
+    const epoch = tab(b).applied.simple.epoch
+    openNewId(orders)
+    store().openWithFilter(users, lookup)
+    expect(activeId()).toBe(b)
+    expect(store().tabs).toHaveLength(2)
+    expect(tab(b).applied.simple.epoch).toBeGreaterThan(epoch)
+    assertInvariants()
+  })
+
+  it('opens another tab once the lookup tab was edited', () => {
+    store().openWithFilter(users, lookup)
+    const b = activeId()
+    store().setDraft(b, { sort: '{ a: 1 }' })
+    store().openWithFilter(users, lookup)
+    expect(activeId()).not.toBe(b)
+    expect(store().tabs).toHaveLength(2)
+  })
+})
+
+describe('close', () => {
+  it('removes the draft and moves to the right neighbour, stamped as active', () => {
+    const a = openNewId(users)
+    const b = openNewId(orders)
+    const c = openNewId(logs)
+    store().activate(b)
+    store().close(b)
+    expect(activeId()).toBe(c)
+    expect(store().drafts[b]).toBeUndefined()
+    assertInvariants()
+    store().close(c)
+    expect(activeId()).toBe(a)
+    assertInvariants()
+  })
+
+  it('keeps the active tab when closing another one', () => {
+    const a = openNewId(users)
+    const b = openNewId(orders)
+    store().close(a)
+    expect(activeId()).toBe(b)
+    assertInvariants()
+  })
+
+  it('leaves no active tab after the last one closes', () => {
+    const a = openNewId(users)
+    store().close(a)
+    expect(store().activeTabId).toBeNull()
+    assertInvariants()
+  })
+
+  it('ignores an unknown id', () => {
+    openNewId(users)
+    const before = store()
+    store().close('t999')
+    expect(store()).toBe(before)
+  })
+})
+
+describe('closeFor*', () => {
+  it('closeForCollection removes every tab of the collection and falls back to the first tab', () => {
+    const o = openNewId(orders)
+    openNewId(users)
+    openNewId(users)
+    store().closeForCollection(users.connectionId, users.db, users.coll)
+    expect(store().tabs.map((t) => t.id)).toEqual([o])
+    expect(activeId()).toBe(o)
+    assertInvariants()
+  })
+
+  it('closeForDatabase removes the tabs of that database only', () => {
+    const l = openNewId(logs)
+    openNewId(users)
+    openNewId(orders)
+    const r = openNewId(remote)
+    store().closeForDatabase('c1', 'app')
+    expect(store().tabs.map((t) => t.id)).toEqual([l, r])
+    expect(activeId()).toBe(r)
+    assertInvariants()
+  })
+
+  it('closeForConnection removes the tabs of that connection only', () => {
+    openNewId(users)
+    const r = openNewId(remote)
+    openNewId(logs)
+    store().closeForConnection('c1')
+    expect(store().tabs.map((t) => t.id)).toEqual([r])
+    expect(activeId()).toBe(r)
+    assertInvariants()
+  })
+
+  it('returns the identical state when nothing matches', () => {
+    openNewId(users)
+    const before = store()
+    store().closeForConnection('c9')
+    store().closeForDatabase('c1', 'nope')
+    store().closeForCollection('c1', 'app', 'nope')
+    expect(store()).toBe(before)
+  })
+})
+
+describe('renameCollection', () => {
+  it('keeps ids, drafts, ordinals and the active tab', () => {
+    const a = openNewId(users)
+    const b = openNewId(users)
+    store().setDraft(a, { filter: '{ a: 1 }' })
+    const drafts = store().drafts
+    store().renameCollection('c1', 'app', 'users', 'members')
+    expect(tab(a)).toMatchObject({ coll: 'members', ordinal: 1 })
+    expect(tab(b)).toMatchObject({ coll: 'members', ordinal: 2 })
+    expect(store().drafts).toBe(drafts)
+    expect(activeId()).toBe(b)
+    assertInvariants()
+  })
+
+  it('renumbers only on a collision with a stale tab of the new name', () => {
+    const stale = openNewId({ ...users, coll: 'members' })
+    const a = openNewId(users)
+    const b = openNewId(users)
+    store().renameCollection('c1', 'app', 'users', 'members')
+    expect(tab(stale).ordinal).toBe(1)
+    expect(tab(a).ordinal).toBe(3)
+    expect(tab(b).ordinal).toBe(2)
+    assertInvariants()
+  })
+
+  it('leaves other connections and databases alone', () => {
+    const r = openNewId(remote)
+    store().renameCollection('c1', 'app', 'users', 'members')
+    expect(tab(r).coll).toBe('users')
+  })
+
+  it('leaves the applied pipeline idle and keeps the draft, so only Run executes it again', () => {
+    const a = openNewId(users)
+    store().setDraft(a, { mode: 'shell', shell: 'db.users.find()' })
+    store().run(a)
+    store().setDraft(a, { mode: 'aggregation', pipeline: '[{ $count: "n" }]' })
+    store().run(a)
+    const { simple, shell } = tab(a).applied
+    store().renameCollection('c1', 'app', 'users', 'members')
+    expect(tab(a).applied).toEqual({ simple, aggregation: null, shell })
+    expect(draft(a).pipeline).toBe('[{ $count: "n" }]')
+    expect(isDraftDirty(draft(a), tab(a).applied)).toBe(true)
+  })
+
+  it('also leaves the pipeline of a renumbered tab idle', () => {
+    openNewId({ ...users, coll: 'members' })
+    const a = openNewId(users)
+    store().setDraft(a, { mode: 'aggregation', pipeline: '[]' })
+    store().run(a)
+    store().renameCollection('c1', 'app', 'users', 'members')
+    expect(tab(a)).toMatchObject({ ordinal: 2, applied: { aggregation: null } })
+  })
+})
+
+describe('activate', () => {
+  it('stamps the tab as most recently active', () => {
+    const a = openNewId(users)
+    openNewId(orders)
+    store().activate(a)
+    expect(activeId()).toBe(a)
+    assertInvariants()
+  })
+
+  it('returns the identical state for an unknown or already active tab', () => {
+    const a = openNewId(users)
+    const before = store()
+    store().activate('t999')
+    store().activate(a)
+    expect(store()).toBe(before)
+  })
+})
+
+describe('activeCollectionKey', () => {
+  it('is the key of the active tab collection only', () => {
+    expect(activeCollectionKey(store())).toBeNull()
+    const a = openNewId(users)
+    openNewId(orders)
+    expect(activeCollectionKey(store())).toBe(collectionKey(orders))
+    expect(activeCollectionKey(store())).not.toBe(collectionKey(users))
+    expect(activeCollectionKey(store())).not.toBe(collectionKey({ ...orders, connectionId: 'c2' }))
+    store().activate(a)
+    expect(activeCollectionKey(store())).toBe(collectionKey(users))
+    store().closeForConnection('c1')
+    expect(activeCollectionKey(store())).toBeNull()
+  })
+
+  it('keeps names with separators apart', () => {
+    expect(collectionKey({ connectionId: 'c1', db: 'a', coll: 'b.c' })).not.toBe(
+      collectionKey({ connectionId: 'c1', db: 'a.b', coll: 'c' })
+    )
+  })
+})
diff --git a/src/renderer/src/store/tabs.ts b/src/renderer/src/store/tabs.ts
index e903fc4..c903225 100644
--- a/src/renderer/src/store/tabs.ts
+++ b/src/renderer/src/store/tabs.ts
@@ -1,153 +1,403 @@
 import { create } from 'zustand'
+import type { CollectionRef } from '@shared/types'
 
 export type QueryMode = 'simple' | 'aggregation' | 'shell'
 
-export type CollectionTab = {
-  id: string
-  connectionId: string
-  db: string
-  coll: string
-  /** Which input surface is active for this tab. */
+/** Editor contents of a tab; nothing here has been executed. */
+export type QueryDraft = {
+  /** Visible input surface; switching it never runs a query. */
   mode: QueryMode
   filter: string
-  /** EJSON object string. Empty = no projection. */
   projection: string
-  /** EJSON object string. Empty = no explicit sort. */
   sort: string
-  /** Aggregation pipeline source (mongosh-flavoured array, e.g. `[{ $match: ... }]`). */
   pipeline: string
-  /** Shell command source (e.g. `db.coll.find({...}).limit(10)`). */
   shell: string
+  /** Raw limit input; empty, 0 or unparsable = no limit. */
+  limit: string
+}
+
+export type AppliedSimple = {
+  filter: string
+  projection: string
+  sort: string
   skip: number
-  /** 0 = no limit (return all matching documents). */
+  /** 0 = no limit. */
   limit: number
-  /**
-   * Bumped on every explicit Run. Part of the active query's queryKey so
-   * pressing Run with unchanged params still refetches, while a tab
-   * re-mount (switching back to this tab) does not.
-   */
-  runEpoch: number
+  /** Unique across all tabs and runs; part of the result key, so Run always refetches. */
+  epoch: number
 }
 
-export type QueryPatch = Partial<
-  Pick<
-    CollectionTab,
-    'mode' | 'filter' | 'projection' | 'sort' | 'pipeline' | 'shell' | 'skip' | 'limit' | 'runEpoch'
-  >
->
+/** Source text of an aggregation / shell run; compiled where it executes. */
+export type AppliedSource = { source: string; epoch: number }
 
-const DEFAULT_LIMIT = 100
+/** Last executed query of each mode; results, paging and counts derive only from these. */
+export type AppliedQueries = {
+  simple: AppliedSimple
+  aggregation: AppliedSource | null
+  shell: AppliedSource | null
+}
 
-const tabId = (connectionId: string, db: string, coll: string): string =>
-  `${connectionId}::${db}::${coll}`
+export type CollectionTab = CollectionRef & {
+  /** `t<seq>`; URI-safe, used in Monaco model URIs and tab-owned result keys. */
+  id: string
+  /** Stable 1-based number among open tabs of the same collection. */
+  ordinal: number
+  /** `seq` of the last activation; the active tab always holds the highest. */
+  lastActive: number
+  applied: AppliedQueries
+}
 
 type TabsState = {
   tabs: CollectionTab[]
+  /** Per tab id, written together with the tab; kept apart so typing leaves `tabs` untouched. */
+  drafts: Record<string, QueryDraft>
   activeTabId: string | null
-  /**
-   * Open or focus the tab for the given collection. When `filter` is provided,
-   * a freshly opened tab starts with that filter, and an existing tab's filter
-   * is overwritten (with `skip` reset). Used by features like cross-collection
-   * ObjectId lookup that need to drop the user into a pre-filtered view.
-   */
-  open: (params: { connectionId: string; db: string; coll: string; filter?: string }) => void
+  /** Monotonic source of tab ids, activation order and run epochs. */
+  seq: number
+  /** Focuses the most recently active tab of the collection, or opens one. */
+  open: (target: CollectionRef) => void
+  /** Always opens a new blank tab. */
+  openNew: (target: CollectionRef) => void
+  /** Shows `filter` in simple mode; never changes another tab's draft or applied query. */
+  openWithFilter: (target: CollectionRef, filter: string) => void
+  /** Copies the draft and the simple query into a new tab right after the source. */
+  duplicate: (id: string) => void
   close: (id: string) => void
   activate: (id: string) => void
-  setQuery: (id: string, patch: QueryPatch) => void
+  setDraft: (id: string, patch: Partial<QueryDraft>) => void
+  /**
+   * Commits the draft of the visible mode with a fresh epoch; the only action that executes.
+   * @returns The committed run; null for an unknown tab.
+   */
+  run: (id: string) => AppliedSimple | AppliedSource | null
+  /** Pages the simple query; keeps its epoch so the count is reused. */
+  setSkip: (id: string, skip: number) => void
   closeForConnection: (connectionId: string) => void
   closeForCollection: (connectionId: string, db: string, coll: string) => void
   closeForDatabase: (connectionId: string, db: string) => void
   renameCollection: (connectionId: string, db: string, oldName: string, newName: string) => void
 }
 
-export const useTabsStore = create<TabsState>((set) => ({
+const DEFAULT_LIMIT = 100
+
+const DEFAULT_DRAFT: QueryDraft = {
+  mode: 'simple',
+  filter: '{}',
+  projection: '{}',
+  sort: '{}',
+  pipeline: '',
+  shell: '',
+  limit: String(DEFAULT_LIMIT)
+}
+
+const sameCollection = (a: CollectionRef, b: CollectionRef): boolean =>
+  a.connectionId === b.connectionId && a.db === b.db && a.coll === b.coll
+
+function parseLimit(text: string): number {
+  const n = Number.parseInt(text, 10)
+  return Number.isFinite(n) && n > 0 ? n : 0
+}
+
+function commitSimple(draft: QueryDraft, epoch: number): AppliedSimple {
+  return {
+    filter: draft.filter,
+    projection: draft.projection,
+    sort: draft.sort,
+    skip: 0,
+    limit: parseLimit(draft.limit),
+    epoch
+  }
+}
+
+function commitDraft(applied: AppliedQueries, draft: QueryDraft, epoch: number): AppliedQueries {
+  switch (draft.mode) {
+    case 'simple':
+      return { ...applied, simple: commitSimple(draft, epoch) }
+    case 'aggregation':
+      return { ...applied, aggregation: { source: draft.pipeline, epoch } }
+    case 'shell':
+      return { ...applied, shell: { source: draft.shell, epoch } }
+  }
+}
+
+const simpleOnly =
+  (draft: QueryDraft) =>
+  (epoch: number): AppliedQueries => ({
+    simple: commitSimple(draft, epoch),
+    aggregation: null,
+    shell: null
+  })
+
+function draftsEqual(a: QueryDraft, b: QueryDraft): boolean {
+  return (
+    a.mode === b.mode &&
+    a.filter === b.filter &&
+    a.projection === b.projection &&
+    a.sort === b.sort &&
+    a.pipeline === b.pipeline &&
+    a.shell === b.shell &&
+    a.limit === b.limit
+  )
+}
+
+function nextOrdinal(tabs: readonly CollectionTab[], ref: CollectionRef): number {
+  const used = new Set(tabs.filter((t) => sameCollection(t, ref)).map((t) => t.ordinal))
+  let n = 1
+  while (used.has(n)) n++
+  return n
+}
+
+function mostRecent(tabs: readonly CollectionTab[]): CollectionTab | undefined {
+  let best: CollectionTab | undefined
+  for (const t of tabs) if (!best || t.lastActive > best.lastActive) best = t
+  return best
+}
+
+function stampActive(s: TabsState, id: string): TabsState {
+  if (id === s.activeTabId) return s
+  const seq = s.seq + 1
+  return {
+    ...s,
+    seq,
+    activeTabId: id,
+    tabs: s.tabs.map((t) => (t.id === id ? { ...t, lastActive: seq } : t))
+  }
+}
+
+function addTab(
+  s: TabsState,
+  target: CollectionRef,
+  draft: QueryDraft,
+  applied: (epoch: number) => AppliedQueries,
+  insertAt = s.tabs.length
+): TabsState {
+  // One seq supplies the id, the activation stamp and the epoch of the initial run.
+  const seq = s.seq + 1
+  const tab: CollectionTab = {
+    id: `t${seq}`,
+    connectionId: target.connectionId,
+    db: target.db,
+    coll: target.coll,
+    ordinal: nextOrdinal(s.tabs, target),
+    lastActive: seq,
+    applied: applied(seq)
+  }
+  return {
+    ...s,
+    seq,
+    tabs: [...s.tabs.slice(0, insertAt), tab, ...s.tabs.slice(insertAt)],
+    drafts: { ...s.drafts, [tab.id]: draft },
+    activeTabId: tab.id
+  }
+}
+
+function removeTabs(
+  s: TabsState,
+  removed: (tab: CollectionTab) => boolean,
+  fallback: (remaining: CollectionTab[]) => CollectionTab | undefined
+): TabsState {
+  const tabs = s.tabs.filter((t) => !removed(t))
+  if (tabs.length === s.tabs.length) return s
+  const drafts: Record<string, QueryDraft> = {}
+  for (const t of tabs) {
+    const draft = s.drafts[t.id]
+    if (draft) drafts[t.id] = draft
+  }
+  const next = { ...s, tabs, drafts }
+  if (tabs.some((t) => t.id === s.activeTabId)) return next
+  const target = fallback(tabs)
+  return target ? stampActive(next, target.id) : { ...next, activeTabId: null }
+}
+
+/** Whether the visible mode's draft differs from that mode's last run (skip and epoch ignored). */
+export function isDraftDirty(draft: QueryDraft, applied: AppliedQueries): boolean {
+  switch (draft.mode) {
+    case 'simple':
+      return (
+        draft.filter !== applied.simple.filter ||
+        draft.projection !== applied.simple.projection ||
+        draft.sort !== applied.simple.sort ||
+        parseLimit(draft.limit) !== applied.simple.limit
+      )
+    case 'aggregation':
+      return draft.pipeline !== (applied.aggregation?.source ?? '')
+    case 'shell':
+      return draft.shell !== (applied.shell?.source ?? '')
+  }
+}
+
+/** The tab's ordinal while another open tab shows the same collection, else null. */
+export function ordinalLabel(tabs: readonly CollectionTab[], tab: CollectionTab): number | null {
+  return tabs.some((t) => t.id !== tab.id && sameCollection(t, tab)) ? tab.ordinal : null
+}
+
+/** Equal for the same collection of the same connection. */
+export const collectionKey = (ref: CollectionRef): string =>
+  JSON.stringify([ref.connectionId, ref.db, ref.coll])
+
+let activeKeyMemo: {
+  tabs: readonly CollectionTab[]
+  activeTabId: string | null
+  key: string | null
+} | null = null
+
+/** Store selector: `collectionKey` of the active tab's collection; null without tabs. */
+export function activeCollectionKey(s: {
+  tabs: readonly CollectionTab[]
+  activeTabId: string | null
+}): string | null {
+  // Every explorer leaf selects this on every store change, typing included; one lookup serves all.
+  if (activeKeyMemo?.tabs !== s.tabs || activeKeyMemo.activeTabId !== s.activeTabId) {
+    const active = s.tabs.find((t) => t.id === s.activeTabId)
+    activeKeyMemo = {
+      tabs: s.tabs,
+      activeTabId: s.activeTabId,
+      key: active ? collectionKey(active) : null
+    }
+  }
+  return activeKeyMemo.key
+}
+
+export const useTabsStore = create<TabsState>((set, get) => ({
   tabs: [],
+  drafts: {},
   activeTabId: null,
-  open: ({ connectionId, db, coll, filter }) =>
-    set((state) => {
-      const id = tabId(connectionId, db, coll)
-      const existing = state.tabs.find((t) => t.id === id)
-      if (existing) {
-        if (filter !== undefined && filter !== existing.filter) {
-          return {
-            tabs: state.tabs.map((t) => (t.id === id ? { ...t, filter, skip: 0 } : t)),
-            activeTabId: id
-          }
-        }
-        return { activeTabId: id }
-      }
-      const tab: CollectionTab = {
-        id,
-        connectionId,
-        db,
-        coll,
-        mode: 'simple',
-        filter: filter ?? '',
-        projection: '',
-        sort: '',
-        pipeline: '',
-        shell: '',
-        skip: 0,
-        limit: DEFAULT_LIMIT,
-        runEpoch: 0
+  seq: 0,
+  open: (target) =>
+    set((s) => {
+      const existing = mostRecent(s.tabs.filter((t) => sameCollection(t, target)))
+      return existing
+        ? stampActive(s, existing.id)
+        : addTab(s, target, DEFAULT_DRAFT, simpleOnly(DEFAULT_DRAFT))
+    }),
+  openNew: (target) => set((s) => addTab(s, target, DEFAULT_DRAFT, simpleOnly(DEFAULT_DRAFT))),
+  openWithFilter: (target, filter) =>
+    set((s) => {
+      const draft: QueryDraft = { ...DEFAULT_DRAFT, filter }
+      const reusable = mostRecent(
+        s.tabs.filter((t) => {
+          const current = s.drafts[t.id]
+          return (
+            sameCollection(t, target) &&
+            current !== undefined &&
+            draftsEqual(current, draft) &&
+            !isDraftDirty(current, t.applied)
+          )
+        })
+      )
+      if (!reusable) return addTab(s, target, draft, simpleOnly(draft))
+      // A repeated lookup re-runs its tab instead of piling up new ones.
+      const seq = s.seq + 1
+      return {
+        seq,
+        activeTabId: reusable.id,
+        tabs: s.tabs.map((t) =>
+          t.id === reusable.id
+            ? { ...t, lastActive: seq, applied: { ...t.applied, simple: commitSimple(draft, seq) } }
+            : t
+        )
       }
-      return { tabs: [...state.tabs, tab], activeTabId: id }
+    }),
+  duplicate: (id) =>
+    set((s) => {
+      const idx = s.tabs.findIndex((t) => t.id === id)
+      const source = s.tabs[idx]
+      const draft = s.drafts[id]
+      if (!source || !draft) return s
+      // Agg/shell results are keyed by tab id; copying those runs would silently re-execute them.
+      return addTab(
+        s,
+        source,
+        { ...draft },
+        () => ({ simple: { ...source.applied.simple }, aggregation: null, shell: null }),
+        idx + 1
+      )
     }),
   close: (id) =>
-    set((state) => {
-      const idx = state.tabs.findIndex((t) => t.id === id)
-      if (idx === -1) return state
-      const remaining = state.tabs.filter((t) => t.id !== id)
-      let nextActive = state.activeTabId
-      if (state.activeTabId === id) {
-        nextActive = remaining[idx]?.id ?? remaining[idx - 1]?.id ?? null
-      }
-      return { tabs: remaining, activeTabId: nextActive }
+    set((s) => {
+      const idx = s.tabs.findIndex((t) => t.id === id)
+      return removeTabs(
+        s,
+        (t) => t.id === id,
+        (remaining) => remaining[idx] ?? remaining[idx - 1]
+      )
     }),
-  activate: (id) => set({ activeTabId: id }),
-  setQuery: (id, patch) =>
-    set((state) => ({
-      tabs: state.tabs.map((t) => (t.id === id ? { ...t, ...patch } : t))
-    })),
-  closeForConnection: (connectionId) =>
-    set((state) => {
-      const remaining = state.tabs.filter((t) => t.connectionId !== connectionId)
-      const stillActive = remaining.some((t) => t.id === state.activeTabId)
+  activate: (id) => set((s) => (s.tabs.some((t) => t.id === id) ? stampActive(s, id) : s)),
+  setDraft: (id, patch) =>
+    set((s) => {
+      const draft = s.drafts[id]
+      return draft ? { drafts: { ...s.drafts, [id]: { ...draft, ...patch } } } : s
+    }),
+  run: (id) => {
+    const s = get()
+    const draft = s.drafts[id]
+    const tab = s.tabs.find((t) => t.id === id)
+    if (!draft || !tab) return null
+    const seq = s.seq + 1
+    const applied = commitDraft(tab.applied, draft, seq)
+    set({ seq, tabs: s.tabs.map((t) => (t.id === id ? { ...t, applied } : t)) })
+    return applied[draft.mode]
+  },
+  setSkip: (id, skip) =>
+    set((s) => {
+      if (!s.tabs.some((t) => t.id === id)) return s
       return {
-        tabs: remaining,
-        activeTabId: stillActive ? state.activeTabId : (remaining[0]?.id ?? null)
+        tabs: s.tabs.map((t) =>
+          t.id === id
+            ? { ...t, applied: { ...t.applied, simple: { ...t.applied.simple, skip } } }
+            : t
+        )
       }
     }),
+  closeForConnection: (connectionId) =>
+    set((s) =>
+      removeTabs(
+        s,
+        (t) => t.connectionId === connectionId,
+        (remaining) => remaining[0]
+      )
+    ),
   closeForCollection: (connectionId, db, coll) =>
-    set((state) => {
-      const remaining = state.tabs.filter(
-        (t) => !(t.connectionId === connectionId && t.db === db && t.coll === coll)
+    set((s) =>
+      removeTabs(
+        s,
+        (t) => sameCollection(t, { connectionId, db, coll }),
+        (remaining) => remaining[0]
       )
-      const stillActive = remaining.some((t) => t.id === state.activeTabId)
-      return {
-        tabs: remaining,
-        activeTabId: stillActive ? state.activeTabId : (remaining[0]?.id ?? null)
-      }
-    }),
+    ),
   closeForDatabase: (connectionId, db) =>
-    set((state) => {
-      const remaining = state.tabs.filter((t) => !(t.connectionId === connectionId && t.db === db))
-      const stillActive = remaining.some((t) => t.id === state.activeTabId)
-      return {
-        tabs: remaining,
-        activeTabId: stillActive ? state.activeTabId : (remaining[0]?.id ?? null)
-      }
-    }),
+    set((s) =>
+      removeTabs(
+        s,
+        (t) => t.connectionId === connectionId && t.db === db,
+        (remaining) => remaining[0]
+      )
+    ),
   renameCollection: (connectionId, db, oldName, newName) =>
-    set((state) => {
-      const oldId = tabId(connectionId, db, oldName)
-      const newId = tabId(connectionId, db, newName)
-      let activeTabId = state.activeTabId
-      const tabs = state.tabs.map((t) => {
-        if (t.connectionId !== connectionId || t.db !== db || t.coll !== oldName) return t
-        if (state.activeTabId === oldId) activeTabId = newId
-        return { ...t, id: newId, coll: newName }
+    set((s) => {
+      const from = { connectionId, db, coll: oldName }
+      const to = { connectionId, db, coll: newName }
+      if (!s.tabs.some((t) => sameCollection(t, from))) return s
+      // The kept result writes to the old name and a new-name key would re-run it: wait for Run.
+      const moved = (t: CollectionTab): CollectionTab => ({
+        ...t,
+        coll: newName,
+        applied: { ...t.applied, aggregation: null }
       })
-      return { tabs, activeTabId }
+      // Numbers held by stale tabs of the new name; only renamed tabs that collide renumber.
+      const taken = new Set(
+        s.tabs
+          .filter((t) => sameCollection(t, to) && !sameCollection(t, from))
+          .map((t) => t.ordinal)
+      )
+      let tabs = s.tabs.map((t) =>
+        sameCollection(t, from) && !taken.has(t.ordinal) ? moved(t) : t
+      )
+      for (const t of s.tabs) {
+        if (!sameCollection(t, from) || !taken.has(t.ordinal)) continue
+        const renamed = { ...moved(t), ordinal: nextOrdinal(tabs, to) }
+        tabs = tabs.map((x) => (x.id === t.id ? renamed : x))
+      }
+      return { tabs }
     })
 }))
diff --git a/src/shared/api.ts b/src/shared/api.ts
index f442e9d..294fe0f 100644
--- a/src/shared/api.ts
+++ b/src/shared/api.ts
@@ -1,7 +1,9 @@
 import type {
   AggregateRequest,
   AggregateResponse,
+  CancelQueryRequest,
   CollectionInfo,
+  CollectionSchema,
   CollectionStats,
   ConnectionConfig,
   ConnectionInput,
@@ -13,16 +15,20 @@ import type {
   CreateIndexPayload,
   CreateUserPayload,
   DatabaseInfo,
+  DatabaseRoleInfo,
   DatabaseUser,
   DeleteManyRequest,
   DeleteManyResponse,
   DeleteOneRequest,
   DeleteOneResponse,
+  DistinctRequest,
+  DistinctResponse,
   DropIndexPayload,
   DropUserPayload,
   FindRequest,
   FindResponse,
   IndexInfo,
+  IndexStatsReport,
   InsertManyRequest,
   InsertManyResponse,
   InsertOneRequest,
@@ -31,9 +37,16 @@ import type {
   ReplaceOneRequest,
   ReplaceOneResponse,
   ServerStats,
-  UpdateUserPayload
+  UpdateUserPayload,
+  WriteRequest,
+  WriteResponse
 } from './types'
-import type { ConnectionDropped, UpdateCheckResult, UpdateProgress } from './events'
+import type {
+  CloudflaredLoginPrompt,
+  ConnectionDropped,
+  UpdateCheckResult,
+  UpdateProgress
+} from './events'
 import type { Result } from './result'
 
 /**
@@ -60,9 +73,18 @@ export type Api = {
     onDropped: (listener: (payload: ConnectionDropped) => void) => () => void
   }
 
+  cloudflared: {
+    /** Version of the cloudflared that would run; omit the path to use PATH. */
+    version: (binaryPath?: string) => Promise<Result<string>>
+    /** cloudflared waits for (or finished) a browser sign-in. Returns an unsubscribe. */
+    onLogin: (listener: (prompt: CloudflaredLoginPrompt) => void) => () => void
+  }
+
   dialog: {
     /** Absolute path, or null when the user cancelled. */
     pickPrivateKey: () => Promise<Result<string | null>>
+    /** Absolute path, or null when the user cancelled. */
+    pickCloudflared: () => Promise<Result<string | null>>
   }
 
   databases: {
@@ -89,6 +111,12 @@ export type Api = {
     create: (payload: { connectionId: string; db: string; name: string }) => Promise<Result<void>>
     drop: (payload: { connectionId: string; db: string; coll: string }) => Promise<Result<void>>
     rename: (payload: RenameCollectionPayload) => Promise<Result<void>>
+    /** Field schema inferred from a random sample of the collection's documents. */
+    schema: (payload: {
+      connectionId: string
+      db: string
+      coll: string
+    }) => Promise<Result<CollectionSchema>>
   }
 
   query: {
@@ -100,6 +128,11 @@ export type Api = {
     insertMany: (request: InsertManyRequest) => Promise<Result<InsertManyResponse>>
     deleteOne: (request: DeleteOneRequest) => Promise<Result<DeleteOneResponse>>
     deleteMany: (request: DeleteManyRequest) => Promise<Result<DeleteManyResponse>>
+    distinct: (request: DistinctRequest) => Promise<Result<DistinctResponse>>
+    /** Aborts a running find / aggregate / count by its requestId; unknown ids are ignored. */
+    cancel: (request: CancelQueryRequest) => Promise<Result<void>>
+    /** Runs one filter-based write, e.g. from the shell; never retried. */
+    write: (request: WriteRequest) => Promise<Result<WriteResponse>>
   }
 
   users: {
@@ -109,6 +142,10 @@ export type Api = {
     drop: (payload: DropUserPayload) => Promise<Result<void>>
   }
 
+  roles: {
+    list: (payload: { connectionId: string; db: string }) => Promise<Result<DatabaseRoleInfo[]>>
+  }
+
   indexes: {
     list: (payload: {
       connectionId: string
@@ -117,6 +154,11 @@ export type Api = {
     }) => Promise<Result<IndexInfo[]>>
     create: (payload: CreateIndexPayload) => Promise<Result<{ name: string }>>
     drop: (payload: DropIndexPayload) => Promise<Result<void>>
+    stats: (payload: {
+      connectionId: string
+      db: string
+      coll: string
+    }) => Promise<Result<IndexStatsReport>>
   }
 
   /** `onProgress` is the only member that is a push subscription, not a request. */
diff --git a/src/shared/cloudflared.test.ts b/src/shared/cloudflared.test.ts
new file mode 100644
index 0000000..e90b134
--- /dev/null
+++ b/src/shared/cloudflared.test.ts
@@ -0,0 +1,147 @@
+import { describe, expect, it } from 'vitest'
+import {
+  canReuseServiceTokenSecret,
+  cloudflaredTunnelProblems,
+  INVALID_CLOUDFLARED_PATH_MESSAGE,
+  isAccessHostname,
+  isCloudflaredExecutable
+} from './cloudflared'
+
+describe('isAccessHostname', () => {
+  it.each([
+    'mongo.example.com',
+    'a-b.c.example.co.uk',
+    'xn--bcher-kva.example.com',
+    'Mongo.EXAMPLE.com'
+  ])('accepts %s', (hostname) => {
+    expect(isAccessHostname(hostname)).toBe(true)
+  })
+
+  it.each([
+    ['a scheme', 'https://x.com'],
+    ['a port', 'x.com:443'],
+    ['a path', 'x.com/db'],
+    ['a leading dash that cloudflared would read as a flag', '-x.example.com'],
+    ['a label ending in a dash', 'x-.example.com'],
+    ['a single label', 'localhost'],
+    ['a wildcard', '*.example.com'],
+    ['a space', 'a b.com'],
+    ['an empty string', ''],
+    ['a 64-character label', `${'a'.repeat(64)}.example.com`]
+  ])('rejects %s', (_case, hostname) => {
+    expect(isAccessHostname(hostname)).toBe(false)
+  })
+
+  it('accepts a 253-character name and rejects a 254-character one', () => {
+    const labels = `${'a'.repeat(63)}.${'b'.repeat(63)}.${'c'.repeat(63)}.`
+    expect(isAccessHostname(`${labels}${'d'.repeat(61)}`)).toBe(true)
+    expect(isAccessHostname(`${labels}${'d'.repeat(62)}`)).toBe(false)
+  })
+})
+
+describe('isCloudflaredExecutable', () => {
+  it.each([
+    'C:\\Program Files (x86)\\cloudflared\\cloudflared.exe',
+    'C:\\dl\\cloudflared-windows-amd64.exe',
+    'C:/tools/cloudflared.exe',
+    'D:\\Tools\\Cloudflared.EXE',
+    '/usr/local/bin/cloudflared',
+    '/opt/cloudflared-linux-amd64'
+  ])('accepts %s', (path) => {
+    expect(isCloudflaredExecutable(path)).toBe(true)
+  })
+
+  it.each([
+    ['a bare file name', 'cloudflared.exe'],
+    ['a relative path', '.\\bin\\cloudflared.exe'],
+    ['a drive-relative path', 'C:cloudflared.exe'],
+    ['another executable', 'C:\\Windows\\System32\\calc.exe'],
+    ['another executable inside a cloudflared folder', 'C:\\cloudflared\\calc.exe'],
+    ['a name that only contains cloudflared', 'C:\\tools\\not-cloudflared.exe'],
+    ['a directory', '/usr/bin/cloudflared/'],
+    ['an empty string', ''],
+    ['a UNC path', '\\\\fileserver\\tools\\cloudflared.exe'],
+    ['a WebDAV UNC path', '\\\\attacker.invalid@SSL@443\\DavWWWRoot\\cloudflared.exe'],
+    ['a forward-slash UNC path', '//attacker.invalid/share/cloudflared.exe'],
+    ['a POSIX path that starts like a UNC path', '/\\attacker.invalid\\share\\cloudflared'],
+    ['an extended-length UNC path', '\\\\?\\UNC\\attacker.invalid\\share\\cloudflared.exe'],
+    ['an extended-length drive path', '\\\\?\\C:\\tools\\cloudflared.exe'],
+    ['a device path', '\\\\.\\C:\\tools\\cloudflared.exe'],
+    ['an alternate data stream', 'C:\\tools\\cloudflared.exe:payload'],
+    ['a screensaver named after cloudflared', 'C:\\Users\\Public\\cloudflared-anything.scr'],
+    ['a batch file', 'C:\\tools\\cloudflared.cmd'],
+    ['a second extension', 'C:\\tools\\cloudflared.exe.bat'],
+    ['a NUL character', 'C:\\tools\0\\cloudflared.exe'],
+    ['a stream path in a folder name', 'C:\\tools:x\\cloudflared.exe']
+  ])('rejects %s', (_case, path) => {
+    expect(isCloudflaredExecutable(path)).toBe(false)
+  })
+})
+
+describe('cloudflaredTunnelProblems', () => {
+  const uri = 'mongodb://localhost'
+  const access = { enabled: true, hostname: 'mongo.example.com', authMethod: 'browser' as const }
+
+  it('finds nothing for a complete tunnel or one that is off', () => {
+    expect(cloudflaredTunnelProblems({ uri, cloudflared: access })).toEqual([])
+    expect(cloudflaredTunnelProblems({ uri: 'mongodb+srv://x.example.com' })).toEqual([])
+    expect(
+      cloudflaredTunnelProblems({
+        uri: 'mongodb+srv://x.example.com',
+        cloudflared: { ...access, enabled: false, hostname: '' }
+      })
+    ).toEqual([])
+  })
+
+  it('lists every broken rule in form field order', () => {
+    const problems = cloudflaredTunnelProblems({
+      uri: 'mongodb+srv://x.example.com',
+      cloudflared: {
+        enabled: true,
+        hostname: 'localhost',
+        authMethod: 'serviceToken',
+        binaryPath: 'C:\\Windows\\System32\\calc.exe'
+      }
+    })
+    expect(problems.map((p) => p.path)).toEqual([
+      ['uri'],
+      ['cloudflared', 'hostname'],
+      ['cloudflared', 'serviceTokenId'],
+      ['cloudflared', 'binaryPath']
+    ])
+    expect(problems[3]?.message).toBe(INVALID_CLOUDFLARED_PATH_MESSAGE)
+  })
+
+  it('needs a client ID only for the service token method', () => {
+    const cloudflared = { ...access, serviceTokenId: '' }
+    expect(cloudflaredTunnelProblems({ uri, cloudflared })).toEqual([])
+    expect(
+      cloudflaredTunnelProblems({
+        uri,
+        cloudflared: { ...cloudflared, authMethod: 'serviceToken' }
+      })
+    ).toEqual([
+      { path: ['cloudflared', 'serviceTokenId'], message: 'Service token client ID is required' }
+    ])
+  })
+})
+
+describe('canReuseServiceTokenSecret', () => {
+  const saved = { hostname: 'mongo.example.com', serviceTokenId: 'abc.access' }
+
+  it('reuses the saved secret for the hostname and client ID it was saved with', () => {
+    expect(canReuseServiceTokenSecret(saved, { ...saved })).toBe(true)
+  })
+
+  it.each([
+    ['another hostname', { ...saved, hostname: 'other-app.example.com' }],
+    ['another client ID', { ...saved, serviceTokenId: 'other.access' }],
+    ['no client ID', { hostname: saved.hostname }]
+  ])('never sends it to %s', (_case, next) => {
+    expect(canReuseServiceTokenSecret(saved, next)).toBe(false)
+  })
+
+  it('has nothing to reuse without a saved tunnel', () => {
+    expect(canReuseServiceTokenSecret(undefined, saved)).toBe(false)
+  })
+})
diff --git a/src/shared/cloudflared.ts b/src/shared/cloudflared.ts
new file mode 100644
index 0000000..52d5f85
--- /dev/null
+++ b/src/shared/cloudflared.ts
@@ -0,0 +1,82 @@
+/**
+ * Rules for the Cloudflare Access tunnel, shared by main, the IPC schemas and
+ * the connection form so all of them apply the same ones.
+ */
+
+import type { ConnectionInput } from './types'
+
+// Two or more DNS labels: no scheme, port, path or wildcard — and no leading '-' that cloudflared could read as a flag.
+const ACCESS_HOSTNAME =
+  /^(?=.{1,253}$)(?:(?!-)[a-z0-9-]{1,63}(?<!-)\.)+(?!-)[a-z0-9-]{2,63}(?<!-)$/i
+// A drive or POSIX root, then no ':' (alternate data streams) and no NUL; `\\`, `//` and `\\?\` reach other machines or devices.
+const LOCAL_ABSOLUTE_PATH = /^(?:[a-z]:[\\/]|\/(?![\\/]))[^:\0]*$/i
+// The names cloudflared releases ship under, e.g. cloudflared.exe or cloudflared-linux-amd64; no other extension.
+const CLOUDFLARED_FILE_NAME = /^cloudflared[\w-]*(?:\.exe)?$/i
+
+type AccessTarget = { hostname: string; serviceTokenId?: string }
+
+/** A rule an enabled tunnel breaks, with the path of the connection input field it concerns. */
+export type CloudflaredTunnelProblem = { path: string[]; message: string }
+
+/** Shown wherever a binary path fails `isCloudflaredExecutable`. */
+export const INVALID_CLOUDFLARED_PATH_MESSAGE =
+  'Choose the cloudflared executable on this computer (absolute path)'
+
+/** True for a bare DNS hostname such as `mongo.example.com`. */
+export function isAccessHostname(value: string): boolean {
+  return ACCESS_HOSTNAME.test(value)
+}
+
+/** True for an absolute local path to a file named like a cloudflared release. */
+export function isCloudflaredExecutable(path: string): boolean {
+  const name = path.split(/[\\/]/).pop() ?? ''
+  // Main runs whatever this names; tying it to a local cloudflared file keeps a renderer from picking any binary.
+  return LOCAL_ABSOLUTE_PATH.test(path) && CLOUDFLARED_FILE_NAME.test(name)
+}
+
+/** Rules of an enabled tunnel that `input` breaks, in form field order; empty while it is off. */
+export function cloudflaredTunnelProblems(
+  input: Pick<ConnectionInput, 'uri' | 'cloudflared'>
+): CloudflaredTunnelProblem[] {
+  const cf = input.cloudflared
+  if (cf?.enabled !== true) return []
+  const problems: CloudflaredTunnelProblem[] = []
+  if (input.uri.startsWith('mongodb+srv://')) {
+    problems.push({
+      path: ['uri'],
+      message:
+        'A Cloudflare tunnel needs a mongodb:// connection string — mongodb+srv:// resolves its hosts through DNS'
+    })
+  }
+  if (!isAccessHostname(cf.hostname)) {
+    problems.push({
+      path: ['cloudflared', 'hostname'],
+      message: 'Enter the Access application hostname, e.g. mongo.example.com'
+    })
+  }
+  if (cf.authMethod === 'serviceToken' && (cf.serviceTokenId ?? '').length === 0) {
+    problems.push({
+      path: ['cloudflared', 'serviceTokenId'],
+      message: 'Service token client ID is required'
+    })
+  }
+  if (cf.binaryPath !== undefined && !isCloudflaredExecutable(cf.binaryPath)) {
+    problems.push({
+      path: ['cloudflared', 'binaryPath'],
+      message: INVALID_CLOUDFLARED_PATH_MESSAGE
+    })
+  }
+  return problems
+}
+
+/** True when a saved service token secret may go to `next`: only the hostname and client ID it was saved for. */
+export function canReuseServiceTokenSecret(
+  saved: AccessTarget | undefined,
+  next: AccessTarget
+): boolean {
+  return (
+    saved !== undefined &&
+    saved.hostname === next.hostname &&
+    (saved.serviceTokenId ?? '') === (next.serviceTokenId ?? '')
+  )
+}
diff --git a/src/shared/collectionSchema.test.ts b/src/shared/collectionSchema.test.ts
new file mode 100644
index 0000000..700d772
--- /dev/null
+++ b/src/shared/collectionSchema.test.ts
@@ -0,0 +1,367 @@
+import { describe, expect, it } from 'vitest'
+import { Binary, Code, DBRef, EJSON, ObjectId, UUID } from 'bson'
+import {
+  MAX_ARRAY_ELEMENTS,
+  MAX_SCHEMA_FIELDS,
+  addCounts,
+  addressableFields,
+  childFields,
+  classifyCanonical,
+  compareText,
+  createSchemaBuilder,
+  dominantType,
+  resolveField,
+  resolveSchemaField,
+  schemaFieldPaths
+} from './collectionSchema'
+import type { CollectionSchema } from './types'
+
+const canonical = (doc: Record<string, unknown>): unknown =>
+  EJSON.serialize(doc, { relaxed: false })
+
+const schemaOf = (...docs: unknown[]): CollectionSchema => {
+  const builder = createSchemaBuilder()
+  for (const doc of docs) builder.add(doc)
+  return builder.build()
+}
+
+const field = (schema: CollectionSchema, path: string) => schema.fields.find((f) => f.path === path)
+
+describe('classifyCanonical', () => {
+  it.each([
+    [{ $oid: '507f1f77bcf86cd799439011' }, 'objectId'],
+    [{ $date: { $numberLong: '1704067200000' } }, 'date'],
+    [{ $numberInt: '5' }, 'int'],
+    [{ $numberLong: '5' }, 'long'],
+    [{ $numberDouble: '5.5' }, 'double'],
+    [{ $numberDecimal: '1.5' }, 'decimal'],
+    [{ $binary: { base64: 'AAAA', subType: '00' } }, 'binData'],
+    [{ $binary: { base64: 'AAAA', subType: '03' } }, 'uuidLegacy'],
+    [{ $binary: { base64: 'AAAA', subType: '04' } }, 'uuid'],
+    [{ $regularExpression: { pattern: 'a', options: 'i' } }, 'regex'],
+    [{ $timestamp: { t: 1, i: 2 } }, 'timestamp'],
+    [{ $minKey: 1 }, 'minKey'],
+    [{ $maxKey: 1 }, 'maxKey'],
+    [{ $symbol: 's' }, 'symbol'],
+    [{ $code: 'f()' }, 'javascript'],
+    [{ $code: 'f()', $scope: { a: { $numberInt: '1' } } }, 'javascript'],
+    [{ $dbPointer: { $ref: 'c', $id: { $oid: '507f1f77bcf86cd799439011' } } }, 'dbPointer'],
+    [{ $undefined: true }, 'undefined'],
+    [{ $ref: 'users', $id: { $oid: '507f1f77bcf86cd799439011' } }, 'dbRef'],
+    [{ $ref: 'users', $id: { $numberInt: '1' }, $db: 'app' }, 'dbRef'],
+    ['text', 'string'],
+    [true, 'bool'],
+    [null, 'null'],
+    [[1, 2], 'array'],
+    [{ a: 1 }, 'object'],
+    [{ $oid: 'x', other: 1 }, 'object'],
+    [5, 'double']
+  ])('classifies %j as %s', (value, type) => {
+    expect(classifyCanonical(value)).toBe(type)
+  })
+
+  it('classifies values produced by the bson serializer', () => {
+    const doc = canonical({
+      date: new Date('2024-01-01T00:00:00Z'),
+      uuid: new UUID('550e8400-e29b-41d4-a716-446655440000'),
+      legacy: new Binary(Buffer.alloc(16), 3),
+      code: new Code('f()', { a: 1 }),
+      ref: new DBRef('users', new ObjectId())
+    }) as Record<string, unknown>
+    expect(classifyCanonical(doc['date'])).toBe('date')
+    expect(classifyCanonical(doc['uuid'])).toBe('uuid')
+    expect(classifyCanonical(doc['legacy'])).toBe('uuidLegacy')
+    expect(classifyCanonical(doc['code'])).toBe('javascript')
+    expect(classifyCanonical(doc['ref'])).toBe('dbRef')
+  })
+})
+
+describe('createSchemaBuilder', () => {
+  it('records nested paths sorted by path', () => {
+    const schema = schemaOf({ b: { $numberInt: '1' }, a: { city: 'Berlin', zip: 'x' } })
+    expect(schema.sampleSize).toBe(1)
+    expect(schema.fields.map((f) => f.path)).toEqual(['a', 'a.city', 'a.zip', 'b'])
+    expect(field(schema, 'a')?.types).toEqual({ object: 1 })
+    expect(field(schema, 'b')?.types).toEqual({ int: 1 })
+  })
+
+  it('lets array elements share the array path and counts them in elementTypes', () => {
+    const schema = schemaOf({
+      items: [{ sku: 'a' }, { sku: 'b' }, { sku: 'c', qty: { $numberInt: '2' } }]
+    })
+    expect(field(schema, 'items')?.types).toEqual({ array: 1 })
+    expect(field(schema, 'items')?.elementTypes).toEqual({ object: 3 })
+    expect(field(schema, 'items.sku')?.types).toEqual({ string: 3 })
+    expect(field(schema, 'items.qty')?.types).toEqual({ int: 1 })
+  })
+
+  it('counts a path once per document, not per occurrence', () => {
+    const schema = schemaOf({ items: [{ sku: 'a' }, { sku: 'b' }, { sku: 'c' }] }, { other: 1 })
+    expect(field(schema, 'items.sku')?.docCount).toBe(1)
+  })
+
+  it('recurses into nested arrays with the same path', () => {
+    const schema = schemaOf({ grid: [[{ $numberInt: '1' }, { $numberInt: '2' }], ['x']] })
+    expect(field(schema, 'grid')?.elementTypes).toEqual({ array: 2, int: 2, string: 1 })
+  })
+
+  it('orders tracked values by count, then by text', () => {
+    const schema = schemaOf({ s: 'b' }, { s: 'a' }, { s: 'b' }, { s: 'c' })
+    expect(field(schema, 's')?.values).toEqual([
+      { ejson: '"b"', count: 2 },
+      { ejson: '"a"', count: 1 },
+      { ejson: '"c"', count: 1 }
+    ])
+    expect(field(schema, 's')?.valuesTruncated).toBeUndefined()
+  })
+
+  it('stops tracking at 20 distinct values and flags truncation at the 21st', () => {
+    const docs = Array.from({ length: 21 }, (_, i) => ({ n: { $numberInt: String(i) } }))
+    const schema = schemaOf(...docs)
+    expect(field(schema, 'n')?.values).toHaveLength(20)
+    expect(field(schema, 'n')?.valuesTruncated).toBe(true)
+  })
+
+  it('does not track long strings, nulls, objects or arrays', () => {
+    const schema = schemaOf({ long: 'x'.repeat(101), n: null, o: { a: 'v' }, arr: [] })
+    expect(field(schema, 'long')?.values).toBeUndefined()
+    expect(field(schema, 'n')?.values).toBeUndefined()
+    expect(field(schema, 'o')?.values).toBeUndefined()
+    expect(field(schema, 'arr')?.values).toBeUndefined()
+    expect(field(schema, 'o.a')?.values).toEqual([{ ejson: '"v"', count: 1 }])
+  })
+
+  it('tracks scalar array elements as values', () => {
+    const schema = schemaOf({ tags: ['a', 'b', 'a'] })
+    expect(field(schema, 'tags')?.values).toEqual([
+      { ejson: '"a"', count: 2 },
+      { ejson: '"b"', count: 1 }
+    ])
+  })
+
+  it('collapses an object with more than 64 distinct keys into a map', () => {
+    const scores = Object.fromEntries(
+      Array.from({ length: 70 }, (_, i) => [`key${i}x`, { $numberInt: '1' }])
+    )
+    const schema = schemaOf({ scores })
+    expect(field(schema, 'scores')?.mapLike).toBe(true)
+    expect(schemaFieldPaths(schema)).toEqual(['scores'])
+    expect(field(schema, 'scores.*')?.types).toEqual({ int: 70 })
+  })
+
+  it('collapses an object keyed by ids', () => {
+    const byUser = Object.fromEntries(
+      Array.from({ length: 10 }, () => [new UUID().toHexString(true), { seen: true }])
+    )
+    const schema = schemaOf({ byUser })
+    expect(field(schema, 'byUser')?.mapLike).toBe(true)
+    expect(field(schema, 'byUser.*.seen')?.types).toEqual({ bool: 10 })
+  })
+
+  it('keeps a small fixed key set as fields', () => {
+    const schema = schemaOf({ address: { street: 'a', city: 'b', zip: 'c', country: 'd', n: 'e' } })
+    expect(field(schema, 'address')?.mapLike).toBeUndefined()
+    expect(childFields(schema, 'address')).toHaveLength(5)
+  })
+
+  it('re-keys and merges descendants that existed before the collapse', () => {
+    const docs = Array.from({ length: 8 }, (_, i) => ({
+      byId: { [String(1000 + i)]: { total: { $numberInt: String(i % 2) } } }
+    }))
+    const schema = schemaOf(...docs)
+    expect(field(schema, 'byId')?.mapLike).toBe(true)
+    expect(schema.fields.map((f) => f.path)).toEqual(['byId', 'byId.*', 'byId.*.total'])
+    expect(field(schema, 'byId.*.total')?.types).toEqual({ int: 8 })
+    expect(field(schema, 'byId.*.total')?.docCount).toBe(8)
+    expect(field(schema, 'byId.*.total')?.values).toEqual([
+      { ejson: '{"$numberInt":"0"}', count: 4 },
+      { ejson: '{"$numberInt":"1"}', count: 4 }
+    ])
+  })
+
+  it('counts each document once for a map that collapses mid-document', () => {
+    const keys = Array.from({ length: 9 }, () => new UUID().toHexString(true))
+    const statsOf = (from: number, to: number) =>
+      Object.fromEntries(keys.slice(from, to).map((key) => [key, { kills: { $numberInt: '1' } }]))
+    const schema = schemaOf(
+      { stats: statsOf(0, 3) },
+      { stats: statsOf(3, 7) },
+      { stats: statsOf(7, 9) }
+    )
+    expect(field(schema, 'stats.*')?.docCount).toBe(3)
+    expect(field(schema, 'stats.*.kills')?.docCount).toBe(3)
+  })
+
+  it('keeps the count when a merged key already appeared in the collapsing document', () => {
+    const keys = Array.from({ length: 8 }, () => new UUID().toHexString(true))
+    const statsOf = (picked: readonly string[]) =>
+      Object.fromEntries(picked.map((key) => [key, { $numberInt: '1' }]))
+    const schema = schemaOf(
+      { stats: statsOf(keys.slice(0, 4)) },
+      { stats: statsOf(keys.slice(4, 7)) },
+      { stats: statsOf([keys[0]!, keys[7]!]) }
+    )
+    expect(field(schema, 'stats.*')?.docCount).toBe(3)
+  })
+
+  it('stops descending below depth 8', () => {
+    let doc: Record<string, unknown> = { leaf: 'x' }
+    for (let i = 10; i >= 1; i--) doc = { [`l${i}`]: doc }
+    const schema = schemaOf(doc)
+    const deepest = Math.max(...schema.fields.map((f) => f.path.split('.').length))
+    expect(deepest).toBe(8)
+    expect(schema.truncated).toBe(false)
+  })
+
+  it('flags truncation when the field cap is hit', () => {
+    const doc = Object.fromEntries(
+      Array.from({ length: MAX_SCHEMA_FIELDS + 5 }, (_, i) => [`f${i}`, 'v'])
+    )
+    const schema = schemaOf(doc)
+    expect(schema.fields).toHaveLength(MAX_SCHEMA_FIELDS)
+    expect(schema.truncated).toBe(true)
+  })
+
+  it('samples only the first array elements', () => {
+    const schema = schemaOf({ n: Array.from({ length: 80 }, () => ({ $numberInt: '1' })) })
+    expect(field(schema, 'n')?.elementTypes).toEqual({ int: MAX_ARRAY_ELEMENTS })
+  })
+
+  it('skips $-prefixed keys of plain objects', () => {
+    const schema = schemaOf({ meta: { $comment: 'x', ok: true } })
+    expect(schemaFieldPaths(schema)).toEqual(['meta', 'meta.ok'])
+  })
+
+  it('continues a seeded schema: counts add and values merge', () => {
+    const seed = schemaOf({ s: 'a' }, { s: 'b' })
+    const builder = createSchemaBuilder(seed)
+    builder.add({ s: 'a', t: true })
+    const schema = builder.build()
+    expect(schema.sampleSize).toBe(3)
+    expect(field(schema, 's')?.docCount).toBe(3)
+    expect(field(schema, 's')?.types).toEqual({ string: 3 })
+    expect(field(schema, 's')?.values).toEqual([
+      { ejson: '"a"', count: 2 },
+      { ejson: '"b"', count: 1 }
+    ])
+    expect(field(schema, 't')?.docCount).toBe(1)
+  })
+
+  it('routes new keys of a seeded map-like object to *', () => {
+    const scores = Object.fromEntries(
+      Array.from({ length: 70 }, (_, i) => [`k${i}z`, { $numberInt: '1' }])
+    )
+    const builder = createSchemaBuilder(schemaOf({ scores }))
+    builder.add({ scores: { fresh: { $numberInt: '2' } } })
+    const schema = builder.build()
+    expect(field(schema, 'scores.fresh')).toBeUndefined()
+    expect(field(schema, 'scores.*')?.types).toEqual({ int: 71 })
+  })
+
+  it('keeps value truncation of a seed', () => {
+    const docs = Array.from({ length: 21 }, (_, i) => ({ n: { $numberInt: String(i) } }))
+    const builder = createSchemaBuilder(schemaOf(...docs))
+    builder.add({ n: { $numberInt: '0' } })
+    expect(field(builder.build(), 'n')?.valuesTruncated).toBe(true)
+  })
+
+  it('ignores non-object documents', () => {
+    const schema = schemaOf('x', null, [1])
+    expect(schema).toEqual({ sampleSize: 0, fields: [], truncated: false })
+  })
+})
+
+describe('schema lookups', () => {
+  const scores = Object.fromEntries(
+    Array.from({ length: 70 }, (_, i) => [`k${i}z`, { value: { $numberInt: '1' } }])
+  )
+  const schema = schemaOf({
+    _id: { $oid: '507f1f77bcf86cd799439011' },
+    address: { city: 'x', geo: { lat: { $numberDouble: '1.5' } } },
+    items: [{ name: 'a' }],
+    scores
+  })
+
+  it('resolves paths through map-like objects and array indexes', () => {
+    expect(resolveSchemaField(schema, 'scores.anyKey.value')?.path).toBe('scores.*.value')
+    expect(resolveSchemaField(schema, 'items.0.name')?.path).toBe('items.name')
+    expect(resolveSchemaField(schema, 'address.geo.lat')?.types).toEqual({ double: 1 })
+    expect(resolveSchemaField(schema, 'missing')).toBeUndefined()
+  })
+
+  it('resolves the same paths in a map of the fields', () => {
+    const fields = new Map(schema.fields.map((f) => [f.path, f]))
+    for (const path of ['scores.anyKey.value', 'items.0.name', 'address.geo.lat', 'missing']) {
+      expect(resolveField(fields, path)).toBe(resolveSchemaField(schema, path))
+    }
+  })
+
+  it('lists direct children without * entries', () => {
+    expect(childFields(schema, '').map((f) => f.path)).toEqual([
+      '_id',
+      'address',
+      'items',
+      'scores'
+    ])
+    expect(childFields(schema, 'address').map((f) => f.path)).toEqual([
+      'address.city',
+      'address.geo'
+    ])
+    expect(childFields(schema, 'scores')).toEqual([])
+    expect(childFields(schema, 'scores.k1z').map((f) => f.path)).toEqual(['scores.*.value'])
+  })
+
+  it('lists addressable fields only', () => {
+    expect(addressableFields(schema).map((f) => f.path)).toEqual(schemaFieldPaths(schema))
+    expect(addressableFields(schema).find((f) => f.path === 'address.city')?.types).toEqual({
+      string: 1
+    })
+  })
+
+  it('lists addressable paths only', () => {
+    expect(schemaFieldPaths(schema)).toEqual([
+      '_id',
+      'address',
+      'address.city',
+      'address.geo',
+      'address.geo.lat',
+      'items',
+      'items.name',
+      'scores'
+    ])
+  })
+})
+
+describe('addCounts', () => {
+  it('sums the counts per type into a new object', () => {
+    const a = { string: 2, int: 1 }
+    const b = { int: 3, null: 1 }
+    expect(addCounts(a, b)).toEqual({ string: 2, int: 4, null: 1 })
+    expect(a).toEqual({ string: 2, int: 1 })
+    expect(b).toEqual({ int: 3, null: 1 })
+  })
+})
+
+describe('compareText', () => {
+  it('orders like the default sort', () => {
+    const words = ['b', 'B', 'a', 'é', 'a.b', 'a_b', '']
+    expect([...words].sort(compareText)).toEqual([...words].sort())
+  })
+})
+
+describe('dominantType', () => {
+  it('picks the most frequent type', () => {
+    expect(dominantType({ string: 3, int: 5 })).toBe('int')
+  })
+
+  it('ignores null and undefined unless nothing else occurs', () => {
+    expect(dominantType({ null: 10, string: 1 })).toBe('string')
+    expect(dominantType({ null: 2 })).toBe('null')
+    expect(dominantType({ undefined: 1 })).toBe('undefined')
+  })
+
+  it('returns null without counts', () => {
+    expect(dominantType(undefined)).toBeNull()
+    expect(dominantType({})).toBeNull()
+  })
+})
diff --git a/src/shared/collectionSchema.ts b/src/shared/collectionSchema.ts
new file mode 100644
index 0000000..a51de92
--- /dev/null
+++ b/src/shared/collectionSchema.ts
@@ -0,0 +1,440 @@
+/**
+ * Field schema inference over canonical-EJSON documents. Runs in main (sampling a
+ * collection) and in the renderer (folding loaded documents into a sampled schema).
+ */
+import type { BsonTypeName, CollectionSchema, SchemaField, TypeCounts } from './types'
+
+export const MAX_SCHEMA_DEPTH = 8
+export const MAX_SCHEMA_FIELDS = 1000
+export const MAX_TRACKED_VALUES = 20
+export const MAX_VALUE_LENGTH = 100
+export const MAX_ARRAY_ELEMENTS = 50
+export const MAP_KEY_LIMIT = 64
+export const MAP_ID_MIN_KEYS = 8
+export const MAP_ID_RATIO = 0.8
+export const ID_KEY_RE =
+  /^(?:[0-9a-f]{24}|[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}|\d+)$/i
+
+const TRACKED_TYPES: ReadonlySet<BsonTypeName> = new Set<BsonTypeName>([
+  'string',
+  'int',
+  'long',
+  'double',
+  'decimal',
+  'bool',
+  'objectId',
+  'uuid',
+  'uuidLegacy',
+  'date'
+])
+
+type FieldState = {
+  docCount: number
+  types: TypeCounts
+  elementTypes: TypeCounts
+  values: Map<string, number>
+  valuesTruncated: boolean
+  mapLike: boolean
+  /** Distinct child keys seen so far; drives the map-like decision. */
+  childKeys: Set<string>
+  idKeys: number
+  /** Sequence number of the last document that contained the path. */
+  seenIn: number
+}
+
+/**
+ * Streaming schema inference over canonical-EJSON documents; `seed` continues an existing schema.
+ * @param seed schema whose counters, values and map-like flags new documents add to
+ * @returns `add` folds in one canonical document; `build` snapshots the schema
+ */
+export function createSchemaBuilder(seed?: CollectionSchema): {
+  add: (canonicalDoc: unknown) => void
+  build: () => CollectionSchema
+} {
+  const fields = new Map<string, FieldState>()
+  let sampleSize = seed?.sampleSize ?? 0
+  let truncated = seed?.truncated ?? false
+  for (const field of seed?.fields ?? []) fields.set(field.path, seededState(field))
+
+  const touch = (path: string): FieldState | null => {
+    let state = fields.get(path)
+    if (!state) {
+      if (fields.size >= MAX_SCHEMA_FIELDS) {
+        truncated = true
+        return null
+      }
+      state = emptyState()
+      fields.set(path, state)
+    }
+    if (state.seenIn !== sampleSize) {
+      state.seenIn = sampleSize
+      state.docCount++
+    }
+    return state
+  }
+
+  const collapse = (parent: string, state: FieldState): void => {
+    state.mapLike = true
+    state.childKeys = new Set()
+    state.idKeys = 0
+    const prefix = `${parent}.`
+    for (const [path, child] of [...fields]) {
+      if (!path.startsWith(prefix)) continue
+      const rest = path.slice(prefix.length)
+      const dot = rest.indexOf('.')
+      if ((dot === -1 ? rest : rest.slice(0, dot)) === '*') continue
+      const target = `${prefix}*${dot === -1 ? '' : rest.slice(dot)}`
+      fields.delete(path)
+      const existing = fields.get(target)
+      fields.set(target, existing ? mergeStates(existing, child, sampleSize) : child)
+    }
+  }
+
+  const childPath = (parent: string, key: string): string => {
+    if (parent === '') return key
+    const state = fields.get(parent)
+    if (state && !state.mapLike && !state.childKeys.has(key)) {
+      state.childKeys.add(key)
+      if (ID_KEY_RE.test(key)) state.idKeys++
+      const keys = state.childKeys.size
+      if (
+        keys > MAP_KEY_LIMIT ||
+        (keys >= MAP_ID_MIN_KEYS && state.idKeys >= MAP_ID_RATIO * keys)
+      ) {
+        collapse(parent, state)
+      }
+    }
+    return `${parent}.${state?.mapLike ? '*' : key}`
+  }
+
+  const recordChildren = (parent: string, obj: Record<string, unknown>, depth: number): void => {
+    for (const key of Object.keys(obj)) {
+      // `$`-prefixed keys cannot be addressed with dot notation.
+      if (key.startsWith('$')) continue
+      recordValue(childPath(parent, key), obj[key], depth + 1)
+    }
+  }
+
+  const recordElements = (
+    path: string,
+    state: FieldState,
+    elements: readonly unknown[],
+    depth: number,
+    nesting: number
+  ): void => {
+    for (const element of elements.slice(0, MAX_ARRAY_ELEMENTS)) {
+      const type = classifyCanonical(element)
+      increment(state.elementTypes, type)
+      if (type === 'array') {
+        // Nested arrays keep the path, as Mongo dot paths traverse them.
+        if (nesting < MAX_SCHEMA_DEPTH) {
+          recordElements(path, state, element as unknown[], depth, nesting + 1)
+        }
+        continue
+      }
+      trackValue(state, type, element)
+      if (type === 'object' && depth < MAX_SCHEMA_DEPTH) {
+        recordChildren(path, element as Record<string, unknown>, depth)
+      }
+    }
+  }
+
+  const recordValue = (path: string, value: unknown, depth: number): void => {
+    const state = touch(path)
+    if (!state) return
+    const type = classifyCanonical(value)
+    increment(state.types, type)
+    if (type === 'array') {
+      recordElements(path, state, value as unknown[], depth, 0)
+      return
+    }
+    trackValue(state, type, value)
+    if (type === 'object' && depth < MAX_SCHEMA_DEPTH) {
+      recordChildren(path, value as Record<string, unknown>, depth)
+    }
+  }
+
+  return {
+    add: (canonicalDoc) => {
+      if (classifyCanonical(canonicalDoc) !== 'object') return
+      sampleSize++
+      recordChildren('', canonicalDoc as Record<string, unknown>, 0)
+    },
+    build: () => ({
+      sampleSize,
+      fields: [...fields]
+        .sort(([a], [b]) => compareText(a, b))
+        .map(([path, state]) => toSchemaField(path, state)),
+      truncated
+    })
+  }
+}
+
+/**
+ * Field at a dot path; segments below a map-like object resolve to its `*` child.
+ * @param path dot path as written in a query; numeric segments below arrays are skipped
+ * @returns the field, or undefined when the schema has no such path
+ */
+export function resolveSchemaField(
+  schema: CollectionSchema,
+  path: string
+): SchemaField | undefined {
+  return resolveField(indexFields(schema), path)
+}
+
+/**
+ * `resolveSchemaField` over fields keyed by their path.
+ * @param fields every field of a schema, keyed by `SchemaField.path`
+ * @returns the field, or undefined when there is no such path
+ */
+export function resolveField(
+  fields: ReadonlyMap<string, SchemaField>,
+  path: string
+): SchemaField | undefined {
+  return fields.get(canonicalPath(fields, path))
+}
+
+/**
+ * Direct children of `parentPath` ('' = root), excluding `*` entries.
+ * @param parentPath dot path, resolved through map-like objects
+ * @returns children in schema order; empty below a map-like object
+ */
+export function childFields(schema: CollectionSchema, parentPath: string): SchemaField[] {
+  const parent = parentPath === '' ? '' : canonicalPath(indexFields(schema), parentPath)
+  const prefix = parent === '' ? '' : `${parent}.`
+  return schema.fields.filter((field) => {
+    if (!field.path.startsWith(prefix)) return false
+    const rest = field.path.slice(prefix.length)
+    return rest !== '' && rest !== '*' && !rest.includes('.')
+  })
+}
+
+/**
+ * Every addressable field (no `*` segments); map-like objects contribute their own field.
+ * @returns fields in schema order
+ */
+export function addressableFields(schema: CollectionSchema): SchemaField[] {
+  return schema.fields.filter((field) => isAddressable(field.path))
+}
+
+/**
+ * Paths of `addressableFields`.
+ * @returns dot paths in schema order
+ */
+export function schemaFieldPaths(schema: CollectionSchema): string[] {
+  return addressableFields(schema).map((field) => field.path)
+}
+
+/**
+ * Most frequent type, ignoring null/undefined unless nothing else occurs.
+ * @returns null when `counts` is absent or all zero
+ */
+export function dominantType(counts: TypeCounts | undefined): BsonTypeName | null {
+  if (!counts) return null
+  let best: BsonTypeName | null = null
+  let bestCount = 0
+  for (const [type, count] of Object.entries(counts) as [BsonTypeName, number][]) {
+    if (type === 'null' || type === 'undefined' || !count) continue
+    if (count > bestCount) {
+      best = type
+      bestCount = count
+    }
+  }
+  if (best) return best
+  const nulls = counts.null ?? 0
+  const undefinedCount = counts.undefined ?? 0
+  if (nulls === 0 && undefinedCount === 0) return null
+  return nulls >= undefinedCount ? 'null' : 'undefined'
+}
+
+/**
+ * BSON type of one canonical-EJSON value.
+ * @param value parsed canonical EJSON; a plain number is classified as double
+ */
+export function classifyCanonical(value: unknown): BsonTypeName {
+  if (value === null) return 'null'
+  if (typeof value === 'string') return 'string'
+  if (typeof value === 'boolean') return 'bool'
+  if (typeof value === 'number') return 'double'
+  if (Array.isArray(value)) return 'array'
+  if (typeof value !== 'object') return 'undefined'
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj)
+  if (keys.length === 1) {
+    switch (keys[0]) {
+      case '$oid':
+        return 'objectId'
+      case '$date':
+        return 'date'
+      case '$numberInt':
+        return 'int'
+      case '$numberLong':
+        return 'long'
+      case '$numberDouble':
+        return 'double'
+      case '$numberDecimal':
+        return 'decimal'
+      case '$binary':
+        return binaryType(obj['$binary'])
+      case '$regularExpression':
+        return 'regex'
+      case '$timestamp':
+        return 'timestamp'
+      case '$minKey':
+        return 'minKey'
+      case '$maxKey':
+        return 'maxKey'
+      case '$symbol':
+        return 'symbol'
+      case '$code':
+        return 'javascript'
+      case '$dbPointer':
+        return 'dbPointer'
+      case '$undefined':
+        return 'undefined'
+    }
+  }
+  if (keys.length === 2 && '$code' in obj && '$scope' in obj) return 'javascript'
+  if (typeof obj['$ref'] === 'string' && '$id' in obj) return 'dbRef'
+  return 'object'
+}
+
+function binaryType(binary: unknown): BsonTypeName {
+  const subType =
+    typeof binary === 'object' && binary !== null
+      ? (binary as Record<string, unknown>)['subType']
+      : undefined
+  const code = typeof subType === 'string' ? parseInt(subType, 16) : NaN
+  if (code === 4) return 'uuid'
+  if (code === 3) return 'uuidLegacy'
+  return 'binData'
+}
+
+function emptyState(): FieldState {
+  return {
+    docCount: 0,
+    types: {},
+    elementTypes: {},
+    values: new Map(),
+    valuesTruncated: false,
+    mapLike: false,
+    childKeys: new Set(),
+    idKeys: 0,
+    seenIn: -1
+  }
+}
+
+function seededState(field: SchemaField): FieldState {
+  return {
+    ...emptyState(),
+    docCount: field.docCount,
+    types: { ...field.types },
+    elementTypes: { ...field.elementTypes },
+    values: new Map((field.values ?? []).map((v) => [v.ejson, v.count])),
+    valuesTruncated: field.valuesTruncated ?? false,
+    mapLike: field.mapLike ?? false
+  }
+}
+
+function mergeStates(a: FieldState, b: FieldState, sampleSize: number): FieldState {
+  const values = new Map(a.values)
+  for (const [ejson, count] of b.values) values.set(ejson, (values.get(ejson) ?? 0) + count)
+  const overflow = values.size > MAX_TRACKED_VALUES
+  const kept = overflow ? new Map(sortValues(values).slice(0, MAX_TRACKED_VALUES)) : values
+  const childKeys = new Set([...a.childKeys, ...b.childKeys])
+  // Leaves the current document to the next touch() unless a merged key already counted it.
+  const cap = Math.max(a.seenIn, b.seenIn) === sampleSize ? sampleSize : sampleSize - 1
+  return {
+    // Approximation: a document holding several of the merged keys counts once per key.
+    docCount: Math.min(cap, a.docCount + b.docCount),
+    types: addCounts(a.types, b.types),
+    elementTypes: addCounts(a.elementTypes, b.elementTypes),
+    values: kept,
+    valuesTruncated: overflow || a.valuesTruncated || b.valuesTruncated,
+    mapLike: a.mapLike || b.mapLike,
+    childKeys,
+    idKeys: [...childKeys].filter((key) => ID_KEY_RE.test(key)).length,
+    seenIn: Math.max(a.seenIn, b.seenIn)
+  }
+}
+
+/**
+ * Sum of two type counts.
+ * @returns a new object; `a` and `b` are not changed
+ */
+export function addCounts(a: TypeCounts, b: TypeCounts): TypeCounts {
+  const out: TypeCounts = { ...a }
+  for (const [type, count] of Object.entries(b) as [BsonTypeName, number][]) {
+    out[type] = (out[type] ?? 0) + count
+  }
+  return out
+}
+
+function increment(counts: TypeCounts, type: BsonTypeName): void {
+  counts[type] = (counts[type] ?? 0) + 1
+}
+
+function trackValue(state: FieldState, type: BsonTypeName, value: unknown): void {
+  if (!TRACKED_TYPES.has(type)) return
+  if (type === 'string' && (value as string).length > MAX_VALUE_LENGTH) return
+  const ejson = JSON.stringify(value)
+  const count = state.values.get(ejson)
+  if (count !== undefined) state.values.set(ejson, count + 1)
+  else if (state.values.size >= MAX_TRACKED_VALUES) state.valuesTruncated = true
+  else state.values.set(ejson, 1)
+}
+
+function sortValues(values: Map<string, number>): [string, number][] {
+  return [...values].sort(([a, ca], [b, cb]) => cb - ca || compareText(a, b))
+}
+
+function toSchemaField(path: string, state: FieldState): SchemaField {
+  const field: SchemaField = { path, docCount: state.docCount, types: { ...state.types } }
+  if (Object.keys(state.elementTypes).length > 0) field.elementTypes = { ...state.elementTypes }
+  if (state.values.size > 0) {
+    field.values = sortValues(state.values).map(([ejson, count]) => ({ ejson, count }))
+  }
+  if (state.valuesTruncated) field.valuesTruncated = true
+  if (state.mapLike) field.mapLike = true
+  return field
+}
+
+const fieldIndexes = new WeakMap<CollectionSchema, Map<string, SchemaField>>()
+
+function indexFields(schema: CollectionSchema): Map<string, SchemaField> {
+  let index = fieldIndexes.get(schema)
+  if (!index) {
+    index = new Map(schema.fields.map((field) => [field.path, field]))
+    fieldIndexes.set(schema, index)
+  }
+  return index
+}
+
+function canonicalPath(index: ReadonlyMap<string, SchemaField>, path: string): string {
+  let current = ''
+  for (const segment of path.split('.')) {
+    const parent = current === '' ? undefined : index.get(current)
+    if (parent?.mapLike) {
+      current = `${current}.*`
+      continue
+    }
+    // `items.0.name` addresses an element; elements share their array's path.
+    if (parent?.types.array && /^\d+$/.test(segment) && !index.has(`${current}.${segment}`)) {
+      continue
+    }
+    current = current === '' ? segment : `${current}.${segment}`
+  }
+  return current
+}
+
+function isAddressable(path: string): boolean {
+  return !path.split('.').includes('*')
+}
+
+/**
+ * Orders strings by UTF-16 code units, as the default sort does.
+ * @returns negative, zero or positive
+ */
+export function compareText(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0
+}
diff --git a/src/shared/events.ts b/src/shared/events.ts
index 7936529..f54c18d 100644
--- a/src/shared/events.ts
+++ b/src/shared/events.ts
@@ -21,11 +21,18 @@ export type UpdateProgress = {
 
 /**
  * Pushed on `connections:dropped` when main tears a connection down on its
- * own — today only when its SSH tunnel dies. The renderer has already been
- * told the connection is live, so without this the sidebar would keep
- * claiming so until the next query happened to fail.
+ * own — when its tunnel dies. The renderer has already been told the
+ * connection is live, so without this the sidebar would keep claiming so
+ * until the next query happened to fail.
  */
 export type ConnectionDropped = {
   connectionId: string
   reason: string
 }
+
+/**
+ * Pushed on `cloudflared:login` while cloudflared waits for a browser sign-in
+ * to Cloudflare Access, and once more when that sign-in process ends.
+ */
+export type CloudflaredLoginPrompt =
+  { hostname: string; state: 'waiting'; url: string } | { hostname: string; state: 'finished' }
diff --git a/src/shared/pipeline.test.ts b/src/shared/pipeline.test.ts
new file mode 100644
index 0000000..f987c64
--- /dev/null
+++ b/src/shared/pipeline.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest'
+import {
+  finalWriteStage,
+  findRejectedStage,
+  rejectedStageMessage,
+  UNSUPPORTED_STAGES,
+  WRITE_STAGES,
+  writePipelineError
+} from './pipeline'
+
+describe('WRITE_STAGES', () => {
+  it('holds exactly the two stages that write', () => {
+    expect([...WRITE_STAGES].sort()).toEqual(['$merge', '$out'])
+  })
+})
+
+describe('UNSUPPORTED_STAGES', () => {
+  it('holds $changeStream, which never returns a complete result', () => {
+    expect([...UNSUPPORTED_STAGES]).toEqual(['$changeStream'])
+  })
+})
+
+describe('findRejectedStage', () => {
+  it('finds $out as the last stage', () => {
+    expect(findRejectedStage([{ $match: { a: 1 } }, { $out: 'copy' }])).toBe('$out')
+  })
+
+  it('finds $merge as the last stage', () => {
+    expect(findRejectedStage([{ $match: {} }, { $merge: { into: 'copy' } }])).toBe('$merge')
+  })
+
+  it('finds $changeStream as the first stage', () => {
+    expect(findRejectedStage([{ $changeStream: {} }, { $match: {} }])).toBe('$changeStream')
+  })
+
+  it('finds a write stage at the first index', () => {
+    expect(findRejectedStage([{ $out: 'copy' }, { $match: {} }])).toBe('$out')
+  })
+
+  it('returns the first rejected stage when there are several', () => {
+    expect(findRejectedStage([{ $merge: { into: 'a' } }, { $out: 'b' }])).toBe('$merge')
+    expect(findRejectedStage([{ $changeStream: {} }, { $out: 'b' }])).toBe('$changeStream')
+  })
+
+  it('finds a rejected operator in a stage object that has other keys too', () => {
+    expect(findRejectedStage([{ $match: {}, $out: 'copy' }])).toBe('$out')
+  })
+
+  it('returns null for a read pipeline', () => {
+    expect(
+      findRejectedStage([
+        { $match: { status: 'active' } },
+        { $group: { _id: '$region', n: { $sum: 1 } } },
+        { $sort: { n: -1 } },
+        { $limit: 10 }
+      ])
+    ).toBeNull()
+  })
+
+  it('returns null for an empty pipeline', () => {
+    expect(findRejectedStage([])).toBeNull()
+  })
+
+  it('ignores entries that are not stage objects', () => {
+    expect(
+      findRejectedStage([null, undefined, 1, '$out', ['$out'], [{ $changeStream: {} }]])
+    ).toBeNull()
+  })
+
+  it('looks only at top-level stage operators', () => {
+    // The server itself rejects $out / $merge inside $facet, $lookup and $unionWith pipelines.
+    expect(
+      findRejectedStage([
+        { $facet: { copy: [{ $out: 'copy' }] } },
+        { $lookup: { from: 'b', pipeline: [{ $merge: { into: 'c' } }], as: 'b' } },
+        { $match: { $out: 1, $changeStream: 1 } }
+      ])
+    ).toBeNull()
+  })
+})
+
+describe('rejectedStageMessage', () => {
+  it.each(['$out', '$merge'])('says %s writes to the database', (stage) => {
+    expect(rejectedStageMessage(stage)).toBe(
+      `${stage} writes to the database; Aggregation mode only reads, run it in Shell mode`
+    )
+  })
+
+  it('says $changeStream never ends', () => {
+    expect(rejectedStageMessage('$changeStream')).toBe(
+      '$changeStream never ends, so it cannot run here'
+    )
+  })
+})
+
+describe('finalWriteStage', () => {
+  it.each([
+    ['$out', [{ $match: {} }, { $out: 'copy' }]],
+    ['$merge', [{ $merge: { into: 'copy' } }]]
+  ])('finds %s ending the pipeline', (stage, stages) => {
+    expect(finalWriteStage(stages)).toBe(stage)
+  })
+
+  it('returns null when the last stage reads', () => {
+    expect(finalWriteStage([{ $out: 'copy' }, { $match: {} }])).toBeNull()
+  })
+
+  it('returns null for an empty pipeline', () => {
+    expect(finalWriteStage([])).toBeNull()
+  })
+
+  it('returns null when the last entry is not a stage object', () => {
+    expect(finalWriteStage([{ $match: {} }, '$out'])).toBeNull()
+    expect(finalWriteStage([{ $match: {} }, [{ $out: 'copy' }]])).toBeNull()
+    expect(finalWriteStage([{ $match: {} }, null])).toBeNull()
+  })
+})
+
+describe('writePipelineError', () => {
+  it('accepts read stages followed by the write stage', () => {
+    expect(
+      writePipelineError([{ $match: {} }, { $group: { _id: '$a' } }, { $out: 'copy' }])
+    ).toBeNull()
+  })
+
+  it('accepts a pipeline that is only the write stage', () => {
+    expect(writePipelineError([{ $merge: { into: 'copy' } }])).toBeNull()
+  })
+
+  it.each(['$out', '$merge'])(
+    'says an earlier %s must be the last stage, naming its position',
+    (stage) => {
+      expect(writePipelineError([{ $match: {} }, { [stage]: 'a' }, { $out: 'copy' }])).toBe(
+        `Stage 2: ${stage} must be the last stage`
+      )
+    }
+  )
+
+  it('rejects $changeStream before the write stage, naming its position', () => {
+    expect(writePipelineError([{ $changeStream: {} }, { $out: 'copy' }])).toBe(
+      `Stage 1: ${rejectedStageMessage('$changeStream')}`
+    )
+  })
+
+  it('looks only at the stages before the last one', () => {
+    expect(writePipelineError([{ $match: {} }, { $changeStream: {} }])).toBeNull()
+  })
+})
diff --git a/src/shared/pipeline.ts b/src/shared/pipeline.ts
new file mode 100644
index 0000000..ebf7196
--- /dev/null
+++ b/src/shared/pipeline.ts
@@ -0,0 +1,47 @@
+import { isDocument } from './writeOps'
+
+/** Stage operators that write to the database; only a shell pipeline may end with one. */
+export const WRITE_STAGES: ReadonlySet<string> = new Set(['$out', '$merge'])
+
+/** Stage operators MongoBench cannot run: a change stream never returns a complete result. */
+export const UNSUPPORTED_STAGES: ReadonlySet<string> = new Set(['$changeStream'])
+
+/** First stage operator MongoBench refuses to run, or null when the pipeline can run. */
+export function findRejectedStage(stages: readonly unknown[]): string | null {
+  for (const stage of stages) {
+    if (!isDocument(stage)) continue
+    const key = Object.keys(stage).find((k) => WRITE_STAGES.has(k) || UNSUPPORTED_STAGES.has(k))
+    if (key !== undefined) return key
+  }
+  return null
+}
+
+/** Why a stage reported by `findRejectedStage` cannot run. */
+export function rejectedStageMessage(stage: string): string {
+  return WRITE_STAGES.has(stage)
+    ? `${stage} writes to the database; Aggregation mode only reads, run it in Shell mode`
+    : `${stage} never ends, so it cannot run here`
+}
+
+/** The `$out` / `$merge` operator ending a pipeline that writes, or null when the last stage reads. */
+export function finalWriteStage(stages: readonly unknown[]): string | null {
+  const last = stages[stages.length - 1]
+  if (!isDocument(last)) return null
+  return Object.keys(last).find((k) => WRITE_STAGES.has(k)) ?? null
+}
+
+/**
+ * Why a pipeline ending in `$out` / `$merge` cannot run, or null; earlier stages must all read.
+ * @returns The reason, prefixed with the offending stage's position ("Stage 2: …").
+ */
+export function writePipelineError(stages: readonly unknown[]): string | null {
+  for (const [index, stage] of stages.slice(0, -1).entries()) {
+    const rejected = findRejectedStage([stage])
+    if (rejected === null) continue
+    const reason = WRITE_STAGES.has(rejected)
+      ? `${rejected} must be the last stage`
+      : rejectedStageMessage(rejected)
+    return `Stage ${index + 1}: ${reason}`
+  }
+  return null
+}
diff --git a/src/shared/result.ts b/src/shared/result.ts
index 84a11e6..b533ba5 100644
--- a/src/shared/result.ts
+++ b/src/shared/result.ts
@@ -19,9 +19,13 @@ export const ErrorCodes = [
   'ssh_connect_failed',
   'ssh_auth_failed',
   'ssh_host_key_mismatch',
+  'cloudflared_not_found',
+  'cloudflared_auth_failed',
+  'cloudflared_failed',
   'driver_error',
   'not_found',
   'conflict',
+  'cancelled',
   'internal'
 ] as const
 
diff --git a/src/shared/schemas.test.ts b/src/shared/schemas.test.ts
new file mode 100644
index 0000000..33d1238
--- /dev/null
+++ b/src/shared/schemas.test.ts
@@ -0,0 +1,442 @@
+import { randomUUID } from 'node:crypto'
+import { describe, expect, it } from 'vitest'
+import type { ZodType } from 'zod'
+import {
+  AggregateRequestSchema,
+  CancelQuerySchema,
+  CloudflaredVersionSchema,
+  CollectionRefSchema,
+  ConnectionInputSchema,
+  ConnectionTestPayloadSchema,
+  ConnectionUpdateSchema,
+  CountRequestSchema,
+  CreateDatabaseSchema,
+  CreateIndexSchema,
+  CreateUserSchema,
+  DatabaseRefSchema,
+  DistinctRequestSchema,
+  DropIndexSchema,
+  DropUserSchema,
+  FindRequestSchema,
+  InsertOneRequestSchema,
+  ReplaceOneRequestSchema,
+  UpdateUserSchema
+} from './schemas'
+
+const CONNECTION_ID = '00000000-0000-4000-8000-000000000000'
+const HASH = 'ab'.repeat(32)
+const MiB = 1024 * 1024
+
+function issuePaths(schema: ZodType, input: unknown): PropertyKey[][] {
+  return schema.safeParse(input).error?.issues.map((issue) => issue.path) ?? []
+}
+
+describe('ConnectionInputSchema with a Cloudflare tunnel', () => {
+  const base = { name: 'Prod', uri: 'mongodb://mongo.internal:27017' }
+  const access = { enabled: true, hostname: 'mongo.example.com', authMethod: 'browser' as const }
+  const sshOn = {
+    enabled: true,
+    host: 'bastion.example.com',
+    username: 'deploy',
+    authMethod: 'agent' as const
+  }
+
+  it('accepts an enabled browser sign-in tunnel', () => {
+    const parsed = ConnectionInputSchema.parse({ ...base, cloudflared: access })
+    expect(parsed.cloudflared).toEqual(access)
+  })
+
+  it('accepts service-token mode with a client ID and no secret', () => {
+    const cloudflared = {
+      enabled: true,
+      hostname: 'mongo.example.com',
+      authMethod: 'serviceToken',
+      serviceTokenId: '0123456789abcdef0123456789abcdef.access'
+    }
+    expect(ConnectionInputSchema.safeParse({ ...base, cloudflared }).success).toBe(true)
+  })
+
+  it('trims hostname, client ID and binary path before checking them', () => {
+    const parsed = ConnectionInputSchema.parse({
+      ...base,
+      cloudflared: {
+        enabled: true,
+        hostname: '  mongo.example.com ',
+        authMethod: 'serviceToken',
+        serviceTokenId: ' id.access ',
+        binaryPath: ' C:\\tools\\cloudflared.exe '
+      }
+    })
+    expect(parsed.cloudflared).toMatchObject({
+      hostname: 'mongo.example.com',
+      serviceTokenId: 'id.access',
+      binaryPath: 'C:\\tools\\cloudflared.exe'
+    })
+  })
+
+  it.each(['https://mongo.example.com', 'mongo.example.com:443', 'localhost', ''])(
+    'rejects the hostname %j once enabled',
+    (hostname) => {
+      expect(
+        issuePaths(ConnectionInputSchema, { ...base, cloudflared: { ...access, hostname } })
+      ).toContainEqual(['cloudflared', 'hostname'])
+    }
+  )
+
+  it.each([undefined, '', '   '])(
+    'rejects service-token mode with the client ID %j',
+    (serviceTokenId) => {
+      const cloudflared = { ...access, authMethod: 'serviceToken', serviceTokenId }
+      expect(issuePaths(ConnectionInputSchema, { ...base, cloudflared })).toContainEqual([
+        'cloudflared',
+        'serviceTokenId'
+      ])
+    }
+  )
+
+  it.each([
+    'C:\\Windows\\System32\\calc.exe',
+    'cloudflared.exe',
+    '',
+    '\\\\attacker.invalid\\share\\cloudflared.exe'
+  ])('rejects the binary path %j once enabled', (binaryPath) => {
+    const cloudflared = { ...access, binaryPath }
+    expect(issuePaths(ConnectionInputSchema, { ...base, cloudflared })).toContainEqual([
+      'cloudflared',
+      'binaryPath'
+    ])
+  })
+
+  it.each(['serviceTokenId', 'serviceTokenSecret'])(
+    'rejects a NUL character in %s, even while switched off',
+    (field) => {
+      const cloudflared = {
+        enabled: false,
+        hostname: 'mongo.example.com',
+        authMethod: 'serviceToken',
+        serviceTokenId: 'abc.access',
+        [field]: 'abc\0def'
+      }
+      expect(issuePaths(ConnectionInputSchema, { ...base, cloudflared })).toContainEqual([
+        'cloudflared',
+        field
+      ])
+    }
+  )
+
+  it('accepts a disabled, half-filled section', () => {
+    const cloudflared = { enabled: false, hostname: 'mongo.', authMethod: 'serviceToken' }
+    expect(ConnectionInputSchema.safeParse({ ...base, cloudflared }).success).toBe(true)
+  })
+
+  it('rejects unknown keys in the section', () => {
+    const cloudflared = { ...access, token: 'secret' }
+    expect(ConnectionInputSchema.safeParse({ ...base, cloudflared }).success).toBe(false)
+  })
+
+  it('rejects SSH and Cloudflare tunnels enabled together', () => {
+    expect(
+      issuePaths(ConnectionInputSchema, { ...base, ssh: sshOn, cloudflared: access })
+    ).toContainEqual(['cloudflared', 'enabled'])
+  })
+
+  it('accepts an enabled SSH tunnel next to a disabled Cloudflare section', () => {
+    const input = { ...base, ssh: sshOn, cloudflared: { ...access, enabled: false } }
+    expect(ConnectionInputSchema.safeParse(input).success).toBe(true)
+  })
+
+  it('rejects a mongodb+srv:// connection string with the tunnel enabled', () => {
+    const input = { ...base, uri: 'mongodb+srv://cluster.example.com', cloudflared: access }
+    expect(issuePaths(ConnectionInputSchema, input)).toContainEqual(['uri'])
+  })
+
+  it('accepts a mongodb+srv:// connection string with the tunnel disabled', () => {
+    const input = {
+      ...base,
+      uri: 'mongodb+srv://cluster.example.com',
+      cloudflared: { ...access, enabled: false }
+    }
+    expect(ConnectionInputSchema.safeParse(input).success).toBe(true)
+  })
+
+  it('applies the same rules when updating and testing a connection', () => {
+    const patch = { ...base, ssh: sshOn, cloudflared: access }
+    expect(ConnectionUpdateSchema.safeParse({ id: CONNECTION_ID, patch }).success).toBe(false)
+    expect(ConnectionTestPayloadSchema.safeParse({ input: patch }).success).toBe(false)
+  })
+})
+
+describe('CloudflaredVersionSchema', () => {
+  it('accepts an absent binary path, meaning cloudflared from PATH', () => {
+    expect(CloudflaredVersionSchema.safeParse({}).success).toBe(true)
+    expect(CloudflaredVersionSchema.safeParse({ binaryPath: undefined }).success).toBe(true)
+  })
+
+  it('accepts an absolute cloudflared path and trims it', () => {
+    expect(CloudflaredVersionSchema.parse({ binaryPath: ' /usr/local/bin/cloudflared ' })).toEqual({
+      binaryPath: '/usr/local/bin/cloudflared'
+    })
+  })
+
+  it.each([
+    'C:\\Windows\\System32\\calc.exe',
+    'cloudflared',
+    '',
+    '\\\\attacker.invalid@SSL\\DavWWWRoot\\cloudflared.exe'
+  ])('rejects the binary path %j', (binaryPath) => {
+    expect(CloudflaredVersionSchema.safeParse({ binaryPath }).success).toBe(false)
+  })
+})
+
+describe('user schemas', () => {
+  const ref = { connectionId: CONNECTION_ID, db: 'admin' }
+  const roles = (count: number): Array<{ role: string; db: string }> =>
+    Array.from({ length: count }, (_, i) => ({ role: 'readWrite', db: `tenant_${i}` }))
+
+  it('accepts 200 roles on create and update', () => {
+    expect(
+      CreateUserSchema.safeParse({ ...ref, username: 'svc', password: 'pw', roles: roles(200) })
+        .success
+    ).toBe(true)
+    expect(
+      UpdateUserSchema.safeParse({ ...ref, username: 'svc', password: null, roles: roles(200) })
+        .success
+    ).toBe(true)
+  })
+
+  it('accepts 10 000 roles and rejects 10 001', () => {
+    const update = { ...ref, username: 'svc', password: null }
+    expect(UpdateUserSchema.safeParse({ ...update, roles: roles(10_000) }).success).toBe(true)
+    expect(UpdateUserSchema.safeParse({ ...update, roles: roles(10_001) }).success).toBe(false)
+    expect(
+      CreateUserSchema.safeParse({ ...ref, username: 'svc', password: 'pw', roles: roles(10_001) })
+        .success
+    ).toBe(false)
+  })
+
+  it('accepts roles: null on update to leave the roles unchanged', () => {
+    const parsed = UpdateUserSchema.parse({ ...ref, username: 'svc', password: 'new', roles: null })
+    expect(parsed.roles).toBeNull()
+  })
+
+  it.each(['report reader', ' bob', 'bob '])(
+    'updates and drops the existing user %j verbatim',
+    (username) => {
+      expect(
+        UpdateUserSchema.parse({ ...ref, username, password: 'pw', roles: null }).username
+      ).toBe(username)
+      expect(DropUserSchema.parse({ ...ref, username }).username).toBe(username)
+    }
+  )
+
+  it('trims the name of a new user', () => {
+    const parsed = CreateUserSchema.parse({ ...ref, username: ' bob ', password: 'pw', roles: [] })
+    expect(parsed.username).toBe('bob')
+  })
+
+  it.each(['a b', 'a\tb', '   '])('rejects the new user name %j', (username) => {
+    expect(
+      CreateUserSchema.safeParse({ ...ref, username, password: 'pw', roles: [] }).success
+    ).toBe(false)
+  })
+
+  it('rejects a NUL character in every user name', () => {
+    const username = 'a\0b'
+    expect(
+      CreateUserSchema.safeParse({ ...ref, username, password: 'pw', roles: [] }).success
+    ).toBe(false)
+    expect(
+      UpdateUserSchema.safeParse({ ...ref, username, password: 'pw', roles: null }).success
+    ).toBe(false)
+    expect(DropUserSchema.safeParse({ ...ref, username }).success).toBe(false)
+  })
+
+  it('rejects an empty name on update and drop', () => {
+    expect(
+      UpdateUserSchema.safeParse({ ...ref, username: '', password: 'pw', roles: null }).success
+    ).toBe(false)
+    expect(DropUserSchema.safeParse({ ...ref, username: '' }).success).toBe(false)
+  })
+})
+
+describe('index name schemas', () => {
+  const ref = { connectionId: CONNECTION_ID, db: 'app', coll: 'players' }
+
+  it.each(['$**_1', 'a.$**_1'])('drops the wildcard index %j', (name) => {
+    expect(DropIndexSchema.safeParse({ ...ref, name }).success).toBe(true)
+  })
+
+  it('drops an index with a 200-character name', () => {
+    expect(DropIndexSchema.safeParse({ ...ref, name: 'k'.repeat(200) }).success).toBe(true)
+  })
+
+  it.each([
+    ['an empty name', ''],
+    ['a NUL character', 'a\0b'],
+    ['more than 1024 characters', 'k'.repeat(1025)]
+  ])('rejects an index name with %s', (_case, name) => {
+    expect(DropIndexSchema.safeParse({ ...ref, name }).success).toBe(false)
+  })
+
+  it('accepts a wildcard index name on create', () => {
+    const request = { ...ref, keys: '{"$**":1}', options: { name: '$**_1' } }
+    expect(CreateIndexSchema.safeParse(request).success).toBe(true)
+  })
+})
+
+describe('payload caps', () => {
+  const ref = { connectionId: CONNECTION_ID, db: 'app', coll: 'players' }
+  const oidIn = JSON.stringify({
+    _id: {
+      $in: Array.from({ length: 32_000 }, (_, i) => ({ $oid: i.toString(16).padStart(24, '0') }))
+    }
+  })
+
+  it('accepts skip and limit past one million', () => {
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 5_000_000, limit: 5_000_000 }).success).toBe(
+      true
+    )
+  })
+
+  it('accepts skip up to the largest safe integer', () => {
+    expect(FindRequestSchema.safeParse({ ...ref, skip: Number.MAX_SAFE_INTEGER }).success).toBe(
+      true
+    )
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 2 ** 53 }).success).toBe(false)
+  })
+
+  it('rejects a negative or fractional skip', () => {
+    expect(FindRequestSchema.safeParse({ ...ref, skip: -1 }).success).toBe(false)
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 1.5 }).success).toBe(false)
+  })
+
+  it('treats an absent limit as no limit and rejects limit 0', () => {
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 0 }).success).toBe(true)
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 0, limit: 0 }).success).toBe(false)
+  })
+
+  it('accepts a filter of more than 1 MiB', () => {
+    expect(oidIn.length).toBeGreaterThan(MiB)
+    expect(CountRequestSchema.safeParse({ ...ref, filter: oidIn }).success).toBe(true)
+    expect(FindRequestSchema.safeParse({ ...ref, filter: oidIn, skip: 0 }).success).toBe(true)
+  })
+
+  it('accepts a pipeline of more than 1 MiB', () => {
+    const pipeline = JSON.stringify([{ $match: JSON.parse(oidIn) }])
+    expect(AggregateRequestSchema.safeParse({ ...ref, pipeline }).success).toBe(true)
+  })
+
+  it('rejects a filter above 16 MiB', () => {
+    const filter = 'x'.repeat(16 * MiB + 1)
+    expect(CountRequestSchema.safeParse({ ...ref, filter }).success).toBe(false)
+  })
+
+  it('accepts a 2 MiB document on replace and insert', () => {
+    const document = JSON.stringify({
+      _id: { $oid: '507f1f77bcf86cd799439011' },
+      blob: { $binary: { base64: 'A'.repeat(2 * MiB), subType: '00' } }
+    })
+    expect(
+      ReplaceOneRequestSchema.safeParse({
+        ...ref,
+        id: '{"$oid":"507f1f77bcf86cd799439011"}',
+        expectedHash: HASH,
+        replacement: document
+      }).success
+    ).toBe(true)
+    expect(InsertOneRequestSchema.safeParse({ ...ref, document }).success).toBe(true)
+  })
+
+  it('rejects a document above 64 MiB', () => {
+    const document = 'x'.repeat(64 * MiB + 1)
+    expect(InsertOneRequestSchema.safeParse({ ...ref, document }).success).toBe(false)
+  })
+})
+
+describe('database name schemas', () => {
+  const create = (db: string): unknown => ({
+    connectionId: CONNECTION_ID,
+    db,
+    firstColl: 'items'
+  })
+
+  it.each(['app:prod', 'tenant*42', 'a<b>', 'a|b', 'a?b'])(
+    'opens the server-legal database %j but does not create it',
+    (db) => {
+      expect(DatabaseRefSchema.safeParse({ connectionId: CONNECTION_ID, db }).success).toBe(true)
+      expect(
+        CollectionRefSchema.safeParse({ connectionId: CONNECTION_ID, db, coll: 'items' }).success
+      ).toBe(true)
+      expect(CreateDatabaseSchema.safeParse(create(db)).success).toBe(false)
+    }
+  )
+
+  it.each(['a.b', 'a b', 'a\0b', 'a/b', 'a\\b', 'a"b', 'a$b', ''])(
+    'rejects the database name %j everywhere',
+    (db) => {
+      expect(DatabaseRefSchema.safeParse({ connectionId: CONNECTION_ID, db }).success).toBe(false)
+      expect(CreateDatabaseSchema.safeParse(create(db)).success).toBe(false)
+    }
+  )
+
+  it('creates a portable database name', () => {
+    expect(CreateDatabaseSchema.safeParse(create('app_prod-2')).success).toBe(true)
+  })
+})
+
+describe('query request ids and options', () => {
+  const ref = { connectionId: CONNECTION_ID, db: 'app', coll: 'players' }
+
+  it('accepts a random UUID as requestId on find, count and aggregate', () => {
+    const requestId = randomUUID()
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 0, requestId }).success).toBe(true)
+    expect(CountRequestSchema.safeParse({ ...ref, requestId }).success).toBe(true)
+    expect(AggregateRequestSchema.safeParse({ ...ref, pipeline: '[]', requestId }).success).toBe(
+      true
+    )
+  })
+
+  it('rejects a requestId that is not a UUID', () => {
+    const requestId = 'run-1'
+    expect(FindRequestSchema.safeParse({ ...ref, skip: 0, requestId }).success).toBe(false)
+    expect(CountRequestSchema.safeParse({ ...ref, requestId }).success).toBe(false)
+    expect(AggregateRequestSchema.safeParse({ ...ref, pipeline: '[]', requestId }).success).toBe(
+      false
+    )
+  })
+
+  it('accepts a boolean exact flag on count and nothing else', () => {
+    expect(CountRequestSchema.safeParse({ ...ref, exact: true }).success).toBe(true)
+    expect(CountRequestSchema.safeParse({ ...ref, exact: false }).success).toBe(true)
+    expect(CountRequestSchema.safeParse({ ...ref, exact: 'yes' }).success).toBe(false)
+  })
+
+  it('accepts distinct with a field and an optional filter', () => {
+    expect(DistinctRequestSchema.safeParse({ ...ref, field: 'meta.region' }).success).toBe(true)
+    expect(
+      DistinctRequestSchema.safeParse({ ...ref, field: 'meta.region', filter: '{"active":true}' })
+        .success
+    ).toBe(true)
+  })
+
+  it('rejects distinct with an empty or over-long field', () => {
+    expect(DistinctRequestSchema.safeParse({ ...ref, field: '' }).success).toBe(false)
+    expect(DistinctRequestSchema.safeParse({ ...ref, field: 'a'.repeat(1025) }).success).toBe(false)
+  })
+
+  it('rejects a requestId on distinct, which is not cancellable server-side', () => {
+    const request = { ...ref, field: 'meta.region', requestId: randomUUID() }
+    expect(DistinctRequestSchema.safeParse(request).success).toBe(false)
+  })
+
+  it('accepts a cancel request with a UUID', () => {
+    const requestId = randomUUID()
+    expect(CancelQuerySchema.parse({ requestId })).toEqual({ requestId })
+  })
+
+  it('rejects a cancel request without a UUID or with extra keys', () => {
+    expect(CancelQuerySchema.safeParse({}).success).toBe(false)
+    expect(CancelQuerySchema.safeParse({ requestId: 'run-1' }).success).toBe(false)
+    expect(CancelQuerySchema.safeParse({ requestId: randomUUID(), all: true }).success).toBe(false)
+  })
+})
diff --git a/src/shared/schemas.ts b/src/shared/schemas.ts
index c16f3d7..ce214e2 100644
--- a/src/shared/schemas.ts
+++ b/src/shared/schemas.ts
@@ -1,4 +1,10 @@
 import { z } from 'zod'
+import {
+  cloudflaredTunnelProblems,
+  INVALID_CLOUDFLARED_PATH_MESSAGE,
+  isCloudflaredExecutable
+} from './cloudflared'
+import { MAX_INSERT_DOCUMENTS } from './types'
 
 const AuthMechanismSchema = z.enum(['SCRAM-SHA-256', 'SCRAM-SHA-1', 'DEFAULT'])
 const ReadPreferenceSchema = z.enum([
@@ -10,6 +16,7 @@ const ReadPreferenceSchema = z.enum([
 ])
 const UuidEncodingSchema = z.enum(['default', 'java'])
 const SshAuthMethodSchema = z.enum(['password', 'privateKey', 'agent'])
+const CloudflaredAuthMethodSchema = z.enum(['browser', 'serviceToken'])
 
 /**
  * Fields stay permissive while `enabled` is false so a half-filled tunnel
@@ -45,6 +52,31 @@ export const SshTunnelInputSchema = z
     }
   })
 
+/** Permissive like the SSH tunnel; ConnectionInputSchema checks an enabled one since its rules need the URI. */
+export const CloudflaredTunnelInputSchema = z
+  .object({
+    enabled: z.boolean(),
+    hostname: z.string().trim().max(253),
+    authMethod: CloudflaredAuthMethodSchema,
+    // The token reaches cloudflared as environment variables, which cannot hold a NUL.
+    serviceTokenId: z
+      .string()
+      .trim()
+      .max(255)
+      .refine((v) => !v.includes('\0'), 'Service token client ID must not contain NUL characters')
+      .optional(),
+    serviceTokenSecret: z
+      .string()
+      .max(1024)
+      .refine(
+        (v) => !v.includes('\0'),
+        'Service token client secret must not contain NUL characters'
+      )
+      .optional(),
+    binaryPath: z.string().trim().max(4096).optional()
+  })
+  .strict()
+
 export const ConnectionInputSchema = z
   .object({
     name: z.string().trim().min(1).max(120),
@@ -65,6 +97,7 @@ export const ConnectionInputSchema = z
     serverSelectionTimeoutMS: z.number().int().min(1000).max(60_000).optional(),
     appName: z.string().trim().max(120).optional(),
     ssh: SshTunnelInputSchema.optional(),
+    cloudflared: CloudflaredTunnelInputSchema.optional(),
     directConnection: z.boolean().optional(),
     replicaSet: z.string().trim().max(120).optional(),
     readPreference: ReadPreferenceSchema.optional(),
@@ -79,6 +112,19 @@ export const ConnectionInputSchema = z
     retryReads: z.boolean().optional()
   })
   .strict()
+  .superRefine((input, ctx) => {
+    if (input.cloudflared?.enabled !== true) return
+    if (input.ssh?.enabled === true) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Use either the SSH tunnel or the Cloudflare tunnel, not both',
+        path: ['cloudflared', 'enabled']
+      })
+    }
+    for (const { path, message } of cloudflaredTunnelProblems(input)) {
+      ctx.addIssue({ code: 'custom', message, path })
+    }
+  })
 
 export const ConnectionUpdateSchema = z
   .object({
@@ -100,13 +146,18 @@ export const ReorderConnectionsSchema = z
   .object({ ids: z.array(z.string().uuid()).min(1) })
   .strict()
 
+// Any name a server can hold: only the characters MongoDB rejects on every platform.
 const dbName = z
   .string()
   .min(1)
   .max(64)
-  .refine((v) => !/[\s/\\."$*<>:|?]/.test(v), 'invalid database name')
+  .refine((v) => !/[\0/\\. "$]/.test(v), 'invalid database name')
+// New databases stay portable: Windows servers also reject these.
+const newDbName = dbName.refine((v) => !/[\s*<>:|?]/.test(v), 'invalid database name')
 const collName = z.string().min(1).max(255)
-const ejsonString = z.string().max(64 * 1024)
+// Payloads are bounded by MongoDB itself (16 MiB BSON), not by an arbitrary smaller cap.
+const ejsonString = z.string().max(16 * 1024 * 1024)
+const requestIdSchema = z.string().uuid()
 
 export const DatabaseRefSchema = z
   .object({
@@ -148,7 +199,7 @@ export const CreateCollectionSchema = z
 export const CreateDatabaseSchema = z
   .object({
     connectionId: z.string().uuid(),
-    db: dbName,
+    db: newDbName,
     firstColl: validCollName
   })
   .strict()
@@ -159,6 +210,12 @@ const usernameSchema = z
   .min(1)
   .max(255)
   .refine((v) => !/[\s\0]/.test(v), 'invalid username')
+// Users created elsewhere may carry whitespace; they must still be editable and droppable verbatim.
+const existingUsernameSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .refine((v) => !v.includes('\0'), 'invalid username')
 
 const RoleSchema = z
   .object({
@@ -166,6 +223,8 @@ const RoleSchema = z
     db: z.string().trim().min(1).max(64)
   })
   .strict()
+// MongoDB has no role-count limit; only the 16 MiB user document bounds it.
+const rolesList = z.array(RoleSchema).max(10_000)
 
 export const CreateUserSchema = z
   .object({
@@ -173,7 +232,7 @@ export const CreateUserSchema = z
     db: dbName,
     username: usernameSchema,
     password: z.string().min(1).max(1024),
-    roles: z.array(RoleSchema).max(64)
+    roles: rolesList
   })
   .strict()
 
@@ -181,9 +240,9 @@ export const UpdateUserSchema = z
   .object({
     connectionId: z.string().uuid(),
     db: dbName,
-    username: usernameSchema,
+    username: existingUsernameSchema,
     password: z.string().min(1).max(1024).nullable(),
-    roles: z.array(RoleSchema).max(64).nullable()
+    roles: rolesList.nullable()
   })
   .strict()
 
@@ -191,7 +250,7 @@ export const DropUserSchema = z
   .object({
     connectionId: z.string().uuid(),
     db: dbName,
-    username: usernameSchema
+    username: existingUsernameSchema
   })
   .strict()
 
@@ -203,9 +262,10 @@ export const FindRequestSchema = z
     filter: ejsonString.optional(),
     projection: ejsonString.optional(),
     sort: ejsonString.optional(),
-    skip: z.number().int().min(0).max(1_000_000),
+    skip: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
     /** Omit / undefined = no limit. */
-    limit: z.number().int().min(1).max(1_000_000).optional()
+    limit: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
+    requestId: requestIdSchema.optional()
   })
   .strict()
 
@@ -214,7 +274,9 @@ export const CountRequestSchema = z
     connectionId: z.string().uuid(),
     db: dbName,
     coll: collName,
-    filter: ejsonString.optional()
+    filter: ejsonString.optional(),
+    exact: z.boolean().optional(),
+    requestId: requestIdSchema.optional()
   })
   .strict()
 
@@ -223,19 +285,33 @@ export const AggregateRequestSchema = z
     connectionId: z.string().uuid(),
     db: dbName,
     coll: collName,
-    pipeline: z.string().max(256 * 1024)
+    pipeline: ejsonString,
+    requestId: requestIdSchema.optional()
+  })
+  .strict()
+
+export const DistinctRequestSchema = z
+  .object({
+    connectionId: z.string().uuid(),
+    db: dbName,
+    coll: collName,
+    field: z.string().min(1).max(1024),
+    filter: ejsonString.optional()
   })
   .strict()
 
+export const CancelQuerySchema = z.object({ requestId: requestIdSchema }).strict()
+
 const idString = z
   .string()
   .min(1)
   .max(64 * 1024)
 const hashString = z.string().regex(/^[0-9a-f]{64}$/, 'expected sha-256 hex digest')
+// The server enforces the 16 MiB BSON limit; the JSON text of such a document is larger.
 const documentString = z
   .string()
   .min(1)
-  .max(1024 * 1024)
+  .max(64 * 1024 * 1024)
 
 export const ReplaceOneRequestSchema = z
   .object({
@@ -262,7 +338,7 @@ export const InsertManyRequestSchema = z
     connectionId: z.string().uuid(),
     db: dbName,
     coll: collName,
-    documents: z.array(documentString).min(1).max(10_000)
+    documents: z.array(documentString).min(1).max(MAX_INSERT_DOCUMENTS)
   })
   .strict()
 
@@ -285,11 +361,61 @@ export const DeleteManyRequestSchema = z
   })
   .strict()
 
+const writeOptions = { options: ejsonString.optional() }
+
+const WriteOpSchema = z.discriminatedUnion('method', [
+  z.object({ method: z.literal('insertOne'), document: documentString, ...writeOptions }).strict(),
+  z
+    .object({
+      method: z.literal('insertMany'),
+      documents: z.array(documentString).min(1).max(MAX_INSERT_DOCUMENTS),
+      ...writeOptions
+    })
+    .strict(),
+  z
+    .object({
+      method: z.enum(['updateOne', 'updateMany', 'findOneAndUpdate']),
+      filter: ejsonString,
+      update: ejsonString,
+      ...writeOptions
+    })
+    .strict(),
+  z
+    .object({
+      method: z.enum(['replaceOne', 'findOneAndReplace']),
+      filter: ejsonString,
+      replacement: documentString,
+      ...writeOptions
+    })
+    .strict(),
+  z
+    .object({
+      method: z.enum(['deleteOne', 'deleteMany', 'findOneAndDelete']),
+      filter: ejsonString,
+      ...writeOptions
+    })
+    .strict(),
+  z
+    .object({ method: z.literal('bulkWrite'), operations: documentString, ...writeOptions })
+    .strict(),
+  z.object({ method: z.literal('aggregate'), pipeline: ejsonString }).strict()
+])
+
+export const WriteRequestSchema = z
+  .object({
+    connectionId: z.string().uuid(),
+    db: dbName,
+    coll: collName,
+    op: WriteOpSchema
+  })
+  .strict()
+
+// The server validates names; driver-generated ones contain '$' (wildcard `$**_1`) and exceed 127 chars since 4.2.
 const indexName = z
   .string()
   .min(1)
-  .max(127)
-  .refine((v) => !v.includes('$') && !v.includes('\0'), 'invalid index name')
+  .max(1024)
+  .refine((v) => !v.includes('\0'), 'invalid index name')
 
 const ejsonObject = z
   .string()
@@ -337,3 +463,14 @@ export const DropIndexSchema = z
     name: indexName
   })
   .strict()
+
+export const CloudflaredVersionSchema = z
+  .object({
+    binaryPath: z
+      .string()
+      .trim()
+      .max(4096)
+      .refine(isCloudflaredExecutable, INVALID_CLOUDFLARED_PATH_MESSAGE)
+      .optional()
+  })
+  .strict()
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 7e0eaf1..af499ab 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -79,6 +79,42 @@ export type SshTunnelView = {
   hasStoredPassphrase: boolean
 }
 
+export type CloudflaredAuthMethod = 'browser' | 'serviceToken'
+
+/** Cloudflare Access tunnel settings; the driver dials only the tunnel's loopback port, never the URI's hosts. */
+export type CloudflaredTunnelInput = {
+  enabled: boolean
+  /** Public hostname of the Access application, e.g. `mongo.example.com`. */
+  hostname: string
+  authMethod: CloudflaredAuthMethod
+  serviceTokenId?: string
+  /** Cleartext only in-flight. Blank on edit = keep what is stored, if hostname and client ID are unchanged. */
+  serviceTokenSecret?: string
+  /** Absent = `cloudflared` from PATH. */
+  binaryPath?: string
+}
+
+/** On-disk shape — main process only. */
+export type StoredCloudflaredTunnel = {
+  enabled: boolean
+  hostname: string
+  authMethod: CloudflaredAuthMethod
+  serviceTokenId?: string
+  /** Base64 of safeStorage.encryptString(cleartext). */
+  encryptedServiceTokenSecret?: string
+  binaryPath?: string
+}
+
+/** Renderer-facing view — never carries cleartext or ciphertext secrets. */
+export type CloudflaredTunnelView = {
+  enabled: boolean
+  hostname: string
+  authMethod: CloudflaredAuthMethod
+  serviceTokenId?: string
+  binaryPath?: string
+  hasStoredServiceTokenSecret: boolean
+}
+
 export type AdvancedOptions = {
   directConnection?: boolean
   replicaSet?: string
@@ -111,6 +147,8 @@ export type StoredConnection = {
   appName?: string
   /** Absent on connections that reach their hosts directly. */
   ssh?: StoredSshTunnel
+  /** Absent on connections that reach their hosts directly. */
+  cloudflared?: StoredCloudflaredTunnel
   // Advanced driver options
   directConnection?: boolean
   replicaSet?: string
@@ -148,6 +186,8 @@ export type ConnectionConfig = {
   appName?: string
   /** Absent on connections that reach their hosts directly. */
   ssh?: SshTunnelView
+  /** Absent on connections that reach their hosts directly. */
+  cloudflared?: CloudflaredTunnelView
   directConnection?: boolean
   replicaSet?: string
   readPreference?: ReadPreference
@@ -185,6 +225,7 @@ export type ConnectionInput = {
   serverSelectionTimeoutMS?: number
   appName?: string
   ssh?: SshTunnelInput
+  cloudflared?: CloudflaredTunnelInput
   directConnection?: boolean
   replicaSet?: string
   readPreference?: ReadPreference
@@ -348,10 +389,18 @@ export type DatabaseUser = {
   user: string
   db: string
   roles: DatabaseUserRole[]
+  /** Relaxed EJSON. */
   customData?: Record<string, unknown>
   mechanisms?: string[]
 }
 
+/** A role as reported by `rolesInfo`, built-in roles included. */
+export type DatabaseRoleInfo = {
+  role: string
+  db: string
+  isBuiltin: boolean
+}
+
 export type CreateUserPayload = {
   connectionId: string
   db: string
@@ -387,13 +436,15 @@ export type ConnectionUpdatePayload = {
  *   `{$oid:…}`/`{$date:…}`/…). Used by the table view.
  * - `canonical`: the document as a canonical-EJSON string (every BSON type
  *   wrapped). Used by the document editor for type-precise round-trips.
- * - `id`: the document's `_id` in canonical-EJSON string form — stable
- *   identity for row keys and write preconditions.
+ * - `id`: the document's `_id` in canonical-EJSON string form — the write
+ *   target for replace / delete. null when the result has no `_id`; only
+ *   unique for documents read from a collection, derived rows (aggregation,
+ *   distinct) may repeat it.
  * - `hash`: sha-256 over `canonical`. Used for optimistic concurrency on
  *   replace / delete.
  */
 export type DocumentEnvelope = {
-  id: string
+  id: string | null
   data: Record<string, unknown>
   canonical: string
   hash: string
@@ -478,6 +529,8 @@ export type FindRequest = {
   skip: number
   /** Omit or pass undefined to fetch all matching documents. */
   limit?: number
+  /** Lets `query.cancel` abort this run server-side. */
+  requestId?: string
 }
 
 export type FindResponse = {
@@ -485,17 +538,27 @@ export type FindResponse = {
   tookMs: number
 }
 
+/** Max rows an aggregation, shell or distinct run returns; one extra row is fetched to detect truncation. */
+export const RESULT_CAP = 1000
+
+/** Max documents one insert request carries. */
+export const MAX_INSERT_DOCUMENTS = 10_000
+
 export type AggregateRequest = {
   connectionId: string
   db: string
   coll: string
   /** Canonical-EJSON string of the pipeline (an array of stage objects). */
   pipeline: string
+  /** Lets `query.cancel` abort this run server-side. */
+  requestId?: string
 }
 
 export type AggregateResponse = {
   documents: DocumentEnvelope[]
   tookMs: number
+  /** More than RESULT_CAP documents came back; only the first RESULT_CAP are included. */
+  truncated: boolean
 }
 
 export type CountRequest = {
@@ -503,11 +566,163 @@ export type CountRequest = {
   db: string
   coll: string
   filter?: string
+  /** Always countDocuments; otherwise an empty filter uses the metadata estimate. */
+  exact?: boolean
+  /** Lets `query.cancel` abort this run server-side. */
+  requestId?: string
 }
 
 export type CountResponse = {
   count: number
   estimated: boolean
+  tookMs: number
+}
+
+export type DistinctRequest = {
+  connectionId: string
+  db: string
+  coll: string
+  field: string
+  filter?: string
+}
+
+/** Distinct values, each wrapped as a `{ value }` document; capped at RESULT_CAP. */
+export type DistinctResponse = {
+  documents: DocumentEnvelope[]
+  tookMs: number
+  truncated: boolean
+}
+
+export type CancelQueryRequest = {
+  requestId: string
+}
+
+/** Collection methods that write; also the write methods Shell mode runs. */
+export const WRITE_METHODS = [
+  'insertOne',
+  'insertMany',
+  'updateOne',
+  'updateMany',
+  'replaceOne',
+  'deleteOne',
+  'deleteMany',
+  'findOneAndUpdate',
+  'findOneAndReplace',
+  'findOneAndDelete',
+  'bulkWrite'
+] as const
+
+export type WriteMethod = (typeof WRITE_METHODS)[number]
+
+/**
+ * A write Shell mode runs, every value a canonical-EJSON string. `options` is the method's
+ * options object; an aggregation write is a pipeline ending in `$out` or `$merge`.
+ */
+export type WriteOp =
+  | { method: 'insertOne'; document: string; options?: string }
+  | { method: 'insertMany'; documents: string[]; options?: string }
+  | {
+      method: 'updateOne' | 'updateMany' | 'findOneAndUpdate'
+      filter: string
+      /** Update operators document, or an update pipeline array. */
+      update: string
+      options?: string
+    }
+  | {
+      method: 'replaceOne' | 'findOneAndReplace'
+      filter: string
+      replacement: string
+      options?: string
+    }
+  | { method: 'deleteOne' | 'deleteMany' | 'findOneAndDelete'; filter: string; options?: string }
+  | { method: 'bulkWrite'; operations: string; options?: string }
+  | { method: 'aggregate'; pipeline: string }
+
+export type WriteRequest = {
+  connectionId: string
+  db: string
+  coll: string
+  op: WriteOp
+}
+
+export type WriteResponse = {
+  tookMs: number
+  /** Counters the server reported for this method; absent ones do not apply to it. */
+  counts: {
+    inserted?: number
+    matched?: number
+    modified?: number
+    deleted?: number
+    upserted?: number
+  }
+  /** Canonical EJSON of the inserted or upserted `_id`s, at most RESULT_CAP. */
+  ids: string[]
+  /** More ids existed than `ids` holds. */
+  idsTruncated: boolean
+  /**
+   * findOneAnd*: the returned document, null when nothing matched; absent for other methods.
+   * Main decodes it with value promotion (an integral Double may read as Int32): not round-trippable.
+   */
+  document?: DocumentEnvelope | null
+}
+
+/** BSON type of a sampled value; `uuid` / `uuidLegacy` split binData subtypes 04 / 03 out of `binData`. */
+export type BsonTypeName =
+  | 'double'
+  | 'int'
+  | 'long'
+  | 'decimal'
+  | 'string'
+  | 'bool'
+  | 'date'
+  | 'objectId'
+  | 'uuid'
+  | 'uuidLegacy'
+  | 'binData'
+  | 'null'
+  | 'undefined'
+  | 'regex'
+  | 'timestamp'
+  | 'object'
+  | 'array'
+  | 'minKey'
+  | 'maxKey'
+  | 'javascript'
+  | 'symbol'
+  | 'dbPointer'
+  | 'dbRef'
+
+export type TypeCounts = Partial<Record<BsonTypeName, number>>
+
+export type SchemaValue = {
+  /** Canonical-EJSON JSON text of the value. */
+  ejson: string
+  count: number
+}
+
+export type SchemaField = {
+  /** Dot notation; array elements share their parent's path, keys of a map-like object collapse to `*`. */
+  path: string
+  /** Sampled documents containing the path at least once. */
+  docCount: number
+  /** Occurrences per type; an array counts once as `array`, its elements count in `elementTypes`. */
+  types: TypeCounts
+  elementTypes?: TypeCounts
+  /** Most frequent distinct scalar values, by count. */
+  values?: SchemaValue[]
+  /** More distinct values occurred than `values` holds. */
+  valuesTruncated?: boolean
+  /** Object whose keys are data (ids, numbers) rather than a fixed set of fields. */
+  mapLike?: boolean
+}
+
+export type CollectionSchema = {
+  /** Number of documents the schema was inferred from. */
+  sampleSize: number
+  /** Sorted by path. */
+  fields: SchemaField[]
+  /** The field cap was hit; rarer paths are missing. */
+  truncated: boolean
 }
 
 export type DatabaseRef = {
@@ -535,11 +750,13 @@ export type IndexInfo = {
   unique?: boolean
   sparse?: boolean
   expireAfterSeconds?: number
+  /** Relaxed EJSON. */
   partialFilterExpression?: Record<string, unknown>
+  /** Relaxed EJSON. */
   collation?: Record<string, unknown>
   hidden?: boolean
   background?: boolean
-  /** text index — per-field weight overrides. */
+  /** text index — per-field weight overrides, relaxed EJSON. */
   weights?: Record<string, number>
   /** text index — language used when a doc has no explicit `language`. */
   default_language?: string
@@ -552,10 +769,46 @@ export type IndexInfo = {
   /** 2d index — coordinate min/max. */
   min?: number
   max?: number
-  /** wildcard index — projection of paths to include/exclude. */
+  /** wildcard index — projection of paths to include/exclude, relaxed EJSON. */
   wildcardProjection?: Record<string, unknown>
-  /** Bytes on disk; populated from collStats's `indexSizes`. */
+}
+
+/** Why one source of index statistics could not be read; `message` is the server's text. */
+export type IndexStatsUnavailable = {
+  reason: 'unauthorized' | 'unsupported' | 'failed'
+  message: string
+}
+
+/** One mongod's `$indexStats` counters for one index. */
+export type IndexUsageSample = {
+  /** host:port of the mongod that counted. */
+  host: string
+  /** Sharded clusters only. */
+  shard?: string
+  /** User operations that used the index since `since`. */
+  ops: number
+  /** ISO-8601 instant the counter started (mongod start, index build or collMod). */
+  since: string
+}
+
+/** Runtime statistics of one index, merged across shards. */
+export type IndexRuntimeStats = {
+  name: string
+  /** Bytes on disk summed across shards; absent when not reported. */
   size?: number
+  /** A build is in progress on at least one shard. */
+  building: boolean
+  /** Empty when usage is unavailable or no mongod reported this index. */
+  usage: IndexUsageSample[]
+}
+
+/** Result of `indexes:stats`; each source degrades independently. */
+export type IndexStatsReport = {
+  indexes: IndexRuntimeStats[]
+  /** null when `$indexStats` succeeded. */
+  usageUnavailable: IndexStatsUnavailable | null
+  /** null when `$collStats` storage stats succeeded. */
+  storageUnavailable: IndexStatsUnavailable | null
 }
 
 export type IndexCreateOptions = {
diff --git a/src/shared/writeOps.test.ts b/src/shared/writeOps.test.ts
new file mode 100644
index 0000000..9063f89
--- /dev/null
+++ b/src/shared/writeOps.test.ts
@@ -0,0 +1,434 @@
+import { describe, expect, it } from 'vitest'
+import { WRITE_METHODS } from './types'
+import {
+  BULK_OPERATION_FIELDS,
+  BULK_OPERATION_OPTIONS,
+  BULK_WRITE_OPERATIONS,
+  EXCLUSIVE_OPTIONS,
+  UPDATE_PIPELINE_STAGES,
+  WRITE_ARGUMENTS,
+  WRITE_OPTIONS,
+  bulkWriteError,
+  filterError,
+  insertDocumentError,
+  isDocument,
+  replacementError,
+  updateError,
+  writeOptionsError
+} from './writeOps'
+
+const STAGE_LIST = '$addFields, $set, $project, $unset, $replaceRoot, $replaceWith'
+
+describe('UPDATE_PIPELINE_STAGES', () => {
+  it('holds exactly the stages MongoDB allows in an update pipeline', () => {
+    expect([...UPDATE_PIPELINE_STAGES]).toEqual([
+      '$addFields',
+      '$set',
+      '$project',
+      '$unset',
+      '$replaceRoot',
+      '$replaceWith'
+    ])
+  })
+})
+
+describe('BULK_WRITE_OPERATIONS', () => {
+  it('lists the six operations bulkWrite accepts', () => {
+    expect(BULK_WRITE_OPERATIONS).toEqual([
+      'insertOne',
+      'updateOne',
+      'updateMany',
+      'replaceOne',
+      'deleteOne',
+      'deleteMany'
+    ])
+  })
+})
+
+describe('WRITE_OPTIONS', () => {
+  it('has an entry for every write method', () => {
+    expect(Object.keys(WRITE_OPTIONS).sort()).toEqual([...WRITE_METHODS].sort())
+  })
+
+  it.each([
+    ['insertOne', ['bypassDocumentValidation']],
+    ['insertMany', ['ordered', 'bypassDocumentValidation']],
+    [
+      'updateOne',
+      ['collation', 'hint', 'let', 'upsert', 'arrayFilters', 'bypassDocumentValidation']
+    ],
+    [
+      'updateMany',
+      ['collation', 'hint', 'let', 'upsert', 'arrayFilters', 'bypassDocumentValidation']
+    ],
+    ['replaceOne', ['collation', 'hint', 'let', 'upsert', 'bypassDocumentValidation']],
+    ['deleteOne', ['collation', 'hint', 'let']],
+    ['deleteMany', ['collation', 'hint', 'let']],
+    [
+      'findOneAndUpdate',
+      [
+        'collation',
+        'hint',
+        'let',
+        'upsert',
+        'arrayFilters',
+        'bypassDocumentValidation',
+        'projection',
+        'sort',
+        'returnDocument',
+        'returnNewDocument'
+      ]
+    ],
+    [
+      'findOneAndReplace',
+      [
+        'collation',
+        'hint',
+        'let',
+        'upsert',
+        'bypassDocumentValidation',
+        'projection',
+        'sort',
+        'returnDocument',
+        'returnNewDocument'
+      ]
+    ],
+    ['findOneAndDelete', ['collation', 'hint', 'let', 'projection', 'sort']],
+    ['bulkWrite', ['ordered', 'bypassDocumentValidation']]
+  ] as const)('%s accepts exactly %j', (method, keys) => {
+    expect(Object.keys(WRITE_OPTIONS[method])).toEqual(keys)
+  })
+})
+
+describe('isDocument', () => {
+  it('accepts objects and rejects null, arrays and primitives', () => {
+    expect([{}, { a: 1 }, null, [], 'x', 1].map(isDocument)).toEqual([
+      true,
+      true,
+      false,
+      false,
+      false,
+      false
+    ])
+  })
+})
+
+describe('EXCLUSIVE_OPTIONS', () => {
+  it('pairs returnDocument with returnNewDocument, which choose the same document', () => {
+    expect(EXCLUSIVE_OPTIONS).toEqual([['returnDocument', 'returnNewDocument']])
+  })
+})
+
+describe('WRITE_ARGUMENTS', () => {
+  it('has an entry for every write method', () => {
+    expect(Object.keys(WRITE_ARGUMENTS).sort()).toEqual([...WRITE_METHODS].sort())
+  })
+
+  it.each([
+    ['insertOne', ['document']],
+    ['insertMany', ['documents']],
+    ['updateOne', ['filter', 'update']],
+    ['updateMany', ['filter', 'update']],
+    ['replaceOne', ['filter', 'replacement']],
+    ['deleteOne', ['filter']],
+    ['deleteMany', ['filter']],
+    ['findOneAndUpdate', ['filter', 'update']],
+    ['findOneAndReplace', ['filter', 'replacement']],
+    ['findOneAndDelete', ['filter']],
+    ['bulkWrite', ['operations']]
+  ] as const)('%s takes %j before its options', (method, args) => {
+    expect(WRITE_ARGUMENTS[method]).toEqual(args)
+  })
+})
+
+describe('BULK_OPERATION_FIELDS', () => {
+  it('lists the fields each operation requires besides its options', () => {
+    expect(BULK_OPERATION_FIELDS).toEqual({
+      insertOne: ['document'],
+      updateOne: ['filter', 'update'],
+      updateMany: ['filter', 'update'],
+      replaceOne: ['filter', 'replacement'],
+      deleteOne: ['filter'],
+      deleteMany: ['filter']
+    })
+  })
+})
+
+describe('BULK_OPERATION_OPTIONS', () => {
+  it('allows no options on a bulk insertOne', () => {
+    expect(BULK_OPERATION_OPTIONS.insertOne).toEqual({})
+  })
+
+  it('allows upsert and arrayFilters only where the operation updates', () => {
+    expect(Object.keys(BULK_OPERATION_OPTIONS.updateMany)).toEqual([
+      'upsert',
+      'arrayFilters',
+      'collation',
+      'hint'
+    ])
+    expect(Object.keys(BULK_OPERATION_OPTIONS.replaceOne)).toEqual(['upsert', 'collation', 'hint'])
+    expect(Object.keys(BULK_OPERATION_OPTIONS.deleteMany)).toEqual(['collation', 'hint'])
+  })
+})
+
+describe('filterError', () => {
+  it('accepts a filter document, empty or not', () => {
+    expect(filterError('deleteMany', {})).toBeNull()
+    expect(filterError('updateOne', { a: 1 })).toBeNull()
+  })
+
+  it.each([[[]], ['a'], [null], [1]])('rejects %j, naming the method', (filter) => {
+    expect(filterError('findOneAndDelete', filter)).toBe(
+      'findOneAndDelete() filter must be an object'
+    )
+  })
+})
+
+describe('updateError', () => {
+  it('accepts an update-operator document', () => {
+    expect(updateError({ $set: { a: 1 }, $inc: { n: 1 } })).toBeNull()
+  })
+
+  it('accepts an update pipeline of allowed stages', () => {
+    expect(updateError([{ $set: { a: 1 } }, { $unset: 'b' }, { $replaceWith: '$doc' }])).toBeNull()
+  })
+
+  it('rejects an empty update pipeline', () => {
+    expect(updateError([])).toBe('An update pipeline needs at least one stage')
+  })
+
+  it('rejects a pipeline stage MongoDB does not allow in updates, naming its position', () => {
+    expect(updateError([{ $set: { a: 1 } }, { $match: {} }])).toBe(
+      `Update pipeline stage 2 must be one of ${STAGE_LIST}`
+    )
+  })
+
+  it('rejects a pipeline stage with more than one operator', () => {
+    expect(updateError([{ $set: { a: 1 }, $unset: 'b' }])).toBe(
+      `Update pipeline stage 1 must be one of ${STAGE_LIST}`
+    )
+  })
+
+  it('rejects a pipeline entry that is not a stage object', () => {
+    expect(updateError(['$set'])).toBe(`Update pipeline stage 1 must be one of ${STAGE_LIST}`)
+    expect(updateError([{}])).toBe(`Update pipeline stage 1 must be one of ${STAGE_LIST}`)
+  })
+
+  it.each([null, 'x', 5, true])('rejects %j as neither operators nor a pipeline', (update) => {
+    expect(updateError(update)).toBe(
+      'The update must be an object of update operators or a pipeline array'
+    )
+  })
+
+  it('rejects an empty update document', () => {
+    expect(updateError({})).toBe('The update needs at least one operator such as $set')
+  })
+
+  it('points a plain document at replaceOne', () => {
+    expect(updateError({ name: 'x' })).toBe(
+      'The update needs operators such as $set; replaceOne replaces whole documents'
+    )
+  })
+
+  it('rejects operators mixed with plain fields', () => {
+    expect(updateError({ $set: { a: 1 }, name: 'x' })).toBe(
+      "The update can't mix operators with plain fields"
+    )
+  })
+})
+
+describe('replacementError', () => {
+  it('accepts a plain document, empty or not', () => {
+    expect(replacementError({ name: 'x', nested: { $literal: 1 } })).toBeNull()
+    expect(replacementError({})).toBeNull()
+  })
+
+  it.each([null, [], [{ a: 1 }], 'x', 1])('rejects %j as not a document', (replacement) => {
+    expect(replacementError(replacement)).toBe('The replacement must be a document')
+  })
+
+  it('points a top-level operator at updateOne', () => {
+    expect(replacementError({ name: 'x', $set: { a: 1 } })).toBe(
+      "A replacement can't contain update operators; updateOne applies operators"
+    )
+  })
+})
+
+describe('insertDocumentError', () => {
+  it('accepts a document', () => {
+    expect(insertDocumentError({ a: 1 })).toBeNull()
+  })
+
+  it.each([null, [], 'x', 1, undefined])('rejects %j', (document) => {
+    expect(insertDocumentError(document)).toBe('Each inserted document must be an object')
+  })
+})
+
+describe('writeOptionsError', () => {
+  it('accepts an empty options object', () => {
+    expect(writeOptionsError('updateOne', {})).toBeNull()
+  })
+
+  it('accepts every value kind in its valid form', () => {
+    expect(
+      writeOptionsError('findOneAndUpdate', {
+        upsert: true,
+        collation: { locale: 'en' },
+        arrayFilters: [{ 'e.k': 1 }],
+        hint: 'name_1',
+        returnDocument: 'after',
+        projection: { a: 1 },
+        sort: { a: -1 },
+        let: { v: 1 }
+      })
+    ).toBeNull()
+    expect(writeOptionsError('deleteOne', { hint: { name: 1 } })).toBeNull()
+    expect(writeOptionsError('findOneAndReplace', { returnNewDocument: false })).toBeNull()
+  })
+
+  it.each([null, [], 'x'])('rejects %j as an options value', (options) => {
+    expect(writeOptionsError('insertOne', options)).toBe('insertOne() options must be an object')
+  })
+
+  it('names the unknown key and the supported ones', () => {
+    expect(writeOptionsError('deleteMany', { upsert: true })).toBe(
+      'deleteMany() options: unknown option "upsert"; supported: collation, hint, let'
+    )
+  })
+
+  it('rejects a non-boolean flag', () => {
+    expect(writeOptionsError('insertMany', { ordered: 'false' })).toBe(
+      'insertMany() options: "ordered" must be true or false'
+    )
+  })
+
+  it('rejects a non-object document option', () => {
+    expect(writeOptionsError('replaceOne', { collation: 'en' })).toBe(
+      'replaceOne() options: "collation" must be an object'
+    )
+  })
+
+  it.each([{ 'e.k': 1 }, [{ a: 1 }, 'x']])('rejects arrayFilters %j', (arrayFilters) => {
+    expect(writeOptionsError('updateMany', { arrayFilters })).toBe(
+      'updateMany() options: "arrayFilters" must be an array of objects'
+    )
+  })
+
+  it.each([1, null, ['a']])('rejects hint %j', (hint) => {
+    expect(writeOptionsError('updateOne', { hint })).toBe(
+      'updateOne() options: "hint" must be an index name or key pattern'
+    )
+  })
+
+  it('rejects a returnDocument other than before or after', () => {
+    expect(writeOptionsError('findOneAndUpdate', { returnDocument: 'new' })).toBe(
+      'findOneAndUpdate() options: "returnDocument" must be "before" or "after"'
+    )
+  })
+
+  it('rejects returnDocument together with returnNewDocument', () => {
+    expect(
+      writeOptionsError('findOneAndReplace', { returnDocument: 'after', returnNewDocument: true })
+    ).toBe('findOneAndReplace() options: use returnDocument or returnNewDocument, not both')
+  })
+
+  it('keeps returnNewDocument away from findOneAndDelete', () => {
+    expect(writeOptionsError('findOneAndDelete', { returnNewDocument: true })).toBe(
+      'findOneAndDelete() options: unknown option "returnNewDocument"; supported: collation, hint, let, projection, sort'
+    )
+  })
+})
+
+describe('bulkWriteError', () => {
+  it('accepts every operation in its valid form', () => {
+    expect(
+      bulkWriteError([
+        { insertOne: { document: { a: 1 } } },
+        { updateOne: { filter: { a: 1 }, update: { $set: { b: 1 } }, upsert: true } },
+        { updateMany: { filter: {}, update: [{ $set: { c: 1 } }], arrayFilters: [{ x: 1 }] } },
+        { replaceOne: { filter: { a: 1 }, replacement: { a: 2 }, hint: 'a_1' } },
+        { deleteOne: { filter: { a: 2 }, collation: { locale: 'en' } } },
+        { deleteMany: { filter: {} } }
+      ])
+    ).toBeNull()
+  })
+
+  it.each([[], null, { insertOne: { document: {} } }])('rejects %j as the operations', (ops) => {
+    expect(bulkWriteError(ops)).toBe('bulkWrite() expects a non-empty array of operations')
+  })
+
+  it.each([
+    ['an unknown operation', { insertMany: { documents: [] } }],
+    ['two operations in one entry', { deleteOne: { filter: {} }, deleteMany: { filter: {} } }],
+    ['a non-object entry', 'insertOne'],
+    ['an empty entry', {}]
+  ])('rejects %s, naming its position', (_case, entry) => {
+    expect(bulkWriteError([{ deleteOne: { filter: {} } }, entry])).toBe(
+      'bulkWrite() operation 2 must be one of { insertOne | updateOne | updateMany | replaceOne | deleteOne | deleteMany: { … } }'
+    )
+  })
+
+  it('rejects an operation whose body is not an object', () => {
+    expect(bulkWriteError([{ deleteMany: [] }])).toBe(
+      'bulkWrite() operation 1: deleteMany needs an object'
+    )
+  })
+
+  it.each([
+    [{ insertOne: {} }, 'insertOne needs "document"'],
+    [{ updateOne: { filter: {} } }, 'updateOne needs "update"'],
+    [{ updateMany: { update: { $set: { a: 1 } } } }, 'updateMany needs "filter"'],
+    [{ replaceOne: { filter: {} } }, 'replaceOne needs "replacement"'],
+    [{ deleteOne: {} }, 'deleteOne needs "filter"']
+  ])('rejects %j: %s', (entry, reason) => {
+    expect(bulkWriteError([entry])).toBe(`bulkWrite() operation 1: ${reason}`)
+  })
+
+  it('rejects an inserted document that is not an object', () => {
+    expect(bulkWriteError([{ insertOne: { document: [1] } }])).toBe(
+      'bulkWrite() operation 1: Each inserted document must be an object'
+    )
+  })
+
+  it('rejects a filter that is not an object', () => {
+    expect(bulkWriteError([{ deleteOne: { filter: 'a' } }])).toBe(
+      'bulkWrite() operation 1: the filter must be an object'
+    )
+  })
+
+  it('applies the update rules to an update operation', () => {
+    expect(bulkWriteError([{ updateMany: { filter: {}, update: { a: 1 } } }])).toBe(
+      'bulkWrite() operation 1: The update needs operators such as $set; replaceOne replaces whole documents'
+    )
+  })
+
+  it('applies the replacement rules to a replace operation', () => {
+    expect(bulkWriteError([{ replaceOne: { filter: {}, replacement: { $set: { a: 1 } } } }])).toBe(
+      "bulkWrite() operation 1: A replacement can't contain update operators; updateOne applies operators"
+    )
+  })
+
+  it('rejects an option the operation does not take', () => {
+    expect(bulkWriteError([{ deleteOne: { filter: {}, upsert: true } }])).toBe(
+      'bulkWrite() operation 1 (deleteOne): unknown option "upsert"; supported: collation, hint'
+    )
+  })
+
+  it('says a bulk insertOne takes no options', () => {
+    expect(bulkWriteError([{ insertOne: { document: {}, ordered: true } }])).toBe(
+      'bulkWrite() operation 1 (insertOne): no options are supported'
+    )
+  })
+
+  it('checks the value kind of an operation option', () => {
+    expect(bulkWriteError([{ updateOne: { filter: {}, update: [{ $set: {} }], upsert: 1 } }])).toBe(
+      'bulkWrite() operation 1 (updateOne): "upsert" must be true or false'
+    )
+  })
+
+  it('reports the first invalid operation only', () => {
+    expect(bulkWriteError([{ deleteOne: {} }, { insertOne: {} }])).toBe(
+      'bulkWrite() operation 1: deleteOne needs "filter"'
+    )
+  })
+})
diff --git a/src/shared/writeOps.ts b/src/shared/writeOps.ts
new file mode 100644
index 0000000..19efc3c
--- /dev/null
+++ b/src/shared/writeOps.ts
@@ -0,0 +1,238 @@
+import type { WriteMethod } from './types'
+
+/**
+ * Argument rules of the write methods. The shell parser and main check writes with them, so both
+ * reject the same input with the same message; completion offers what they accept. Values are
+ * plain parsed JSON/EJSON trees.
+ */
+
+/** Stages an update pipeline may contain; MongoDB rejects every other stage there. */
+export const UPDATE_PIPELINE_STAGES: ReadonlySet<string> = new Set([
+  '$addFields',
+  '$set',
+  '$project',
+  '$unset',
+  '$replaceRoot',
+  '$replaceWith'
+])
+
+/** Operations `bulkWrite` accepts, named like the keys of its argument's elements. */
+export const BULK_WRITE_OPERATIONS = [
+  'insertOne',
+  'updateOne',
+  'updateMany',
+  'replaceOne',
+  'deleteOne',
+  'deleteMany'
+] as const
+
+export type BulkWriteOperation = (typeof BULK_WRITE_OPERATIONS)[number]
+
+/** A field a `bulkWrite` operation requires; the write methods name their arguments alike. */
+export type WriteField = 'document' | 'filter' | 'update' | 'replacement'
+
+/** A required argument of a write method. */
+export type WriteArgument = WriteField | 'documents' | 'operations'
+
+/** Fields each `bulkWrite` operation requires besides its options. */
+export const BULK_OPERATION_FIELDS: Readonly<Record<BulkWriteOperation, readonly WriteField[]>> = {
+  insertOne: ['document'],
+  updateOne: ['filter', 'update'],
+  updateMany: ['filter', 'update'],
+  replaceOne: ['filter', 'replacement'],
+  deleteOne: ['filter'],
+  deleteMany: ['filter']
+}
+
+/** Arguments each write method requires, in call order; each also takes a trailing options object. */
+export const WRITE_ARGUMENTS: Readonly<Record<WriteMethod, readonly WriteArgument[]>> = {
+  ...BULK_OPERATION_FIELDS,
+  insertMany: ['documents'],
+  findOneAndUpdate: ['filter', 'update'],
+  findOneAndReplace: ['filter', 'replacement'],
+  findOneAndDelete: ['filter'],
+  bulkWrite: ['operations']
+}
+
+/** The value an option takes: `documents` is an array of objects, `hint` an index name or key. */
+export type WriteOptionKind = 'boolean' | 'document' | 'documents' | 'hint' | 'returnDocument'
+
+type OptionSpec = Readonly<Record<string, WriteOptionKind>>
+
+const FILTERED: OptionSpec = { collation: 'document', hint: 'hint', let: 'document' }
+const UPDATE: OptionSpec = {
+  ...FILTERED,
+  upsert: 'boolean',
+  arrayFilters: 'documents',
+  bypassDocumentValidation: 'boolean'
+}
+const REPLACE: OptionSpec = { ...FILTERED, upsert: 'boolean', bypassDocumentValidation: 'boolean' }
+const RETURNING: OptionSpec = {
+  projection: 'document',
+  sort: 'document',
+  returnDocument: 'returnDocument',
+  returnNewDocument: 'boolean'
+}
+
+/** Options each write method accepts, and the kind of value each takes. */
+export const WRITE_OPTIONS: Readonly<Record<WriteMethod, OptionSpec>> = {
+  insertOne: { bypassDocumentValidation: 'boolean' },
+  insertMany: { ordered: 'boolean', bypassDocumentValidation: 'boolean' },
+  updateOne: UPDATE,
+  updateMany: UPDATE,
+  replaceOne: REPLACE,
+  deleteOne: FILTERED,
+  deleteMany: FILTERED,
+  findOneAndUpdate: { ...UPDATE, ...RETURNING },
+  findOneAndReplace: { ...REPLACE, ...RETURNING },
+  findOneAndDelete: { ...FILTERED, projection: 'document', sort: 'document' },
+  bulkWrite: { ordered: 'boolean', bypassDocumentValidation: 'boolean' }
+}
+
+const BULK_UPDATE: OptionSpec = {
+  upsert: 'boolean',
+  arrayFilters: 'documents',
+  collation: 'document',
+  hint: 'hint'
+}
+
+/** Option keys allowed inside one `bulkWrite` operation besides its required fields. */
+export const BULK_OPERATION_OPTIONS: Readonly<Record<BulkWriteOperation, OptionSpec>> = {
+  insertOne: {},
+  updateOne: BULK_UPDATE,
+  updateMany: BULK_UPDATE,
+  replaceOne: { upsert: 'boolean', collation: 'document', hint: 'hint' },
+  deleteOne: { collation: 'document', hint: 'hint' },
+  deleteMany: { collation: 'document', hint: 'hint' }
+}
+
+/** Option pairs that choose the same thing (the document findOneAnd* returns); one of each at most. */
+export const EXCLUSIVE_OPTIONS: readonly (readonly [string, string])[] = [
+  ['returnDocument', 'returnNewDocument']
+]
+
+/** Narrows to a non-null object that is not an array. */
+export const isDocument = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** Why `filter` cannot select the documents `method` writes, or null. */
+export function filterError(method: WriteMethod, filter: unknown): string | null {
+  return isDocument(filter) ? null : `${method}() filter must be an object`
+}
+
+/** Why `update` is neither an update-operator document nor an update pipeline, or null. */
+export function updateError(update: unknown): string | null {
+  if (Array.isArray(update)) {
+    if (update.length === 0) return 'An update pipeline needs at least one stage'
+    for (const [index, stage] of update.entries()) {
+      const keys = isDocument(stage) ? Object.keys(stage) : []
+      if (keys.length !== 1 || !UPDATE_PIPELINE_STAGES.has(keys[0]!)) {
+        return `Update pipeline stage ${index + 1} must be one of ${[...UPDATE_PIPELINE_STAGES].join(', ')}`
+      }
+    }
+    return null
+  }
+  if (!isDocument(update)) {
+    return 'The update must be an object of update operators or a pipeline array'
+  }
+  const keys = Object.keys(update)
+  if (keys.length === 0) return 'The update needs at least one operator such as $set'
+  const operators = keys.filter((key) => key.startsWith('$')).length
+  if (operators === 0) {
+    return 'The update needs operators such as $set; replaceOne replaces whole documents'
+  }
+  if (operators !== keys.length) return "The update can't mix operators with plain fields"
+  return null
+}
+
+/** Why `replacement` cannot replace a document, or null. */
+export function replacementError(replacement: unknown): string | null {
+  if (!isDocument(replacement)) return 'The replacement must be a document'
+  return Object.keys(replacement).some((key) => key.startsWith('$'))
+    ? "A replacement can't contain update operators; updateOne applies operators"
+    : null
+}
+
+/** Why `document` cannot be inserted, or null. */
+export function insertDocumentError(document: unknown): string | null {
+  return isDocument(document) ? null : 'Each inserted document must be an object'
+}
+
+/** Why `options` is not a valid options object for `method`, or null. */
+export function writeOptionsError(method: WriteMethod, options: unknown): string | null {
+  return optionsError(WRITE_OPTIONS[method], options, `${method}() options`)
+}
+
+/** Why `operations` is not a valid `bulkWrite` argument, or null. */
+export function bulkWriteError(operations: unknown): string | null {
+  if (!Array.isArray(operations) || operations.length === 0) {
+    return 'bulkWrite() expects a non-empty array of operations'
+  }
+  for (const [index, entry] of operations.entries()) {
+    const at = `bulkWrite() operation ${index + 1}`
+    const keys = isDocument(entry) ? Object.keys(entry) : []
+    const name = keys[0]
+    if (keys.length !== 1 || !isBulkWriteOperation(name)) {
+      return `${at} must be one of { ${BULK_WRITE_OPERATIONS.join(' | ')}: { … } }`
+    }
+    const body = (entry as Record<string, unknown>)[name]
+    if (!isDocument(body)) return `${at}: ${name} needs an object`
+    const fields: readonly string[] = BULK_OPERATION_FIELDS[name]
+    for (const field of fields) {
+      if (!(field in body)) return `${at}: ${name} needs "${field}"`
+    }
+    const fieldError = bulkFieldError(name, body)
+    if (fieldError !== null) return `${at}: ${fieldError}`
+    const rest = Object.fromEntries(Object.entries(body).filter(([key]) => !fields.includes(key)))
+    const restError = optionsError(BULK_OPERATION_OPTIONS[name], rest, `${at} (${name})`)
+    if (restError !== null) return restError
+  }
+  return null
+}
+
+function bulkFieldError(name: BulkWriteOperation, body: Record<string, unknown>): string | null {
+  if (name === 'insertOne') return insertDocumentError(body['document'])
+  if (!isDocument(body['filter'])) return 'the filter must be an object'
+  if (name === 'updateOne' || name === 'updateMany') return updateError(body['update'])
+  if (name === 'replaceOne') return replacementError(body['replacement'])
+  return null
+}
+
+function optionsError(spec: OptionSpec, options: unknown, what: string): string | null {
+  if (!isDocument(options)) return `${what} must be an object`
+  for (const [key, value] of Object.entries(options)) {
+    const kind = spec[key]
+    if (kind === undefined) {
+      const known = Object.keys(spec)
+      return known.length === 0
+        ? `${what}: no options are supported`
+        : `${what}: unknown option "${key}"; supported: ${known.join(', ')}`
+    }
+    const error = valueError(kind, value)
+    if (error !== null) return `${what}: "${key}" ${error}`
+  }
+  for (const [a, b] of EXCLUSIVE_OPTIONS) {
+    if (a in options && b in options) return `${what}: use ${a} or ${b}, not both`
+  }
+  return null
+}
+
+function valueError(kind: WriteOptionKind, value: unknown): string | null {
+  switch (kind) {
+    case 'boolean':
+      return typeof value === 'boolean' ? null : 'must be true or false'
+    case 'document':
+      return isDocument(value) ? null : 'must be an object'
+    case 'documents':
+      return Array.isArray(value) && value.every(isDocument) ? null : 'must be an array of objects'
+    case 'hint':
+      return typeof value === 'string' || isDocument(value)
+        ? null
+        : 'must be an index name or key pattern'
+    case 'returnDocument':
+      return value === 'before' || value === 'after' ? null : 'must be "before" or "after"'
+  }
+}
+
+const isBulkWriteOperation = (name: string | undefined): name is BulkWriteOperation =>
+  (BULK_WRITE_OPERATIONS as readonly (string | undefined)[]).includes(name)