diff --git a/api-reference/commands/diagnostic/hello.md b/api-reference/commands/diagnostic/hello.md
index 1d92590..c261eb1 100644
--- a/api-reference/commands/diagnostic/hello.md
+++ b/api-reference/commands/diagnostic/hello.md
@@ -105,4 +105,4 @@ The first value is the installed SQL extension version — the schema version, f
 
 ## Related content
 
-- [DocumentDB Local](https://documentdb.io/docs/documentdb-local)
+- [DocumentDB Local](https://documentdb.io/docs/documentdb-local/)
diff --git a/api-reference/commands/query-and-write/delete.md b/api-reference/commands/query-and-write/delete.md
index 6e258f8..936d13f 100644
--- a/api-reference/commands/query-and-write/delete.md
+++ b/api-reference/commands/query-and-write/delete.md
@@ -146,31 +146,52 @@ Consider this sample document from the stores collection in the StoreData databa
 }
 ```
 
-### Example 1 - Delete all documents in a collection
+The sample store above runs two promotion events, and three of its discounts are at 19%, so the filter `"promotionEvents.discounts.discountPercentage": 19` matches it. Each example below is independent and assumes the collection is fully populated; they are ordered so that the destructive one comes last.
+
+### Example 1 - Delete a document that matches a specified query filter
 
 ```javascript
-db.stores.deleteMany({})
+db.stores.deleteOne({"_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4"})
 ```
 
-### Example 2 - Delete a document that matches a specified query filter
+### Example 2 - Delete all documents that match a specified query filter
 
 ```javascript
-db.stores.deleteOne({"_id": "68471088-4d45-4164-ae58-a9428d12f310"})
+db.stores.deleteMany({"promotionEvents.discounts.discountPercentage": 19})
 ```
 
-### Example 3 - Delete all documents that match a specified query filter
+### Example 3 - Delete only one of many documents that match a specified query filter
+
+Use `deleteOne` rather than `deleteMany`. There is no shell option that limits `deleteMany` to a single document — `limit` is a field of the wire-protocol `deletes` array element (see below), not a `deleteMany` option, and passing it here has no effect.
 
 ```javascript
-db.stores.deleteMany({"promotionEvents.discounts.discountPercentage": 21}, {"limit": 0})
+db.stores.deleteOne({"promotionEvents.discounts.discountPercentage": 19})
 ```
 
-### Example 3 - Delete only one of many documents that match a specified query filter
+### Example 4 - Delete all documents in a collection
+
+An empty filter matches everything, so this empties the collection:
 
 ```javascript
-db.stores.deleteMany({"promotionEvents.discounts.discountPercentage": 21}, {"limit": 1})
+db.stores.deleteMany({})
 ```
 
+## Wire protocol form
+
+The shell helpers above are wrappers over the `delete` command. Each element of the `deletes` array carries its own `limit`, which must be `0` (delete every match) or `1` (delete at most one match); any other value is rejected with `The limit field in delete objects must be 0 or 1`.
+
+```javascript
+db.runCommand({
+   delete: "stores",
+   deletes: [
+      { q: {"promotionEvents.discounts.discountPercentage": 19}, limit: 1 }
+   ]
+})
+```
+
+`deleteOne` sends `limit: 1`; `deleteMany` sends `limit: 0`.
+
 ## Related content
 
-- [insert with DocumentDB](insert)
-- [update with DocumentDB](update)
+- [insert with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/insert/)
+- [update with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/update/)
diff --git a/api-reference/commands/query-and-write/find.md b/api-reference/commands/query-and-write/find.md
index c8f3d3f..f8de849 100644
--- a/api-reference/commands/query-and-write/find.md
+++ b/api-reference/commands/query-and-write/find.md
@@ -345,5 +345,5 @@ One of the documents returned shows the specified array elements projected in th
 
 ## Related content
 
-- [insert with DocumentDB](insert)
-- [update with DocumentDB](update)
+- [insert with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/insert/)
+- [update with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/update/)
diff --git a/api-reference/commands/query-and-write/getMore.md b/api-reference/commands/query-and-write/getMore.md
index a7e3008..3a0254d 100644
--- a/api-reference/commands/query-and-write/getMore.md
+++ b/api-reference/commands/query-and-write/getMore.md
@@ -7,45 +7,49 @@ category: query-and-write
 
 # getMore
 
-The `getMore` command is used to retrieve extra batches of documents from an existing cursor. This command is useful when dealing with large datasets that can't be fetched in a single query due to size limitations. The command allows clients to paginate through the results in manageable chunks with commands that return a cursor. For example, [find](./find) and [aggregate](../aggregation/aggregate), to return subsequent batches of documents currently pointed to by the cursor.
+The `getMore` command is used to retrieve extra batches of documents from an existing cursor. This command is useful when dealing with large datasets that can't be fetched in a single query due to size limitations. The command allows clients to paginate through the results in manageable chunks with commands that return a cursor. For example, [find](https://documentdb.io/docs/reference/commands/query-and-write/find/) and [aggregate](https://documentdb.io/docs/reference/commands/aggregation/aggregate/), to return subsequent batches of documents currently pointed to by the cursor.
 
 ## Syntax
 
 The syntax for the `getMore` command is as follows:
 
 ```javascript
-{
-   getMore: <cursor-id>,
+db.runCommand({
+   getMore: NumberLong("<cursor-id>"),
    collection: <collection-name>,
-   batchSize: <number-of-documents>
-}
+   batchSize: <number-of-documents>,
+   maxTimeMS: <milliseconds>
+})
 ```
 
-- `getMore`: The unique identifier for the cursor from which to retrieve more documents.
+- `getMore`: The unique identifier for the cursor from which to retrieve more documents, taken from the `cursor.id` field of the originating `find` or `aggregate` response. This field must be a BSON 64-bit integer — in `mongosh` write it as `NumberLong("...")`, and in Extended JSON as `{"$numberLong": "..."}`. A plain JavaScript number is serialized as a 32-bit integer and is rejected with `BadValue: getMore value should be an i64`.
 - `collection`: The name of the collection associated with the cursor.
-- `batchSize`: (Optional) The number of documents to return in the batch. If not specified, the server uses the default batch size.
+- `batchSize`: (Optional) The maximum number of documents to return in the batch. Unlike the first page of `find` or `aggregate`, which defaults to 101 documents, `getMore` has no small default — if `batchSize` is omitted the server returns everything remaining in the cursor, stopping only when the accumulated batch reaches 16 MB.
+- `maxTimeMS`: (Optional) A statement timeout for this batch. On a tailable cursor such as a change stream it instead bounds how long the server waits for new data.
 
 ## Examples
 
 ### Example 1: Retrieve more documents from a cursor
 
-Assume you have a cursor with the ID `1234567890` from the `stores` collection. The following command retrieves the next batch of documents:
+Assume you have a cursor with the ID `1234567890` from the `stores` collection. The following command retrieves up to five more documents:
 
 ```javascript
-{
-   getMore: 1234567890,
+db.runCommand({
+   getMore: NumberLong("1234567890"),
    collection: "stores",
    batchSize: 5
-}
+})
 ```
 
-### Example 2: Retrieve more documents without specifying batch size
+### Example 2: Drain the rest of the cursor
 
-If you don't specify the `batchSize`, the server uses the default batch size:
+Omitting `batchSize` returns every document still held by the cursor in a single batch, up to the 16 MB limit:
 
 ```javascript
-{
-   getMore: 1234567890,
+db.runCommand({
+   getMore: NumberLong("1234567890"),
    collection: "stores"
-}
+})
 ```
+
+A batch can come back smaller than requested, and an omitted `batchSize` does not guarantee the cursor was drained — the 16 MB batch limit can cut it short. Always keep calling `getMore` until the response reports a `cursor.id` of `0`, rather than stopping when a batch is shorter than `batchSize`.
diff --git a/api-reference/commands/query-and-write/insert.md b/api-reference/commands/query-and-write/insert.md
index 02d409b..45befbe 100644
--- a/api-reference/commands/query-and-write/insert.md
+++ b/api-reference/commands/query-and-write/insert.md
@@ -29,11 +29,11 @@ db.collection.insert(
 | --- | --- |
 | **`<single document or array of documents>`** | The document or array of documents to insert into the collection|
 | **`writeConcern`** | (Optional) A document expressing the write concern. The write concern describes the level of acknowledgment requested from the server for the write operation|
-| **`ordered`** | (Optional) If `true`, the server inserts the documents in the order provided. If `false`, the server can insert the documents in any order and will attempt to insert all documents regardless of errors|
+| **`ordered`** | (Optional) Defaults to `true`. If `true`, the server inserts the documents in the order provided and stops at the first failure. If `false`, the server can insert the documents in any order and will attempt to insert all documents regardless of errors|
 
 - `<single document or array of documents>`: The document or array of documents to insert into the collection.
 - `writeConcern`: Optional. A document expressing the write concern. The write concern describes the level of acknowledgment requested from the server for the write operation.
-- `ordered`: Optional. If `true`, the server inserts the documents in the order provided. If `false`, the server can insert the documents in any order and will attempt to insert all documents regardless of errors.
+- `ordered`: Optional. Defaults to `true`. If `true`, the server inserts the documents in the order provided and stops at the first failure. If `false`, the server can insert the documents in any order and will attempt to insert all documents regardless of errors.
 
 ## Example(s)
 
@@ -237,7 +237,7 @@ If a duplicate value for the _id field is specified, a duplicate key violation e
 
 ### Inserting multiple documents in order
 
-Documents that are inserted in bulk can be inserted in order when specifying "ordered": true
+Documents inserted in bulk are inserted in the order provided, and the batch stops at the first failure. This is the default, so `ordered: true` below is explicit rather than required. Pass `ordered: false` instead when you want the server to attempt every document regardless of errors.
 
 ```javascript
 db.stores.insertMany([
@@ -335,10 +335,10 @@ db.stores.insertMany([
       }
     ]
   }
-], "ordered": true)
+], { ordered: true })
 ```
 
-The ordered insert command returns a response confirming the order in which documents were inserted:
+A successful insert returns the ids of the inserted documents, keyed by their position in the input array. Note that `insertedIds` reports input positions, not execution order, so its shape is the same under `ordered: false` — it is not a way to confirm the order in which documents were applied:
 
 ```json
 {
@@ -352,5 +352,5 @@ The ordered insert command returns a response confirming the order in which docu
 
 ## Related content
 
-- [update with DocumentDB](update)
-- [find with DocumentDB](find)
+- [update with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/update/)
+- [find with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/find/)
diff --git a/api-reference/commands/query-and-write/update.md b/api-reference/commands/query-and-write/update.md
index 6ca0e77..7552267 100644
--- a/api-reference/commands/query-and-write/update.md
+++ b/api-reference/commands/query-and-write/update.md
@@ -197,5 +197,5 @@ db.stores.updateOne({"_id": "NonExistentDocId"}, {"$set": {"name": "Lakeshore Re
 
 ## Related content
 
-- [insert with DocumentDB](insert)
-- [delete with DocumentDB](delete)
+- [insert with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/insert/)
+- [delete with DocumentDB](https://documentdb.io/docs/reference/commands/query-and-write/delete/)
diff --git a/api-reference/operators/aggregation/$bucketauto.md b/api-reference/operators/aggregation/$bucketauto.md
index 3558068..cdc8f59 100644
--- a/api-reference/operators/aggregation/$bucketauto.md
+++ b/api-reference/operators/aggregation/$bucketauto.md
@@ -7,7 +7,7 @@ category: aggregation
 
 # $bucketAuto
 
-The `$bucketAuto` stage categorizes documents into a specified number of buckets, attempting to evenly distribute the documents based on the values of a `groupBy` expression. Unlike [`$bucket`](./%24bucket.md), you do not have to provide boundaries — DocumentDB computes them for you.
+The `$bucketAuto` stage categorizes documents into a specified number of buckets, attempting to evenly distribute the documents based on the values of a `groupBy` expression. Unlike [`$bucket`](https://documentdb.io/docs/reference/operators/aggregation/%24bucket/), you do not have to provide boundaries — DocumentDB computes them for you.
 
 Supported since `v0.105-0`.
 
@@ -39,8 +39,11 @@ Supported since `v0.105-0`.
 ## Behavior
 
 - `$bucketAuto` outputs documents with an `_id` of the form `{ "min": <lower>, "max": <upper> }`, representing the bucket's lower and upper boundary. The upper boundary is exclusive for all buckets except the last, which includes its upper boundary.
-- When the number of distinct `groupBy` values is less than `buckets`, the stage produces fewer buckets than requested.
-- When `granularity` is specified, the computed boundaries are rounded outward to the nearest preferred number.
+- Without `granularity`, a non-last bucket's `max` is the first `groupBy` value of the *next* bucket, so adjacent buckets share a boundary. The last bucket's `max` is its own largest value.
+- Documents are distributed as evenly as the input allows: with `n` documents and `b` buckets each bucket takes `floor(n / b)` documents, and a pool of `n mod b` spare documents is handed out one at a time to the buckets that need them, earliest first. A bucket is then extended to absorb any following documents that tie with its largest value, so that equal values never straddle a boundary. Each absorbed document consumes one of the spares, so when `n` is not divisible by `b` the extras do not always land in the earliest buckets.
+- The stage can produce fewer buckets than requested — when the number of distinct `groupBy` values is less than `buckets`, and also whenever `granularity` rounding absorbs documents (see below).
+- When `granularity` is specified, the first bucket's `min` is rounded down to the nearest series value strictly below it, and every bucket's `max` is rounded up to the nearest series value strictly above it; each later bucket's `min` is simply the previous bucket's `max`. Because a rounded-up `max` can exceed values that were assigned to later buckets, those documents are pulled into the current bucket, which is why the result often has fewer buckets than requested. Boundaries produced this way are doubles.
+- With `granularity`, every `groupBy` value must be numeric and non-negative; a non-numeric value fails with `$bucketAuto only allows specifying a 'granularity' with numeric boundaries`.
 
 ## Examples
 
@@ -82,15 +85,17 @@ Sample output:
 
 ```json
 [
-  { "_id": { "min": 3,  "max": 18  }, "count": 3, "avgPrice": 9.67 },
-  { "_id": { "min": 18, "max": 45  }, "count": 3, "avgPrice": 28.33 },
-  { "_id": { "min": 45, "max": 230 }, "count": 2, "avgPrice": 145 }
+  { "_id": { "min": 3,  "max": 18  }, "count": 3, "avgPrice": 7.666666666666667 },
+  { "_id": { "min": 18, "max": 60  }, "count": 3, "avgPrice": 32.666666666666664 },
+  { "_id": { "min": 60, "max": 230 }, "count": 2, "avgPrice": 145 }
 ]
 ```
 
+Eight documents into three buckets gives sizes 3, 3, 2. The buckets hold prices `3, 8, 12`, then `18, 35, 45`, then `60, 230`. Each non-last bucket reports the next bucket's first price as its `max`, so the first bucket ends at `18` and the second at `60`.
+
 ### Example 2: Buckets with rounded boundaries via `granularity`
 
-Group prices into four buckets rounded to a power-of-two series:
+Request four buckets rounded to a power-of-two series:
 
 ```javascript
 db.sales.aggregate([
@@ -108,14 +113,15 @@ Sample output:
 
 ```json
 [
-  { "_id": { "min": 2,   "max": 16  }, "count": 3 },
-  { "_id": { "min": 16,  "max": 32  }, "count": 1 },
-  { "_id": { "min": 32,  "max": 64  }, "count": 2 },
-  { "_id": { "min": 64,  "max": 256 }, "count": 2 }
+  { "_id": { "min": 2,  "max": 16  }, "count": 3 },
+  { "_id": { "min": 16, "max": 64  }, "count": 4 },
+  { "_id": { "min": 64, "max": 256 }, "count": 1 }
 ]
 ```
 
+Four buckets were requested but three are returned. The even split would have put `3, 8` in the first bucket, but rounding its `max` up from `8` to `16` pulls in `12` as well. The second bucket starts at `18`, and rounding its `max` up from `35` to `64` absorbs `45` and `60`, leaving only `230` for the third bucket.
+
 ## See Also
 
-- [`$bucket`](./%24bucket.md) — fixed-boundary bucketing.
-- [`$group`](./%24group.md) — generic grouping by an expression.
+- [`$bucket`](https://documentdb.io/docs/reference/operators/aggregation/%24bucket/) — fixed-boundary bucketing.
+- [`$group`](https://documentdb.io/docs/reference/operators/aggregation/%24group/) — generic grouping by an expression.
diff --git a/api-reference/operators/arithmetic-expression/index.md b/api-reference/operators/arithmetic-expression/index.md
deleted file mode 100644
index c44c4a7..0000000
--- a/api-reference/operators/arithmetic-expression/index.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# Arithmetic Expressions
-
-This section contains documentation for arithmetic expression operators.
-
-## Overview
-
-Arithmetic expression operators perform mathematical operations on numeric values.
-
-## Available Operators
-
-*More content to be added as operators are documented.*
-
-## Related Topics
-
-- [Comparison Operators](../comparison/)
-- [Bitwise Operators](../bitwise/)
diff --git a/getting-started/index.md b/getting-started/index.md
index 3aaf8ea..f025dbf 100644
--- a/getting-started/index.md
+++ b/getting-started/index.md
@@ -45,7 +45,7 @@ DocumentDB consists of three primary components:
 
 3. **pg_documentdb_gw**: The gateway that:
    - Implements the MongoDB wire protocol
-   - Terminates TLS and authenticates clients (SCRAM-SHA-256 and Plain)
+   - Terminates TLS and authenticates clients (SCRAM-SHA-256)
    - Translates MongoDB commands into calls against `pg_documentdb`
    - Manages cursors, sessions, and connection state for MongoDB drivers
 
@@ -62,15 +62,15 @@ DocumentDB consists of three primary components:
 Choose the getting started guide that best fits your needs:
 
 ### Quick Start Guides
-- [VS Code Extension Quick Start](https://documentdb.io/docs/getting-started/vscode-quickstart) - Recommended for developers new to DocumentDB
-- [VS Code Extension Guide](https://documentdb.io/docs/getting-started/vscode-extension-guide) - Comprehensive guide to the VS Code extension
+- [VS Code Extension Quick Start](https://documentdb.io/docs/getting-started/vscode-quickstart/) - Recommended for developers new to DocumentDB
+- [VS Code Extension Guide](https://documentdb.io/docs/getting-started/vscode-extension-guide/) - Comprehensive guide to the VS Code extension
 
 ### Language-Specific Guides
-- [Python Setup Guide](https://documentdb.io/docs/getting-started/python-setup) - Using DocumentDB with Python applications
-- [Node.js Setup Guide](https://documentdb.io/docs/getting-started/nodejs-setup) - Using DocumentDB with Node.js applications
+- [Python Setup Guide](https://documentdb.io/docs/getting-started/python-setup/) - Using DocumentDB with Python applications
+- [Node.js Setup Guide](https://documentdb.io/docs/getting-started/nodejs-setup/) - Using DocumentDB with Node.js applications
 
 ### Deployment Options
-- [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages) - Download and install ready-to-use packages
+- [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages/) - Download and install ready-to-use packages
 
 ## Community and Support
 
@@ -86,5 +86,5 @@ Choose the getting started guide that best fits your needs:
 ## Next Steps
 
 After choosing your preferred getting started path:
-- Explore our [API Reference](https://documentdb.io/docs/reference) for detailed documentation
+- Explore our [API Reference](https://documentdb.io/docs/reference/) for detailed documentation
 - Join our community to contribute and get support 
diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md
index 69dd1c9..ccde27a 100644
--- a/getting-started/mongo-shell-quickstart.md
+++ b/getting-started/mongo-shell-quickstart.md
@@ -46,7 +46,7 @@ DocumentDB Local terminates TLS on the gateway port. The container generates a n
 mongosh "mongodb://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"
 ```
 
-For instructions on installing the generated certificate so you can validate it normally, see [DocumentDB Local](https://documentdb.io/docs/documentdb-local).
+For instructions on installing the generated certificate so you can validate it normally, see [DocumentDB Local](https://documentdb.io/docs/documentdb-local/).
 
 ## Basic Operations
 
@@ -130,7 +130,7 @@ DocumentDB supports many MongoDB-compatible index types, including single-field,
 
 ```javascript
 // Single field index
-db.users.createIndex({ email: 1 })
+db.users.createIndex({ name: 1 })
 
 // Compound index
 db.users.createIndex({ name: 1, email: 1 })
@@ -151,6 +151,10 @@ db.orders.createIndex(
 )
 ```
 
+Each index above is on a distinct set of keys, which matters: when you don't pass a `name`, the index name is generated from the keys, so `{ email: 1 }` becomes `email_1` whatever options you give it. Creating both a plain and a unique index on `{ email: 1 }` therefore collides on that one generated name and fails with `An existing index has the same name as the requested index`. Pass an explicit `name` to at least one of them if you need both.
+
+Note also that a unique index is not sparse unless you say so. Documents that lack the indexed field are all treated as sharing a single "missing" value, so the second such document violates uniqueness. Add `sparse: true` when the field is optional.
+
 To create a vector index on an embedding field, use the `cosmosSearchOptions` index spec accepted by the DocumentDB gateway:
 
 ```javascript
@@ -162,12 +166,14 @@ db.products.createIndex(
       kind: "vector-ivf",
       numLists: 100,
       similarity: "COS",
-      dimensions: 384
+      dimensions: 3
     }
   }
 )
 ```
 
+`dimensions` must match the length of the vectors you store and query — a query vector of a different length is rejected. Three is used here only to keep the example short; a real embedding field is typically 384, 768, or 1536 wide, depending on the model.
+
 ## Aggregation Pipelines
 
 ```javascript
@@ -182,10 +188,12 @@ db.orders.aggregate([
 ])
 ```
 
-DocumentDB also supports stages such as `$lookup`, `$unwind`, `$facet`, `$bucket`, `$bucketAuto`, and many others. See the [API Reference](https://documentdb.io/docs/api-reference) for the full list.
+DocumentDB also supports stages such as `$lookup`, `$unwind`, `$facet`, `$bucket`, `$bucketAuto`, and many others. See the [API Reference](https://documentdb.io/docs/reference/) for the full list.
 
 ## Vector Search
 
+This queries the `vectorIndex` created above, so the query vector has the same three dimensions the index declares:
+
 ```javascript
 db.products.aggregate([
   {
@@ -240,18 +248,30 @@ db.users.validate()
 db.runCommand({ compact: "users" })
 ```
 
-User and role management commands are also supported:
+User and role management commands are also supported, with two caveats specific to roles: they must be run from the `admin` database, and they are gated behind a server setting that is off by default. Enable it once, as a Postgres superuser, before running the role examples:
+
+```sql
+ALTER SYSTEM SET documentdb.enableRoleCrud = on;
+SELECT pg_reload_conf();
+```
+
+This is a PostgreSQL GUC, so it cannot be set from `mongosh` — use `psql` or your provider's parameter settings. `updateRole` is not implemented regardless of this setting.
 
 ```javascript
-// Users
-db.runCommand({ createUser: "alice", pwd: "secret", roles: [ { role: "readWrite", db: "mydb" } ] })
+// Users — can be created from any database
+db.runCommand({ createUser: "alice", pwd: "secret", roles: [ { role: "readAnyDatabase", db: "admin" } ] })
 db.runCommand({ usersInfo: 1 })
 
-// Roles
-db.runCommand({ createRole: "appWriter", privileges: [], roles: [ "readWrite" ] })
+// Roles — must be run against admin
+use admin
+db.runCommand({ createRole: "appReader", privileges: [], roles: [ "readAnyDatabase" ] })
 db.runCommand({ rolesInfo: 1 })
 ```
 
+DocumentDB does not implement per-database roles. `createUser` takes role **documents** and accepts exactly two sets, both scoped to `admin` — `[{ role: "readAnyDatabase", db: "admin" }]` for read-only access, or `[{ role: "clusterAdmin", db: "admin" }, { role: "readWriteAnyDatabase", db: "admin" }]` for read-write access. Anything else, including `readWrite` or a `db` other than `admin`, is rejected.
+
+`createRole` draws on the same three built-in roles but takes their **names as bare strings**, not documents — `roles: [ "readAnyDatabase" ]`. Passing a document there fails with `Invalid inherited from role name provided.` As with `createUser`, `readWriteAnyDatabase` and `clusterAdmin` must be named together. `createRole` also requires a `privileges` field, even when empty.
+
 ## Best Practices
 
 - **Connection pooling:** reuse a single `mongosh` connection per session.
@@ -261,6 +281,6 @@ db.runCommand({ rolesInfo: 1 })
 
 ## Next Steps
 
-- Browse the [API Reference](https://documentdb.io/docs/api-reference) for the full list of supported commands, operators, and aggregation stages.
-- Connect from your application using the [Python](https://documentdb.io/docs/getting-started/python-setup) or [Node.js](https://documentdb.io/docs/getting-started/nodejs-setup) setup guides.
-- Use the [Visual Studio Code extension](https://documentdb.io/docs/getting-started/vscode-extension-guide) for a GUI experience over the same gateway.
+- Browse the [API Reference](https://documentdb.io/docs/reference/) for the full list of supported commands, operators, and aggregation stages.
+- Connect from your application using the [Python](https://documentdb.io/docs/getting-started/python-setup/) or [Node.js](https://documentdb.io/docs/getting-started/nodejs-setup/) setup guides.
+- Use the [Visual Studio Code extension](https://documentdb.io/docs/getting-started/vscode-extension-guide/) for a GUI experience over the same gateway.
diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md
index 7ddefcf..0b4d96f 100644
--- a/getting-started/python-setup.md
+++ b/getting-started/python-setup.md
@@ -11,7 +11,7 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py
 
 - Python 3.7+
 - pip package manager
-- DocumentDB installed and running (see [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages))
+- DocumentDB installed and running (see [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages/))
 - Docker (if DocumentDB is not set up yet)
 - Git installed (for cloning the repository)
 
@@ -282,5 +282,5 @@ if __name__ == '__main__':
 
 ## Next Steps
 
-- Explore advanced features in the [API Reference](https://documentdb.io/docs/reference)
-- Check out the [MongoDB Shell Guide](mongo-shell-quickstart.md) for additional query examples 
+- Explore advanced features in the [API Reference](https://documentdb.io/docs/reference/)
+- Check out the [MongoDB Shell Guide](https://documentdb.io/docs/getting-started/mongo-shell-quickstart/) for additional query examples
diff --git a/getting-started/vscode-extension-guide.md b/getting-started/vscode-extension-guide.md
index 6af5dfe..e6eaa71 100644
--- a/getting-started/vscode-extension-guide.md
+++ b/getting-started/vscode-extension-guide.md
@@ -238,7 +238,7 @@ db.collection.getIndexes()
 #### Creating Indexes
 ```javascript
 // Create a single field index
-db.collection.createIndex({ "email": 1 })
+db.collection.createIndex({ "createdAt": 1 })
 
 // Create a compound index
 db.collection.createIndex({ "lastName": 1, "firstName": 1 })
@@ -355,6 +355,6 @@ The VS Code extension is particularly useful for migrating from MongoDB to Docum
 
 ## Next Steps
 
-- Learn about [DocumentDB Features](https://documentdb.io/docs/reference) for advanced capabilities
+- Learn about [DocumentDB Features](https://documentdb.io/docs/reference/) for advanced capabilities
 - Join our [Discord community](https://discord.gg/vH7bYu524D) for support and discussions
 - Report issues and contribute on [GitHub](https://github.com/documentdb/documentdb)
diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md
index c098ad3..2da1b2b 100644
--- a/getting-started/vscode-quickstart.md
+++ b/getting-started/vscode-quickstart.md
@@ -108,5 +108,5 @@ Get started with DocumentDB using the Visual Studio Code extension for a seamles
 
 ## Next Steps
 
-- Explore advanced querying capabilities in the [API Reference](https://documentdb.io/docs/reference)
-- Connect your application using the [Python Setup for DocumentDB](https://documentdb.io/docs/getting-started/python-setup) 
+- Explore advanced querying capabilities in the [API Reference](https://documentdb.io/docs/reference/)
+- Connect your application using the [Python Setup for DocumentDB](https://documentdb.io/docs/getting-started/python-setup/) 
diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md
index 94c0a1b..a5a2106 100644
--- a/postgres-api/configuration.md
+++ b/postgres-api/configuration.md
@@ -37,6 +37,15 @@ These flags gate functionality that is otherwise silently unavailable — in eac
 | `documentdb.enablePreImages` | `off` | Allows the `changeStreamPreAndPostImages` collection option. While `off`, `create` and `collMod` reject that option. |
 | `documentdb.indexBuildsScheduledOnBgWorker` | `off` | Drains the background index build queue from a PostgreSQL background worker instead of a pg_cron job. Leave `off` where pg_cron is configured and working; turn it on where pg_cron cannot run the job, otherwise queued index builds never start. |
 
+### Role management flags
+
+Unlike the flags above, these two produce an error rather than a missing effect, so a caller sees the failure immediately.
+
+| GUC | Default | Description |
+| --- | --- | --- |
+| `documentdb.enableRoleCrud` | `off` (since v0.108-0) | Enables role CRUD through the data plane. While `off`, `create_role`, `drop_role`, and `roles_info` each raise before doing any work, for example "The CreateRole command is currently unsupported." Note that `update_role` is not implemented in any case. |
+| `documentdb.enableRolesAdminDBCheck` | `on` (since v0.109-0) | Requires the wire-protocol role commands to be issued against the `admin` database, raising "CreateRole must be called from 'admin' database." otherwise. The user management commands are governed separately by `documentdb.enableUsersAdminDBCheck`, which is `off` by default. |
+
 ## Gateway configuration
 
 The gateway (`pg_documentdb_gw`) reads its settings from a JSON configuration file and/or `DOCUMENTDB_*` environment variables. Environment variables override the JSON file, which makes them convenient for systemd-managed and container deployments. *(Environment-variable configuration added in v0.114-0.)*
diff --git a/postgres-api/functions.md b/postgres-api/functions.md
index cdb1514..83caddc 100644
--- a/postgres-api/functions.md
+++ b/postgres-api/functions.md
@@ -160,11 +160,13 @@ Functions for creating, updating, and managing database users. Backed by the wir
 
 All four role functions were added in v0.106-0, together with wire-protocol support for `createRole`. Support for the `dropRole` and `rolesInfo` commands followed in v0.108-0. `updateRole` is routed by the gateway to `documentdb_api.update_role`.
 
+All of them are gated behind `documentdb.enableRoleCrud`, added in v0.108-0 and off by default, so on a stock build `create_role`, `drop_role`, and `roles_info` raise "The CreateRole command is currently unsupported." and its equivalents before doing any work. The wire-protocol commands are additionally required to run against the `admin` database (`documentdb.enableRolesAdminDBCheck`, on by default since v0.109-0); the user management functions above are not.
+
 | Function | Description |
 | --- | --- |
 | `documentdb_api.create_role(p_spec bson)` | Creates a new role. |
 | `documentdb_api.drop_role(p_spec bson)` | Drops an existing role. |
-| `documentdb_api.update_role(p_spec bson)` | Updates an existing role's privileges or inherited roles. |
+| `documentdb_api.update_role(p_spec bson)` | Not implemented. The function body is a bare `ereport(ERROR)`, so every call raises "UpdateRole command is not supported in preview." regardless of the spec or of `enableRoleCrud`. |
 | `documentdb_api.roles_info(p_spec bson)` | Returns information about one or more roles. |
 
 ## Utility Functions
@@ -187,4 +189,4 @@ SELECT * FROM documentdb_api.insert(
 
 Because `insert` declares two `OUT` parameters, `SELECT *` returns them as the named columns `p_result` and `p_success`. Dropping the `*` would collapse them into a single composite value.
 
-For more complete examples (cursors, aggregation, sharding) see the [API Reference](https://documentdb.io/docs/api-reference).
+For more complete examples (cursors, aggregation, sharding) see the [API Reference](https://documentdb.io/docs/reference/).
diff --git a/postgres-api/index.md b/postgres-api/index.md
index 1178355..4b526e1 100644
--- a/postgres-api/index.md
+++ b/postgres-api/index.md
@@ -37,7 +37,7 @@ The DocumentDB implementation consists of three PostgreSQL extensions that work
 
 ### Usage
 
-To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and configured in your PostgreSQL environment. Once set up, you can leverage the APIs provided by `pg_documentdb` to perform document operations from any PostgreSQL client. For the full list of callable functions, see [Functions](functions.md).
+To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and configured in your PostgreSQL environment. Once set up, you can leverage the APIs provided by `pg_documentdb` to perform document operations from any PostgreSQL client. For the full list of callable functions, see [Functions](https://documentdb.io/docs/postgres-api/functions/).
 
 ## pg_documentdb_gw
 
@@ -47,7 +47,7 @@ To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and conf
 
 - **MongoDB Wire Protocol:** Parses MongoDB wire protocol messages (`OP_MSG`, `OP_QUERY`, `OP_INSERT`, etc.) and dispatches them to the corresponding `pg_documentdb` SQL functions.
 
-- **Authentication:** Supports SCRAM-SHA-256 and Plain authentication (including EntraId token-based Plain Auth introduced in v0.106-0).
+- **Authentication:** SCRAM-SHA-256. It is the only mechanism advertised in the `hello`/`isMaster` handshake, and the only one usable against a stock build. The gateway also accepts `MONGODB-OIDC` at SASL start for token-based authentication, but that path delegates to a `documentdb_api_internal.authenticate_token` function the extensions do not define, so it requires a deployment-supplied token provider. `PLAIN` is rejected.
 
 - **TLS Termination:** Terminates TLS on the gateway port (default `10260`), allowing drivers to connect over the standard MongoDB-style `mongodb://` connection string with `tls=true`.
 
diff --git a/readme.md b/readme.md
index 2c49164..a41f8c8 100644
--- a/readme.md
+++ b/readme.md
@@ -5,7 +5,7 @@ Welcome to the official documentation for [DocumentDB](https://github.com/docume
 ## Documentation Sections
 
 - [Getting Started](getting-started/index.md) - Quick start guides and basic concepts
-- [API Reference](api-reference/index.md) - Detailed API documentation
+- [API Reference](https://documentdb.io/docs/reference/) - Detailed API documentation
 - [PostgreSQL API](postgres-api/index.md) - PostgreSQL-compatible API documentation
 - [Architecture](architecture/index.md) - System architecture and design principles
 - [documentdb-local](documentdb-local/index.md) - Detailed documentation of the documentdb-local container image