diff --git a/api-reference/commands/aggregation/aggregate.md b/api-reference/commands/aggregation/aggregate.md
index 0856ead..6f5900e 100644
--- a/api-reference/commands/aggregation/aggregate.md
+++ b/api-reference/commands/aggregation/aggregate.md
@@ -18,6 +18,8 @@ db.collection.aggregate(pipeline, options)
 - **pipeline**: An array of aggregation stages that process and transform the data.
 - **options**: Optional. Specifies more options for the aggregation, such as `explain`, `allowDiskUse`, and `cursor`.
 
+Collation is off by default: an `aggregate` that sets `collation` fails with `collation is not supported in the aggregate command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Examples
 
 ### Example 1: Calculate total sales by category
diff --git a/api-reference/commands/aggregation/count.md b/api-reference/commands/aggregation/count.md
index 2c11dc9..a8a6dbb 100644
--- a/api-reference/commands/aggregation/count.md
+++ b/api-reference/commands/aggregation/count.md
@@ -20,6 +20,8 @@ db.collection.count(query, options)
 - `query`: A document specifying the selection criteria using query operators.
 - `options`: Optional. A document specifying options, such as `limit` and `skip`.
 
+Collation is off by default: a `count` that sets `collation` fails with `collation is not supported in the count command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Examples
 
 Here are some examples to demonstrate the usage of the `count` command:
diff --git a/api-reference/commands/aggregation/distinct.md b/api-reference/commands/aggregation/distinct.md
index ea417e0..770e983 100644
--- a/api-reference/commands/aggregation/distinct.md
+++ b/api-reference/commands/aggregation/distinct.md
@@ -19,7 +19,7 @@ db.collection.distinct(field, query, options)
 
 - `field`: The field that receives the returned distinct values.
 - `query`: Optional. A query that specifies the documents from which to retrieve the distinct values.
-- `options`: Optional. Other options for the command.
+- `options`: Optional. Other options for the command. `collation` isn't supported and fails with `collation is not supported in the distinct command yet.`
 
 ## Examples
 
diff --git a/api-reference/commands/diagnostic/hello.md b/api-reference/commands/diagnostic/hello.md
index c261eb1..c1482aa 100644
--- a/api-reference/commands/diagnostic/hello.md
+++ b/api-reference/commands/diagnostic/hello.md
@@ -9,7 +9,7 @@ category: diagnostic
 
 The `hello` command returns a document describing the role of the DocumentDB server, along with connection limits, supported authentication mechanisms, and the version of the DocumentDB engine you are connected to. It's the recommended way to discover the DocumentDB version from a MongoDB client, since the `internal.documentdb_versions` field reports the underlying engine version rather than only the emulated MongoDB wire-protocol version.
 
-The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, in `major-minor` form such as `0.113-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `0.113.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, when the shared library has been updated but `ALTER EXTENSION documentdb UPDATE` hasn't yet been run. A mismatch such as `["0.112-0", "0.113.0"]` indicates the SQL schema is behind the loaded binary.
+The versions in `internal.documentdb_versions` come from the backend DocumentDB PostgreSQL extension, not from the gateway. The array reports two values: the installed SQL extension version (from the `pg_extension` catalog, such as `1.0-0`) followed by the loaded binary version (from `documentdb_api.binary_version()`, in dotted form such as `1.0.0`). In PostgreSQL, the installed extension version *is* the schema version — it tracks which SQL upgrade scripts have been applied — so the first value reflects the schema currently installed in the database. These two values normally describe the same release and differ only in formatting, but they can diverge during an upgrade — for example, after the 1.0 packages are installed over 0.117 but before `ALTER EXTENSION documentdb UPDATE` has been run. A mismatch such as `["0.117-0", "1.0.0"]` indicates the SQL schema is behind the loaded binary.
 
 ## Syntax
 
@@ -42,7 +42,7 @@ The response includes the following fields. Fields marked as DocumentDB-specific
 | **`readOnly`** | `true` when the connection is read-only. |
 | **`connectionId`** | Identifier of the current connection. |
 | **`saslSupportedMechs`** | Authentication mechanisms the server supports, for example `SCRAM-SHA-256`. |
-| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (`major-minor`, for example `0.113-0`) — followed by the loaded binary version (dotted, for example `0.113.0`). These normally match and diverge only during an upgrade. |
+| **`internal.documentdb_versions`** | (DocumentDB-specific) Versions reported by the backend DocumentDB PostgreSQL extension: the installed SQL extension version — which in PostgreSQL is the schema version (for example `1.0-0`) — followed by the loaded binary version (dotted, for example `1.0.0`). These normally match and diverge only during an upgrade. |
 | **`ok`** | `1` when the command succeeds. |
 
 ## Examples
@@ -75,8 +75,8 @@ The server returns a document similar to the following:
   ],
   "internal": {
     "documentdb_versions": [
-      "0.113-0",
-      "0.113.0"
+      "1.0-0",
+      "1.0.0"
     ],
     "kind": ""
   },
@@ -95,7 +95,7 @@ db.runCommand({ hello: 1 }).internal.documentdb_versions
 The command returns an array with the installed SQL extension version followed by the loaded binary version:
 
 ```json
-[ "0.113-0", "0.113.0" ]
+[ "1.0-0", "1.0.0" ]
 ```
 
 The first value is the installed SQL extension version — the schema version, from the `pg_extension` catalog — and the second is the compiled binary version. They normally describe the same release and differ only in formatting.
diff --git a/api-reference/commands/query-and-write/delete.md b/api-reference/commands/query-and-write/delete.md
index 936d13f..0330f05 100644
--- a/api-reference/commands/query-and-write/delete.md
+++ b/api-reference/commands/query-and-write/delete.md
@@ -30,7 +30,7 @@ db.collection.deleteMany(
 | Parameter | Description |
 | --- | --- |
 | **<`filter`>** | A document that specifies the criteria for deletion. Only the documents that match the filter are deleted|
-| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation|
+| **`options`** | Optional. A document that specifies options for the delete operation. Common options include writeConcern and collation. Collation is off by default: a delete that sets it fails with `BSON field 'delete.deletes.collation' is not yet supported` unless the server enables `documentdb_core.enableCollation`.|
 
 ## Example(s)
 
diff --git a/api-reference/commands/query-and-write/find.md b/api-reference/commands/query-and-write/find.md
index f8de849..ac2922f 100644
--- a/api-reference/commands/query-and-write/find.md
+++ b/api-reference/commands/query-and-write/find.md
@@ -25,6 +25,8 @@ db.collection.find(query, projection, options)
 | **`projection`** | (Optional) A document that specifies the fields in the matching documents to be returned in the result set|
 | **`options`** | (Optional) A document that specifies options for query behavior and results|
 
+Collation is off by default: a `find` that sets `collation` fails with `collation is not supported in the find command yet.` unless the server enables `documentdb_core.enableCollation`.
+
 ## Example(s)
 
 Consider this sample document from the stores collection in the StoreData database.
diff --git a/api-reference/commands/query-and-write/findandmodify.md b/api-reference/commands/query-and-write/findandmodify.md
index 286c847..d59c219 100644
--- a/api-reference/commands/query-and-write/findandmodify.md
+++ b/api-reference/commands/query-and-write/findandmodify.md
@@ -35,6 +35,8 @@ db.collection.findAndModify({
 - **fields**: Limits the fields to return for the matching document.
 - **upsert**: If `true`, creates a new document if no document matches the query.
 
+`collation` isn't supported and fails with `findAndModify.collation is not implemented yet`.
+
 ## Examples
 
 ### Example 1: Update total sales
@@ -135,6 +137,19 @@ db.stores.findAndModify({
     ]
   },
   "promotionEvents": [
+    {
+      "eventName": "Incredible Discount Days",
+      "promotionalDates": {
+        "startDate": { "Year": 2024, "Month": 2, "Day": 11 },
+        "endDate": { "Year": 2024, "Month": 2, "Day": 18 }
+      },
+      "discounts": [
+        { "categoryName": "Square Sunglasses", "discountPercentage": 16 },
+        { "categoryName": "Safety Glasses", "discountPercentage": 17 },
+        { "categoryName": "Wayfarers", "discountPercentage": 7 },
+        { "categoryName": "Eyewear Accessories", "discountPercentage": 12 }
+      ]
+    },
     {
       "eventName": "Electronics Super Saver",
       "promotionalDates": { "startDate": "2025-09-31", "endDate": "2025-09-31" },
@@ -156,7 +171,7 @@ db.stores.findAndModify({
 
 ### Example 3: Remove a promotional event
 
-Suppose we want to remove the "Electronics Super Saver" promotional event from the store with `_id` "e5767a9f-cd95-439c-9ec4-7ddc13d22926" and return the original document.
+Suppose we want to remove the "Electronics Super Saver" promotional event from the store with `_id` "e5767a9f-cd95-439c-9ec4-7ddc13d22926" and return the updated document.
 
 ```javascript
 db.stores.findAndModify({
diff --git a/api-reference/commands/query-and-write/update.md b/api-reference/commands/query-and-write/update.md
index 7552267..cc22441 100644
--- a/api-reference/commands/query-and-write/update.md
+++ b/api-reference/commands/query-and-write/update.md
@@ -9,6 +9,8 @@ category: query-and-write
 
 The `update` command is used to modify existing documents within a collection. The `update` command can be used to update one or multiple documents based on filtering criteria. Values of fields can be changed, new fields and values can be added and existing fields can be removed.
 
+The `collation` option isn't supported and fails with `BSON field 'update.updates.collation' is not yet supported`.
+
 ## Example(s)
 
 Consider this sample document from the stores collection in the StoreData database.
diff --git a/api-reference/operators/aggregation/$changestream.md b/api-reference/operators/aggregation/$changestream.md
index ba10015..6888e7d 100644
--- a/api-reference/operators/aggregation/$changestream.md
+++ b/api-reference/operators/aggregation/$changestream.md
@@ -1,13 +1,16 @@
 ---
 title: $changeStream
-description: The $changeStream stage opens a change stream cursor to track data changes in real-time.
+description: The $changeStream stage opens a change stream cursor in MongoDB. DocumentDB does not support it.
 type: operators
 category: aggregation
 ---
 
 # $changeStream
 
-The `$changeStream` aggregation stage opens a change stream cursor that tracks data changes in real-time. This stage enables applications to react to insert, update, delete, and other operations as they occur in the collection.
+> [!IMPORTANT]
+> DocumentDB does not support `$changeStream`. Any pipeline that uses it, including `db.collection.watch()`, fails with `Stage $changeStream is not supported yet in native pipeline` (`CommandNotSupported`, code 115).
+
+In MongoDB, the `$changeStream` aggregation stage opens a cursor that reports inserts, updates, deletes, and other changes as they happen. The syntax below is listed for reference only.
 
 ## Syntax
 
@@ -37,123 +40,9 @@ The `$changeStream` aggregation stage opens a change stream cursor that tracks d
 | **`startAtOperationTime`** | Optional. timestamp for starting change stream from a specific time. |
 | **`showExpandedEvents`** | Optional. Boolean. Include another change stream events. Default is false. |
 
-## Examples
-
-Consider this sample document from the stores collection.
-
-```json
-{
-    "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
-    "name": "First Up Consultants | Beverage Shop - Satterfieldmouth",
-    "location": {
-        "lat": -89.2384,
-        "lon": -46.4012
-    },
-    "staff": {
-        "totalStaff": {
-            "fullTime": 8,
-            "partTime": 20
-        }
-    },
-    "sales": {
-        "totalSales": 75670,
-        "salesByCategory": [
-            {
-                "categoryName": "Wine Accessories",
-                "totalSales": 34440
-            },
-            {
-                "categoryName": "Bitters",
-                "totalSales": 39496
-            },
-            {
-                "categoryName": "Rum",
-                "totalSales": 1734
-            }
-        ]
-    },
-    "promotionEvents": [
-        {
-            "eventName": "Unbeatable Bargain Bash",
-            "promotionalDates": {
-                "startDate": {
-                    "Year": 2024,
-                    "Month": 6,
-                    "Day": 23
-                },
-                "endDate": {
-                    "Year": 2024,
-                    "Month": 7,
-                    "Day": 2
-                }
-            },
-            "discounts": [
-                {
-                    "categoryName": "Whiskey",
-                    "discountPercentage": 7
-                },
-                {
-                    "categoryName": "Bitters",
-                    "discountPercentage": 15
-                },
-                {
-                    "categoryName": "Brandy",
-                    "discountPercentage": 8
-                },
-                {
-                    "categoryName": "Sports Drinks",
-                    "discountPercentage": 22
-                },
-                {
-                    "categoryName": "Vodka",
-                    "discountPercentage": 19
-                }
-            ]
-        },
-        {
-            "eventName": "Steal of a Deal Days",
-            "promotionalDates": {
-                "startDate": {
-                    "Year": 2024,
-                    "Month": 9,
-                    "Day": 21
-                },
-                "endDate": {
-                    "Year": 2024,
-                    "Month": 9,
-                    "Day": 29
-                }
-            },
-            "discounts": [
-                {
-                    "categoryName": "Organic Wine",
-                    "discountPercentage": 19
-                },
-                {
-                    "categoryName": "White Wine",
-                    "discountPercentage": 20
-                },
-                {
-                    "categoryName": "Sparkling Wine",
-                    "discountPercentage": 19
-                },
-                {
-                    "categoryName": "Whiskey",
-                    "discountPercentage": 17
-                },
-                {
-                    "categoryName": "Vodka",
-                    "discountPercentage": 23
-                }
-            ]
-        }
-    ]
-}
-```
-
-### Example 1: Monitor all changes in stores collection
+## Example
 
-This operation sets up a change stream to monitor all changes in the stores collection.
+This pipeline is rejected:
 
 ```javascript
 db.stores.aggregate([
@@ -165,27 +54,6 @@ db.stores.aggregate([
 ])
 ```
 
-When a store document is updated, the change stream returns the change event with the full document.
-
-```json
-{
-  "_id": { "_data": "AeARBpQ/AAAA" },
-  "operationType": "update",
-  "fullDocument": {
-    "_id": "905d1939-e03a-413e-a9c4-221f74055aac",
-    "name": "Trey Research | Home Office Depot - Lake Freeda",
-    "sales": {
-      "revenue": 42500
-    },
-    "company": "Trey Research",
-    "lastUpdated": "ISODate('2024-06-16T10:30:00.000Z')"
-  },
-  "ns": {
-    "db": "StoreData",
-    "coll": "stores"
-  },
-  "documentKey": {
-    "_id": "905d1939-e03a-413e-a9c4-221f74055aac"
-  }
-}
+```
+Stage $changeStream is not supported yet in native pipeline
 ```
diff --git a/api-reference/operators/aggregation/$collstats.md b/api-reference/operators/aggregation/$collstats.md
index 8920caa..e7d9775 100644
--- a/api-reference/operators/aggregation/$collstats.md
+++ b/api-reference/operators/aggregation/$collstats.md
@@ -14,7 +14,6 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab
 ```javascript
 {
   $collStats: {
-    latencyStats: { histograms: <boolean> },
     storageStats: { scale: <number> },
     count: {}
   }
@@ -25,10 +24,11 @@ The $collStats stage in the aggregation pipeline is used to return statistics ab
 
 | Parameter | Description |
 | --- | --- |
-| **`latencyStats`** | Optional. Specifies whether to include latency statistics. The `histograms` field is a boolean that indicates whether to include histograms of latency data. |
 | **`storageStats`** | Optional. Specifies whether to include storage statistics. The `scale` field is a number that indicates the scale factor for the storage statistics. |
 | **`count`** | Optional. Includes the count of documents in the collection. |
 
+`latencyStats` and `queryExecStats` aren't supported; either one fails with `collStats with <option> not supported yet` (`CommandNotSupported`).
+
 ## Examples
 
 Consider this sample document from the stores collection.
diff --git a/api-reference/operators/array-update/$positional-all.md b/api-reference/operators/array-update/$positional-all.md
index 2ef174c..b52e6f0 100644
--- a/api-reference/operators/array-update/$positional-all.md
+++ b/api-reference/operators/array-update/$positional-all.md
@@ -1,13 +1,13 @@
 ---
 title: $[]
-description: The $[] operator is used to update all elements in an array that match the query condition.
+description: The $[] all positional operator applies an update to every element of an array.
 type: operators
 category: array-update
 ---
 
 # $[]
 
-The $[] operator in DocumentDB is used to update all elements in an array that match a specified condition. This operator allows you to perform updates on multiple elements in an array without specifying their positions. It is particularly useful when you need to apply the same update to all items in an array.
+The `$[]` all positional operator applies an update to every element of an array in each matched document. Unlike `$`, it doesn't depend on which element the query matched, and unlike `$[<identifier>]`, it takes no `arrayFilters`. If the path holds a value that isn't an array, the update fails.
 
 ## Syntax
 
@@ -28,7 +28,7 @@ db.collection.update(
 | --- | --- |
 | **`<query>`** | The selection criteria for the documents to update. |
 | **`<arrayField>`** | The field containing the array to update. |
-| **`<value>`** | The value to set for each matching element in the array. |
+| **`<value>`** | The value to set for each element in the array. |
 
 ## Examples
 
@@ -150,7 +150,7 @@ This query updates all elements in the discounts array inside each promotion eve
 
 ```javascript
 db.stores.updateOne(
-  { _id: "905d1939-e03a-413e-a9c4-221f74055aac" },
+  { _id: "0fcc0bf0-ed18-4ab8-b558-9848e18058f4" },
   {
     $inc: {
       "promotionEvents.$[].discounts.$[].discountPercentage": 5
@@ -165,7 +165,7 @@ This query increase the total sales for all categories by 10% by using the $[] o
 
 ```javascript
 db.stores.update(
-  { _id: "905d1939-e03a-413e-a9c4-221f74055aac" },
+  { _id: "0fcc0bf0-ed18-4ab8-b558-9848e18058f4" },
   {
     $mul: {
       "sales.salesByCategory.$[].totalSales": 1.10
diff --git a/api-reference/operators/evaluation-query/$jsonschema.md b/api-reference/operators/evaluation-query/$jsonschema.md
index 8b173c3..ea3b82d 100644
--- a/api-reference/operators/evaluation-query/$jsonschema.md
+++ b/api-reference/operators/evaluation-query/$jsonschema.md
@@ -58,8 +58,10 @@ DocumentDB supports the following JSON Schema keywords:
 |---------|------|-------------|--------|
 | `additionalItems` | arrays | Schema for extra array items | Extended array validation |
 | `bsonType` | all types | MongoDB extension - accepts BSON type aliases | `"string"`, `"int"`, `"double"`, `"object"`, `"array"`, `"bool"`, `"date"` |
-| `exclusiveMinimum` | numbers | Exclusive minimum boundary | Advanced numeric validation |
-| `exclusiveMaximum` | numbers | Exclusive maximum boundary | Advanced numeric validation |
+| `description` | N/A | Informational text; must be a string | Documentation only |
+| `enum` | all types | Value must equal one of the listed values | Restrict a field to fixed values |
+| `exclusiveMinimum` | numbers | Boolean; makes `minimum` exclusive (requires `minimum`) | Advanced numeric validation |
+| `exclusiveMaximum` | numbers | Boolean; makes `maximum` exclusive (requires `maximum`) | Advanced numeric validation |
 | `items` | arrays | Schema for array elements | Array element validation |
 | `minimum` | numbers | Minimum value constraint | Numeric validation |
 | `maximum` | numbers | Maximum value constraint | Numeric validation |
@@ -68,6 +70,7 @@ DocumentDB supports the following JSON Schema keywords:
 | `multipleOf` | numbers | Value must be multiple of specified number | Mathematical constraints |
 | `minLength` | strings | Minimum string length | String validation |
 | `maxLength` | strings | Maximum string length | String validation |
+| `oneOf` | all types | Value must match exactly one of the listed subschemas | Alternative structures |
 | `pattern` | strings | Regular expression pattern matching | String format validation |
 | `properties` | objects | Define validation rules for object fields | Schema definition for nested objects |
 | `required` | objects | Array of required field names | Enforce mandatory fields |
@@ -76,22 +79,20 @@ DocumentDB supports the following JSON Schema keywords:
 
 ### Unsupported Keywords
 
-These JSON Schema keywords are yet to be supported in DocumentDB:
-
-| Keyword | Type | Reason for Non-Support | Workaround |
-|---------|------|----------------------|------------|
-| `additionalProperties` | objects | Not implemented | Use explicit `properties` definitions |
-| `allOf` | all types | Logical operator not supported | Use nested validation |
-| `anyOf` | all types | Logical operator not supported | Use separate queries |
-| `dependencies` | objects | Complex dependency validation not supported | Handle in application logic |
-| `description` | N/A | Might not appear in error messages | Informational only |
-| `enum` | all types | Enumeration validation not supported | Use `$in` operator instead |
-| `maxProperties` | objects | Property count validation not supported | Handle in application logic |
-| `minProperties` | objects | Property count validation not supported | Handle in application logic |
-| `not` | all types | Negation operator not supported | Use positive validation rules |
-| `oneOf` | all types | Logical operator not supported | Use application-level validation |
-| `patternProperties` | objects | Pattern-based property validation not supported | Use explicit property names |
-| `title` | N/A | Metadata field not processed | Use `description` instead |
+These keywords are rejected with `The '<keyword>' keyword in $jsonSchema is not supported at this time`:
+
+| Keyword | Type | Workaround |
+|---------|------|------------|
+| `$ref` | N/A | Inline the referenced schema |
+| `$schema` | N/A | Omit it |
+| `default` | N/A | Set defaults in application logic |
+| `definitions` | N/A | Inline the subschemas |
+| `format` | strings | Use `pattern` |
+| `id` | N/A | Omit it |
+
+`encrypt` and `encryptMetadata` are accepted so that client-side field-level encryption schemas parse; DocumentDB doesn't encrypt anything.
+
+Any other keyword, including `additionalProperties`, `allOf`, `anyOf`, `dependencies`, `maxProperties`, `minProperties`, `not`, `patternProperties`, and `title`, is rejected with `Unknown $jsonSchema keyword: <keyword>`.
 
 ## Examples
 
@@ -131,6 +132,7 @@ This query retrieves all stores with names between 5 and 100 characters long, an
 db.stores.find({
   $jsonSchema: {
     bsonType: "object",
+    required: ["name", "location"],
     properties: {
       _id: {
         bsonType: "string"
@@ -142,6 +144,7 @@ db.stores.find({
       },
       location: {
         bsonType: "object",
+        required: ["lat", "lon"],
         properties: {
           lat: {
             bsonType: "double",
@@ -169,9 +172,11 @@ This query retrieves all store documents where the sales field is a valid object
 db.stores.find({
   $jsonSchema: {
     bsonType: "object",
+    required: ["sales"],
     properties: {
       sales: {
         bsonType: "object",
+        required: ["totalSales", "salesByCategory"],
         properties: {
           totalSales: {
             bsonType: "int",
@@ -202,20 +207,22 @@ db.stores.find({
 
 ```
 
-This query should return this output:
+This query matches one store in the sample data. Its `name` and `sales` fields are:
 
 ```javascript
 [
   {
-    _id: 'new-store-001',
-    name: 'Adatum Corporation - Downtown Branch',
-    sales: { totalSales: 5000 },
-    createdDate: ISODate('2025-06-11T11:11:32.262Z'),
-    status: 'new',
-    staff: { totalStaff: { fullTime: 0, partTime: 0 } },
-    version: 1,
-    storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'),
-    storeFeatures: 213
+    _id: 'f2a8c190-28e4-4e14-9d8b-0256e53dca66',
+    name: 'Fabrikam, Inc. | Car Accessory Outlet - West Adele',
+    sales: {
+      salesByCategory: [
+        { categoryName: 'Phone Mounts', totalSales: 12000 },
+        { categoryName: 'Dash Cameras', totalSales: 22300 }
+      ],
+      peakSalesRecord: 100000,
+      revenue: 50000,
+      totalSales: 50000
+    }
   }
 ]
 ```
@@ -229,12 +236,15 @@ db.stores.find({
   $and: [
     {
       $jsonSchema: {
+        required: ["staff"],
         properties: {
           staff: {
             bsonType: "object",
+            required: ["totalStaff"],
             properties: {
               totalStaff: {
                 bsonType: "object",
+                required: ["fullTime"],
                 properties: {
                   fullTime: {
                     bsonType: "int",
@@ -255,26 +265,19 @@ db.stores.find({
 }).limit(1)
 ```
 
-This query returns the following result:
+This query matches one store in the sample data. Its `name`, `staff` and `sales.totalSales` fields are:
 
 ```javascript
 [
   {
-    _id: 'future-electronics-001',
-    address: { city: 'New Tech City' },
-    name: 'Boulder Innovations - Future Electronics Hub',
-    sales: { totalSales: 25000 },
-    establishedDate: ISODate('2025-06-11T11:14:23.147Z'),
-    categories: [ 'electronics', 'gadgets', 'smart-home' ],
-    promotionEvents: [],
-    ratings: { average: 0, count: 0, reviews: [] },
-    inventory: {
-      lastUpdated: ISODate('2025-06-11T11:14:23.147Z'),
-      totalItems: 0,
-      lowStockAlerts: []
+    _id: 'f2a8c190-28e4-4e14-9d8b-0256e53dca66',
+    name: 'Fabrikam, Inc. | Car Accessory Outlet - West Adele',
+    staff: {
+      maxStaffCapacity: 25,
+      employeeCount: { fullTime: 10, partTime: 2 },
+      totalStaff: { fullTime: 10, partTime: 2 }
     },
-    storeOpeningDate: ISODate('2025-06-11T11:11:32.262Z'),
-    storeFeatures: 120
+    sales: { totalSales: 50000 }
   }
 ]
 ```
diff --git a/documentdb-local/index.md b/documentdb-local/index.md
index 1c75ba4..fe73dee 100644
--- a/documentdb-local/index.md
+++ b/documentdb-local/index.md
@@ -7,7 +7,9 @@ description: Learn how to install and run DocumentDB Local using Docker for loca
 
 DocumentDB Local provides a lightweight, containerized environment for developing and testing applications locally, including prototyping and integration testing.
 
-The examples below use the PostgreSQL 17 image from release **0.117.0**. Other PostgreSQL major versions and image tags are listed in the [0.117 release](https://github.com/documentdb/documentdb/releases/tag/v0.117-0). To test the 1.0 release candidate, see [Try the 1.0 release candidate](../getting-started/release-candidate.md).
+The examples below use the PostgreSQL 17 image from release **1.0.0**. Images for PostgreSQL 15 to 18 are tagged `pg15-1.0.0` to `pg18-1.0.0`, for Linux amd64 and arm64; `latest` points to `pg17-1.0.0`. Use a versioned tag when you need a reproducible setup. The [1.0 release notes](../getting-started/release-notes-1.0.md) list what changed and the known issues.
+
+> **Usage telemetry is on by default.** The 1.0 image reports its version, platform and CPU architecture to Scarf at startup and hourly. Turn it off with `-e DOCUMENTDB_USAGE_TELEMETRY=false`. See [Usage telemetry](#usage-telemetry).
 
 ## Prerequisites
 
@@ -18,40 +20,38 @@ The examples below use the PostgreSQL 17 image from release **0.117.0**. Other P
 Get the Docker container image using `docker pull`.
 
 ```bash
-docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0
-
+docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0
 ```
 
 ## Running
 
-To run the container, use `docker run`. Afterwards, use `docker ps` to validate that the container is running.
+Choose the admin credentials first, in the same terminal (this works in bash and zsh):
 
 ```bash
-read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
-read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
-printf '\n'
+printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
+printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
 export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
+```
 
-docker run -dt -p 127.0.0.1:10260:10260 --name docdb \
-  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
-  --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
-  --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"
+Then start the container with `docker run`, and use `docker ps` to check that it is running:
 
+```bash
+docker run -dt -p 127.0.0.1:10260:10260 --name docdb \
+  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0
 
 docker ps
 ```
 
 ```output
-CONTAINER ID   IMAGE                                                                             COMMAND                  CREATED         STATUS         PORTS                              NAMES
-5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0                        "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   127.0.0.1:10260->10260/tcp       docdb
+CONTAINER ID   IMAGE                                                         COMMAND                  CREATED         STATUS                            PORTS                        NAMES
+5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0     "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds (health: starting)   127.0.0.1:10260->10260/tcp   docdb
 ```
 
-> The prompts export the credentials for the later client examples, and the guards
-> prevent an empty value from falling through to the image's public defaults. If you
-> open a new shell, set both variables again. The loopback binding makes the gateway
-> reachable only from this host. To allow remote clients, change it to
-> `-p 10260:10260` only after restricting the port with a firewall and configuring a
-> certificate that remote clients can validate.
+> The exported variables are reused by the client examples below; if you open a new shell, set them again. The guards stop an empty value from falling through to the image's public default credentials, which the container still accepts but warns about loudly. The credentials are passed as environment variables because `--username` and `--password` arguments stay visible in the container's process list.
+>
+> The loopback binding makes the gateway reachable only from this host. To allow remote clients, change it to `-p 10260:10260` only after restricting the port with a firewall and configuring a certificate that remote clients can validate.
 >
 > This container writes its database to `/data`, which the image declares as a Docker volume. The command above mounts nothing there, so each `docker run` gets a fresh anonymous volume: the data does not survive re-creating the container, and the old volume is left behind on the host until you prune it. Mount a named volume - `-v documentdb-data:/data` - to persist it. See `--data-path` in the table below.
 
@@ -76,7 +76,7 @@ First start typically takes a few tens of seconds. If the command has not return
 ```bash
 mongosh localhost:10260 \
   -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  -p \
   --authenticationMechanism SCRAM-SHA-256 \
   --tls --tlsAllowInvalidCertificates
 ```
@@ -101,7 +101,7 @@ The following table summarizes the available Docker commands for configuring the
 |---|---|---|---|---|---|
 | Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration |
 | Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. It may not be an internal DocumentDB role name, and it may not begin with `documentdb`, `citus`, `pg`, or `internal_role` (case-insensitive). The container rejects a reserved name and exits before starting anything. |
-| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. |
+| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. When the password is left at its default, the container prints a warning at startup; `DOCUMENTDB_ALLOW_DEFAULT_PASSWORD=true` silences it. Prefer the environment variable: a `--password` argument stays visible in the container's process list. A changed password on an existing data volume is ignored; the volume keeps the admin user it was initialized with. |
 | The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published. For local use, bind only to loopback - for example, `-p 127.0.0.1:10260:10260`. To use host port `27017` without changing the gateway port, publish `-p 127.0.0.1:27017:10260`; add `--documentdb-port 27017` only when changing the container-side port too. |
 | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. |
 | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "<value>" does not exist` after PostgreSQL has already initialized, and the container exits. |
@@ -112,14 +112,17 @@ The following table summarizes the available Docker commands for configuring the
 | Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. |
 | Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | PEM-format private key. Must be set together with `--cert-path` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` |
 | Set the TLS mode for client connections. | `--tlsMode [value]` | Overrides `TLS_MODE` environment variable | `disabled`, `allowTLS`, `requireTLS` | `allowTLS` | With `allowTLS` the gateway accepts both plain and TLS connections; `disabled` behaves the same way. `requireTLS` rejects plain connections, so every client must connect with `tls=true`. |
-| Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Loads the `StoreData` dataset once per fresh data volume. Use a new, empty volume to seed again; see [Built-in sample data](#built-in-sample-data). |
-| Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files run alphabetically using `mongosh`, once per fresh data volume. Syntax or runtime errors abort initialization. An attempted script run is not repeated on restart, so fix the scripts and use a fresh volume to retry. |
+| Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Loads the `StoreData` dataset once per data volume: a marker file in the volume records that it ran, so it also loads into a volume that already holds data but was never seeded. Use a new volume to seed again; see [Built-in sample data](#built-in-sample-data). |
+| Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files run alphabetically using `mongosh`, once per data volume (a marker file records the attempt, so they also run against an existing volume that never ran them), before the built-in sample data when both are enabled. A syntax or runtime error stops the container with an error. The run isn't repeated on restart, so fix the scripts and start from a fresh volume. |
 | Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | `true`, `false` (`SKIP_INIT_DATA` only - the flag itself takes no value) | N/A | Legacy alias for `--init-data false`. Note that `SKIP_INIT_DATA=false` does the opposite of the flag: with `INIT_DATA` unset it enables the built-in sample data. Does not affect `--init-data-path`. |
-| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A (takes no value) | N/A | Extended RUM is enabled by default. **Known issue:** this flag does not currently disable it - the container still starts with `documentdb_extended_rum` configured. |
+| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A (takes no value) | N/A | **Deprecated and ignored**, apart from a warning at startup; it will be removed in a later release. `documentdb_extended_rum` is always enabled on a volume this image initializes. |
 | Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | The gateway's operational metrics, unrelated to [usage telemetry](#usage-telemetry). **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. |
 | Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | **Known issue:** the value is validated at startup but does not currently change what the container logs. To change the gateway's own verbosity, set the `DOCUMENTDB_LOG_LEVEL` environment variable instead; it takes a tracing filter such as `info` or `debug` (`quiet` is not one of its values). |
+| Turn usage telemetry on or off. | `--usage-telemetry [value]` | Overrides `DOCUMENTDB_USAGE_TELEMETRY` environment variable | `true`, `false` (also `1`/`0`, `yes`/`no`, `on`/`off`, case-insensitive) | `true` | Reports the image version, platform and CPU architecture at startup and hourly. An unrecognized value is treated as `false` with a warning, so an opt-out can never stop the container from starting. See [Usage telemetry](#usage-telemetry). |
+| Turn usage telemetry off. | `--disable-usage-telemetry` | N/A | N/A (takes no value) | N/A | Same as `--usage-telemetry false`. |
+| Set TOAST compression. | `--toast-compression [value]` | Overrides `DOCUMENTDB_TOAST_COMPRESSION` environment variable | `lz4`, `pglz`, `default` | `lz4` | Compression for large values PostgreSQL stores out of line (TOAST). `lz4` decompresses large documents faster, `pglz` is PostgreSQL's built-in method, and `default` leaves the server's own setting alone. Affects newly written values only. Ignored, with a warning, when `--start-pg false`. |
 
-> `--skip-init-data` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-extended-rum false` - is rejected as an unexpected argument and the container exits.
+> `--skip-init-data`, `--disable-usage-telemetry` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-usage-telemetry false` - is rejected as an unknown option and the container exits.
 
 A complete `docker run` showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from the **Running** section above with a persistent volume and sample data added, so remove that container first with `docker rm -f docdb`:
 
@@ -128,25 +131,35 @@ docker run -dt \
   -p 127.0.0.1:10260:10260 \
   -v documentdb-data:/data \
   --name docdb \
-  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
-  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0 \
   --init-data true
 ```
 
 ## Usage telemetry
 
-Starting with the 1.0 RC2 images (`pg15-1.0-rc2` to `pg18-1.0-rc2`), DocumentDB Local sends anonymous usage data by default. The 0.117 images used on this page send none, and neither do the native packages.
+The 1.0 image sends usage data by default. The native packages send nothing.
+
+At startup and then hourly, the image reports its version, platform and CPU architecture to [Scarf](https://scarf.sh). It never sends database, collection or user names, queries, documents or credentials. Scarf does see the source IP address of each request, and the privacy statement says that address shouldn't be assumed to be anonymous once received. A `[TELEMETRY]` notice in the container log says when it is on.
 
-At startup and then hourly, the image reports its version, platform and CPU architecture to [Scarf](https://scarf.sh). It never sends database, collection or user names, queries, documents or credentials. A `[TELEMETRY]` notice in the container log says when it is on.
+To turn it off, add any of these before the image name:
 
-To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1` before the image name, or `--disable-usage-telemetry` after it. In CI, turn it off explicitly: the image skips telemetry when `CI` is set inside the container, but `docker run` doesn't pass the host's `CI` through. `--enable-telemetry` is a separate setting for the gateway's own metrics and doesn't affect this.
+```bash
+-e DOCUMENTDB_USAGE_TELEMETRY=false
+-e NO_ANALYTICS=1
+-e DO_NOT_TRACK=1
+```
+
+or `--disable-usage-telemetry` (or `--usage-telemetry false`) after it. `NO_ANALYTICS` and `DO_NOT_TRACK` win over any setting that turns it on. To send the reports to your own collector instead, set `DOCUMENTDB_USAGE_TELEMETRY_ENDPOINT`.
+
+In CI, turn it off explicitly with `-e DOCUMENTDB_USAGE_TELEMETRY=false`. The image skips telemetry only when `CI`, `GITHUB_ACTIONS` or `TF_BUILD` is set to a non-empty value in the container's own environment, and `docker run` doesn't pass the runner's variables through: a container started on a CI runner still reports unless you forward one, for example `-e GITHUB_ACTIONS`. `--enable-telemetry` is a separate setting for the gateway's own metrics and doesn't affect this.
 
-The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-RC2/documentdb-local/PRIVACY.md) has the details. The image also includes it at `/home/documentdb/PRIVACY.md`.
+The [privacy statement](https://github.com/documentdb/documentdb/blob/v1.0-0/documentdb-local/PRIVACY.md) has the details. The image also includes it at `/home/documentdb/PRIVACY.md`.
 
 ## Built-in sample data
 
-Release 0.117 replaces the earlier small `sampledb` seed with the complete `StoreData` dataset. Loading remains opt-in: add `--init-data true` to the container arguments, as in the example above.
+The built-in sample data is the `StoreData` dataset. Loading it is opt-in: add `--init-data true` to the container arguments, as in the example above. If you also give scripts in `--init-data-path`, both run: your scripts first, then the sample data, each tracked by its own marker in the volume.
 
 | Collection | Documents |
 |---|---:|
@@ -160,8 +173,19 @@ db.getSiblingDB("StoreData").stores.countDocuments({})   // 41505
 db.getSiblingDB("StoreData").ratings.countDocuments({})  // 2
 ```
 
-Seeding remains one-shot per data volume. Previously seeded volumes are **not automatically migrated** to StoreData; use a new, empty volume when you want the new sample dataset. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the [versioned sample-data guide](https://github.com/documentdb/documentdb/tree/v0.117-0/documentdb-local/sample-data) for manual loader instructions.
+Seeding is one-shot per data volume; use a new, empty volume to seed again. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the [versioned sample-data guide](https://github.com/documentdb/documentdb/tree/v1.0-0/documentdb-local/sample-data) for manual loader instructions.
+
+## Container lifecycle
+
+- **Health check.** The image has a Docker health check. `docker inspect -f '{{.State.Health.Status}}' docdb` reports `healthy` once DocumentDB accepts connections.
+- **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f`, an out-of-memory kill or a host crash, the next start removes the stale file, but only when the volume's lock shows a 1.0 container wrote it. Otherwise it refuses to start, because an older container may still be using the volume. Once nothing else uses it, re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it (`docker start` can't add the variable). Don't share a volume between hosts. A second container on a volume that is already in use exits immediately.
+- **PostgreSQL loss stops the container.** If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (`DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT`), so a restart policy can bring it back.
+
+## Upgrading the image
+
+A newer image on an existing data volume doesn't update the DocumentDB extensions in it ([#773](https://github.com/documentdb/documentdb/issues/773)), so the volume keeps the old schema under the new binaries. Upgrading a volume in place is not supported in 1.0. To move data from a 0.117 container to 1.0, export it with `mongodump`, start a 1.0 container on a new volume, and load it with `mongorestore`. The PostgreSQL major version of the image must also match the one that initialized the volume.
 
+If you do start a 1.0 image on a volume an older container used, the 1.0 image refuses to start while the old container's `postmaster.pid` is still there; see [Container lifecycle](#container-lifecycle) for the override and removing it afterward. For 0.116 and 0.117, stop the old container with `docker stop` first, which removes the file; after `docker kill`, `docker rm -f` or a crash it stays. Images 0.114 and earlier don't normally stop PostgreSQL cleanly, so their volumes usually keep the file.
 
 ## Feature support
 
@@ -196,19 +220,19 @@ docker run -dt \
   -v documentdb-data:/data \
   -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \
   --name docdb \
-  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
-  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}"
+  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
+  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0
 ```
 
-Point it inside the data directory rather than at a volume of its own: the entrypoint takes ownership of the data directory on every start, whereas a separate volume is created root-owned and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the same step runs `chmod -R 750` over that directory, so from the second start onwards the private key is group-readable rather than owner-only, and it is included in any backup of the data volume.
+Point it inside the data directory rather than at a volume of its own: a separate volume is created root-owned, and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the key is included in any backup of the data volume. If the entrypoint ever has to repair the data directory's ownership (it does when the owner doesn't match, or with `DOCUMENTDB_FORCE_OWNERSHIP_REPAIR=true`), it runs `chmod -R 750` over the directory, which leaves the private key group-readable rather than owner-only.
 
 ### Use the certificate with mongosh
 
 ```bash
 mongosh localhost:10260 \
   -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  -p \
   --authenticationMechanism SCRAM-SHA-256 \
   --tls --tlsCAFile ~/documentdb-cert.pem
 ```
diff --git a/getting-started/index.md b/getting-started/index.md
index a497e8c..40441a8 100644
--- a/getting-started/index.md
+++ b/getting-started/index.md
@@ -11,12 +11,12 @@ DocumentDB is an open-source document database platform built on PostgreSQL. It
 
 DocumentDB provides a NoSQL datastore implemented using PostgreSQL, giving developers complete visibility into the architecture and implementation of the engine. It's designed to offer:
 
-- Full compatibility with the MongoDB wire protocol through the `pg_documentdb_gw` gateway
+- MongoDB wire protocol compatibility through the `pg_documentdb_gw` gateway, so MongoDB drivers and tools connect unmodified
 - Public document CRUD and management APIs through the `pg_documentdb` extension
 - Native BSON document support via the `pg_documentdb_core` PostgreSQL extension
 - Advanced indexing capabilities including single field, multi-key, compound, text, geospatial, and vector indexes
 - Vector search functionality powered by the `pgvector` PostgreSQL extension
-- Enterprise-grade security with SCRAM authentication
+- SCRAM-SHA-256 authentication and TLS on the gateway
 - Full PostgreSQL compatibility for advanced SQL operations
 
 ## Key Features
@@ -24,12 +24,12 @@ DocumentDB provides a NoSQL datastore implemented using PostgreSQL, giving devel
 - **PostgreSQL Foundation**: Built on the powerful PostgreSQL engine, allowing you to leverage both document and relational capabilities
 - **Open Source**: Released under the MIT license with no restrictions on usage, modification, or distribution
 - **Document Database Standard**: First implementation towards creating an open standard for document databases, similar to ANSI SQL for relational databases
-- **Cloud Ready**: Supports multi-cloud deployments across major cloud providers with native integration in Azure Cosmos DB
+- **Runs anywhere**: Linux packages, a container image for local development, and a Kubernetes operator for replicated deployments
 - **Developer Friendly**: Rich ecosystem of tools and extensions, including VS Code integration and MongoDB compatibility
 
 ## Architecture Components
 
-DocumentDB consists of three primary components:
+DocumentDB consists of four primary components:
 
 1. **pg_documentdb_core**: A PostgreSQL extension that provides:
    - Native BSON data type support in PostgreSQL
@@ -49,6 +49,8 @@ DocumentDB consists of three primary components:
    - Translates MongoDB commands into calls against `pg_documentdb`
    - Manages cursors, sessions, and connection state for MongoDB drivers
 
+4. **pg_documentdb_extended_rum**: The index access method behind DocumentDB's document indexes, required in 1.0
+
 ## Common Use Cases
 
 - **Modern Web Applications**: Store and query JSON documents with MongoDB compatibility
diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md
index 24dff2a..978fbca 100644
--- a/getting-started/mongo-shell-quickstart.md
+++ b/getting-started/mongo-shell-quickstart.md
@@ -24,19 +24,21 @@ docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
 # Tag the image for convenience
 docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
 
-read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
-read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
-printf '\n'
+printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
+printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
 export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
 
 # Run the container with your chosen username and password
-docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \
-  --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
-  --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"
+docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container \
+  -e USERNAME="${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+  -e PASSWORD="${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" \
+  documentdb
 ```
 
 > **Note:** The prompts export the credentials for the `mongosh` command below. The guards reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. If you open a new shell, set both environment variables again.
 >
+> **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
+>
 > **Network note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
 >
 > **Port note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
@@ -62,7 +64,7 @@ DocumentDB Local accepts TLS connections on the gateway port and requires authen
 ```bash
 mongosh localhost:10260 \
   -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
+  -p \
   --authenticationMechanism SCRAM-SHA-256 \
   --tls --tlsAllowInvalidCertificates
 ```
@@ -283,6 +285,8 @@ 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.
 
+> **Known issue:** in 1.0, the admin user that the container or the setup wizard creates can't run `createUser` or `createRole`; both fail with `User is not authorized to perform this action` ([#752](https://github.com/documentdb/documentdb/issues/752)). See the [1.0 known issues](release-notes-1.0.md#known-issues).
+
 ```javascript
 // Users — can be created from any database
 db.runCommand({ createUser: "alice", pwd: "secret", roles: [ { role: "readAnyDatabase", db: "admin" } ] })
diff --git a/getting-started/navigation.yml b/getting-started/navigation.yml
index 63c49d2..c0fb341 100644
--- a/getting-started/navigation.yml
+++ b/getting-started/navigation.yml
@@ -12,5 +12,5 @@
   link: mongo-shell-quickstart.md
 - title: Pre-built Packages
   link: prebuilt-packages.md
-- title: Try the 1.0 Release Candidate
-  link: release-candidate.md
+- title: 1.0 Release Notes
+  link: release-notes-1.0.md
diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md
index 2e7bd14..86dec50 100644
--- a/getting-started/nodejs-setup.md
+++ b/getting-started/nodejs-setup.md
@@ -26,15 +26,15 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance
    # Tag the image for convenience
    docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
 
-   read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
-   read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
-   printf '\n'
+   printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
+   printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
    export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
 
    # Run the container with your chosen username and password
-   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \
-     --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
-     --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"; then
+   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container \
+     -e USERNAME="${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+     -e PASSWORD="${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" \
+     documentdb; then
      docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
    fi
    ```
@@ -44,6 +44,8 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance
 >
 > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done`
 >
+> **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
+>
 > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
 >
 > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
@@ -133,8 +135,9 @@ main().catch((error) => {
 
 ## Beyond CRUD
 
-Aggregation pipelines, vector search, geospatial queries, and change streams use the
-same syntax as the MongoDB shell. See the
+Aggregation pipelines, vector search and geospatial queries use the same syntax as the
+MongoDB shell. Change streams (`watch()`) are not supported; see
+[`$changeStream`](https://documentdb.io/docs/reference/operators/aggregation/$changestream/). See the
 [Mongo Shell Quick Start](https://documentdb.io/docs/getting-started/mongo-shell-quickstart/)
 for worked examples, and the [API reference](https://documentdb.io/docs/reference/)
 for the supported operator set.
diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md
index 9a47f22..d72b187 100644
--- a/getting-started/prebuilt-packages.md
+++ b/getting-started/prebuilt-packages.md
@@ -19,7 +19,7 @@ Get first-party packages from [documentdb.io](https://documentdb.io/packages), e
 
 ## First-party packages
 
-The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/releases/tag/v0.117-0), published on **2026-09-10**. First-party CI builds and tests the full stack for:
+The current release is [`v1.0-0`](https://github.com/documentdb/documentdb/releases/tag/v1.0-0), published on **2026-10-19**. See the [1.0 release notes](release-notes-1.0.md) for what changed and the known issues. First-party CI builds and tests the full stack for:
 
 | Distribution | PostgreSQL | Architectures |
 | --- | --- | --- |
@@ -28,8 +28,6 @@ The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/rel
 
 Ubuntu 24.04 with PostgreSQL 18 is the recommended default. Other targets may be available through PGDG or the build scripts; they are not part of this hosted matrix.
 
-The 1.0 release candidate is available for testing but is not in the package repository; see [Try the 1.0 release candidate](release-candidate.md).
-
 For a clean host, the installer configures repositories, installs packages,
 and runs setup:
 
@@ -38,12 +36,12 @@ curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh &&
 sh documentdb-install.sh
 ```
 
-This installs v0.117-0 on PostgreSQL 18. Use `--pg-major 17` for PostgreSQL 17.
-The manual steps below install the same release.
+This installs the current release on PostgreSQL 18. Use `--pg-major 17` for PostgreSQL 17.
+The manual steps below install the same release. To move an existing installation to 1.0, see [Upgrading to 1.0](#upgrading-to-10) instead.
 
 ## Set up and connect
 
-These steps are for a **new stand-alone installation**. For an existing deployment, read [Upgrades and retired targets](#upgrades-and-retired-targets) first.
+These steps are for a **new stand-alone installation**. For an existing deployment, read [Upgrading to 1.0](#upgrading-to-10) first.
 
 ### 1. Install the stack
 
@@ -122,14 +120,14 @@ sudo documentdb-tune --pg-version 18 --cluster main --dry-run
 Review the proposed configuration, then apply it during a suitable restart window:
 
 ```bash
-sudo documentdb-tune --pg-version 18 --cluster main --yes
-sudo systemctl restart postgresql@18-main
+sudo documentdb-tune --pg-version 18 --cluster main --yes &&
+sudo systemctl restart postgresql@18-main &&
 sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 \
   -c "CREATE EXTENSION IF NOT EXISTS documentdb CASCADE;" \
   -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;"
 ```
 
-In v0.117, both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`.
+Both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`.
 
 For a **new** Debian/Ubuntu cluster, `sudo documentdb-createcluster 18 docdb --start` combines cluster creation, tuning, startup, and extension creation. Choose a cluster name that does not already exist.
 
@@ -175,30 +173,32 @@ No package for your target? The supplied scripts build DEB or RPM packages with
 Use a Linux build environment with Git, Docker, Bash 4+, and GNU utilities, on the target architecture. For example, build the extension for Debian 12 and PostgreSQL 18:
 
 ```bash
-git clone --depth 1 --branch v0.117-0 https://github.com/documentdb/documentdb.git
+git clone --depth 1 --branch v1.0-0 https://github.com/documentdb/documentdb.git
 cd documentdb
-./packaging/build_packages.sh --os deb12 --pg 18 --output-dir packages
+./packaging/build_packages.sh --os deb12 --pg 18 --version 1.0.0 --output-dir packages
 ```
 
+Pass `--version 1.0.0` explicitly. The `v1.0-0` tag shares its commit with `v1.0-RC2`, and without `--version` the build takes its version from the tag `git describe` picks, which can be the release candidate.
+
 For the full stand-alone DEB set, make `dpkg-deb` available on the build host, then build the gateway and shared packages:
 
 ```bash
 ./packaging/gateway/build_gateway_packages.sh --os deb12 --pg 18 \
-  --version 0.117.0 --output-dir packages
+  --version 1.0.0 --output-dir packages
 ./packaging/build_extra_packages.sh --type deb --pg 18 \
-  --version 0.117.0 --output-dir packages
+  --version 1.0.0 --output-dir packages
 ```
 
-Outputs go into `packages/`. RPM extras instead require host `rpmbuild` and applicable RPM macros. The [versioned packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md) lists targets, prerequisites, and clean-install checks.
+Outputs go into `packages/`. RPM extras instead require host `rpmbuild` and applicable RPM macros. The [versioned packaging guide](https://github.com/documentdb/documentdb/blob/v1.0-0/packaging/README.md) lists targets, prerequisites, and clean-install checks.
 
 Validate builds for targets outside the first-party CI matrix in your environment. PostgreSQL 15 is extension-only; package-managed gateway setup requires PostgreSQL 16 or newer.
 
 ## Download and verify
 
-Use release assets when you need an exact first-party version rather than a repository install. `v0.117-0` includes 22 Linux packages, `SHA256SUMS`, and `manifest.txt`.
+Use release assets when you need an exact first-party version rather than a repository install. Each release publishes its Linux packages with `SHA256SUMS` and `manifest.txt`.
 
 ```bash
-gh release download v0.117-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS
+gh release download v1.0-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS
 ```
 
 This downloads all formats, architectures, and PostgreSQL major versions. Install only the matching subset below, not every downloaded file.
@@ -214,11 +214,11 @@ These examples install `documentdb-18` and its dependencies; the optional `docum
 For arm64, replace `amd64` with `arm64`. Only the gateway and extension files are architecture-specific.
 
 ```bash
-sudo apt install ./ubuntu24.04-documentdb-18_0.117.0_all.deb \
-                 ./ubuntu24.04-documentdb-common_0.117.0_all.deb \
-                 ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \
-                 ./ubuntu24.04-documentdb-gateway_0.117.0_amd64.deb \
-                 ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb
+sudo apt install ./ubuntu24.04-documentdb-18_1.0.0_all.deb \
+                 ./ubuntu24.04-documentdb-common_1.0.0_all.deb \
+                 ./ubuntu24.04-documentdb-postgresql-tools_1.0.0_all.deb \
+                 ./ubuntu24.04-documentdb-gateway_1.0.0_amd64.deb \
+                 ./ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb
 ```
 
 ### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64)
@@ -226,26 +226,100 @@ sudo apt install ./ubuntu24.04-documentdb-18_0.117.0_all.deb \
 For arm64, replace `x86_64` with `aarch64`; leave `noarch` files unchanged.
 
 ```bash
-sudo dnf install ./documentdb-18-0.117.0-1.noarch.rpm \
-                 ./documentdb-common-0.117.0-1.noarch.rpm \
-                 ./documentdb-postgresql-tools-0.117.0-1.noarch.rpm \
-                 ./documentdb-gateway-0.117.0-1.el9.x86_64.rpm \
-                 ./rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm
+sudo dnf install ./documentdb-18-1.0.0-1.noarch.rpm \
+                 ./documentdb-common-1.0.0-1.noarch.rpm \
+                 ./documentdb-postgresql-tools-1.0.0-1.noarch.rpm \
+                 ./documentdb-gateway-1.0.0-1.el9.x86_64.rpm \
+                 ./rhel9-postgresql18-documentdb-1.0.0-1.el9.x86_64.rpm
 ```
 
 For PostgreSQL 17, replace the two PostgreSQL-specific files with their `17` equivalents; the shared packages stay the same. The `documentdb` meta package always selects PG18.
 
 For extension-only use, install the extension and tools files, then [configure PostgreSQL](#extension-only-installation). For a full stack, [run the wizard](#2-run-the-setup-wizard) with the installed major: use `--pg-version 17` for PG17.
 
-Filename prefixes such as `ubuntu24.04-` and `rhel9-` identify release assets, not package names. DEB extensions use version `0.117-0`, while other packages use `0.117.0`; RPMs use `0.117.0` with release `1` or `1.el9`.
+Filename prefixes such as `ubuntu24.04-` and `rhel9-` identify release assets, not package names. DEB extensions use version `1.0-0`, while other packages use `1.0.0`; RPMs use `1.0.0` with release `1` or `1.el9`.
 
 ### Offline / air-gapped
 
 Release assets do not include the full dependency set. Stage PostgreSQL, its required extensions, and all other dependencies on a connected machine of the **same distro, release, and architecture**. Include dependencies already installed on the staging machine. Follow [Offline / air-gapped install](https://documentdb.io/docs/linux-packages/offline/) to serve the bundle as a local repository.
 
-## Upgrades and retired targets
+## Upgrading to 1.0
+
+A 0.116 or 0.117 package installation can be upgraded in place; move the whole stack together. Upgrading the packages replaces the libraries and installs the upgrade scripts, but doesn't change the databases: each PostgreSQL instance keeps reporting the old extension version until its extensions are updated. Back up first; there is no downgrade.
+
+Upgrading a host that ever ran a release candidate isn't supported, and the installer refuses it. Install 1.0 on a fresh host and move the data with `mongodump` and `mongorestore`. Removing packages keeps the PostgreSQL data; don't reset or reuse an adopted instance as an upgrade workaround.
+
+### Stand-alone stack
+
+Stop the gateway so no client reaches the new libraries before the extensions are updated, upgrade the packages, restart PostgreSQL so it loads the new libraries, then re-run the setup wizard with the options you installed with. The wizard updates the extensions and then starts the gateway:
+
+```bash
+# Debian / Ubuntu
+sudo systemctl stop documentdb-gateway-local@18.service &&
+sudo apt update && sudo apt install --only-upgrade documentdb-18 postgresql-18-documentdb \
+  documentdb-common documentdb-gateway documentdb-postgresql-tools &&
+sudo systemctl restart documentdb-postgresql@18.service &&
+sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin
+
+# RHEL-compatible 9
+sudo systemctl stop documentdb-gateway-local@18.service &&
+sudo dnf upgrade documentdb-18 postgresql18-documentdb \
+  documentdb-common documentdb-gateway documentdb-postgresql-tools &&
+sudo systemctl restart documentdb-postgresql@18.service &&
+sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin
+```
+
+These commands assume the DocumentDB package repository, which carries 1.0 from the release date. If you installed from release assets, download the 1.0 assets and install the same set of files [the same way](#install-from-downloaded-assets) in place of the `apt`/`dnf` command, keeping the `&&` so the restart and setup run only if the install succeeds. The gateway stays stopped until the wizard finishes; if the wizard stops early, run it again. The shared packages (`documentdb-common`, `documentdb-gateway`, `documentdb-postgresql-tools`) serve every PostgreSQL major on the host, so if more than one major is installed, stop each major's gateway first, then upgrade and re-run setup for each of them.
+
+On a configured instance the wizard is a day-2 re-run: it keeps the gateway port and TLS settings and runs `ALTER EXTENSION ... UPDATE` for each DocumentDB extension. It also asks for the admin password and, after a warning and a confirmation, sets it on the existing admin user: enter the current password to keep it, because any other value replaces it and the old one stops working. For PostgreSQL 17, use `17` throughout. If pressing Enter at the password prompt aborts the wizard, run it again and type the password ([#772](https://github.com/documentdb/documentdb/issues/772)).
+
+### Extension and gateway on your own PostgreSQL
+
+If you adopted the instance with `documentdb-setup --target-postgres-instance 18/main`, the wizard never restarts PostgreSQL for you. Stop the gateway (`sudo systemctl stop documentdb-gateway-local@18.service`), upgrade the packages, restart PostgreSQL yourself (`sudo systemctl restart postgresql@18-main` on Ubuntu, `sudo systemctl restart postgresql-18` on EL9), then re-run the same `documentdb-setup --pg-version 18 --target-postgres-instance 18/main --admin-user admin` command; it warns about the admin password as above, updates the extensions and then starts the gateway. If the wizard has to change `shared_preload_libraries`, it writes the change, asks you to restart PostgreSQL, and exits without updating the extensions: restart and run it once more.
+
+Otherwise, stop the gateway and upgrade the packages first. On Ubuntu with a cluster named `main`:
+
+```bash
+sudo systemctl stop documentdb-gateway &&
+sudo apt update && sudo apt install --only-upgrade postgresql-18-documentdb \
+  documentdb-postgresql-tools documentdb-gateway
+sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -Atc "SHOW shared_preload_libraries;"
+```
+
+1.0 loads the extended RUM library only from `shared_preload_libraries`; `CREATE EXTENSION documentdb_extended_rum` fails with `pg_documentdb_extended_rum can only be loaded via shared_preload_libraries` otherwise. If `pg_documentdb_extended_rum` isn't in the list (it may be missing on a 0.116 installation), add it with `documentdb-tune`, reviewing the dry run first:
+
+```bash
+sudo documentdb-tune --pg-version 18 --cluster main --dry-run
+sudo documentdb-tune --pg-version 18 --cluster main --yes
+```
+
+Then restart PostgreSQL so it loads the new libraries, and update the extensions in every database where you created them, in this order, because `ALTER EXTENSION` doesn't update dependencies. `-1` runs the statements as one transaction, so a failure leaves every extension at its old version, and the gateway starts again only on success. The transaction doesn't detect a missing preload, though: when `documentdb_extended_rum` already exists, the statements succeed without it and index builds fail later with `The index access method extended_rum could not be located`. That is why the preload check above comes first:
+
+```bash
+sudo systemctl restart postgresql@18-main &&
+sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -1 -v ON_ERROR_STOP=1 \
+  -c "ALTER EXTENSION documentdb_core UPDATE;" \
+  -c "ALTER EXTENSION documentdb UPDATE;" \
+  -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" \
+  -c "ALTER EXTENSION documentdb_extended_rum UPDATE;" &&
+sudo systemctl start documentdb-gateway
+```
+
+### Check the version
+
+Connect with `mongosh` and run:
+
+```javascript
+db.hello().internal.documentdb_versions
+```
+
+It should print `[ '1.0-0', '1.0.0' ]`: the installed extension version, then the loaded library version. If the first value is still `0.116-0` or `0.117-0`, the extensions weren't updated. See [`hello`](https://documentdb.io/docs/reference/commands/diagnostic/hello/).
+
+### Containers
+
+A newer DocumentDB Local image on an existing data volume does not update the extensions ([#773](https://github.com/documentdb/documentdb/issues/773)). Start 1.0 on a new volume and move the data with `mongodump` and `mongorestore`. See [Upgrading the image](../documentdb-local/index.md#upgrading-the-image).
 
-**Pre-GA:** in-place package upgrades from earlier releases are not supported yet. Use a clean host or a new, empty PostgreSQL instance and plan data migration separately. Removing packages preserves PostgreSQL data; do not reset or reuse an adopted instance as an upgrade workaround.
+## Retired targets
 
 The hosted matrix excludes PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-compatible 8. Since v0.116, older packages for retired targets are not carried forward, including PG16 extensions formerly hosted for Ubuntu 24.04 and EL9. Existing installations keep running, but cannot update or reinstall those packages from documentdb.io.
 
@@ -265,4 +339,4 @@ sudo dnf clean all
 
 ## Container image
 
-For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release v0.117 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version.
+For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release 1.0 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version.
diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md
index d8b8b1b..a55113e 100644
--- a/getting-started/python-setup.md
+++ b/getting-started/python-setup.md
@@ -37,15 +37,15 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py
    # Tag the image for convenience
    docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
 
-   read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
-   read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
-   printf '\n'
+   printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
+   printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
    export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
 
    # Run the container with your chosen username and password
-   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb \
-     --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
-     --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"; then
+   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container \
+     -e USERNAME="${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
+     -e PASSWORD="${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" \
+     documentdb; then
      docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
    fi
    ```
@@ -54,6 +54,8 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py
    >
    > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done`
    > 
+   > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
+   >
    > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
    >
    > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
@@ -225,7 +227,7 @@ The code reads the same `DOCUMENTDB_USERNAME` and `DOCUMENTDB_PASSWORD` values e
 
    ```python
    db.command({
-       'createIndexes': 'your_collection',
+       'createIndexes': 'sample_collection',
        'indexes': [
            {
                'name': 'embeddings_idx',
diff --git a/getting-started/release-candidate.md b/getting-started/release-candidate.md
index 1472dcb..296700e 100644
--- a/getting-started/release-candidate.md
+++ b/getting-started/release-candidate.md
@@ -1,160 +1,10 @@
 ---
-title: Try the 1.0 Release Candidate
-description: Try DocumentDB 1.0 RC2 from release assets or container images. For testing only, with no upgrade path and no fixes to RC2. No date for 1.0 yet.
+title: 1.0 Release Candidates
+description: The DocumentDB 1.0 release candidates have ended. DocumentDB 1.0 is released; upgrading hosts and volumes that ran a release candidate isn't supported.
 ---
 
-# Try the 1.0 release candidate
+# 1.0 release candidates
 
-[DocumentDB v1.0-RC2](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) is a preview of 1.0 for testing. Try your applications and workloads against it and [report what breaks](#report-issues) before 1.0 ships.
+The 1.0 release candidates have ended: [DocumentDB 1.0](release-notes-1.0.md) was released on 2026-10-19, from the same commit as v1.0-RC2.
 
-There is no date for 1.0 yet. A release candidate is meant to be close to what 1.0 ships, apart from fixes found during testing; 1.0 follows once the release candidates stop turning up blocking issues. The upgrade and support policy from 1.0 onward will be published with the final release.
-
-> **For testing only.** Don't use a release candidate for production or for data you need to keep.
->
-> - **No upgrade path.** Upgrades from 0.117 to an RC, between release candidates, and from an RC to 1.0 are not supported. Start from an empty instance or volume, and expect to discard it.
-> - **No fixes to RC2.** Fixes go into the next release candidate or 1.0, not into RC2.
-> - **Not the default.** GitHub marks the RC as a pre-release. The package repository, the container `latest` tag and GitHub's latest release stay on the current stable release, v0.117-0. You only get the RC by asking for it explicitly, as shown below.
-
-## Changes since RC1
-
-- **Usage telemetry in the container image.** The RC2 image sends anonymous usage data by default; native packages send nothing. See [Container image](#container-image).
-- **Gateway v2 runtime.** The gateway now runs on its v2 runtime by default.
-- **Init script errors stop startup.** RC1's known issue is fixed: an error in an `--init-data-path` script now stops the container with an error. The run isn't retried on restart, so fix the script and start from a new volume.
-- **Permission fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection, and `$merge` and `$out` now need insert or update permission on the target collection, not just read.
-
-The [changelog](https://github.com/documentdb/documentdb/blob/v1.0-RC2/CHANGELOG.md) lists every change. There is no upgrade from RC1: if you tested RC1, start RC2 on a fresh host or a new volume.
-
-## Container image
-
-The RC images are tagged `pg15-1.0-rc2`, `pg16-1.0-rc2`, `pg17-1.0-rc2` and `pg18-1.0-rc2`, for Linux amd64 and arm64. Include the container's `Release Version` log line when you [report issues](#report-issues). Use a new volume, not one a 0.117 or RC1 container has used:
-
-```bash
-docker run -dt -p 127.0.0.1:10260:10260 -v documentdb-rc2-data:/data --name docdb-rc2 \
-  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
-  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
-  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0-rc2
-```
-
-Everything else in [DocumentDB Local](../documentdb-local/index.md) applies, with these differences:
-
-- **Usage telemetry is on by default.** At startup and then hourly, the image reports its version, platform and CPU architecture to Scarf, and nothing about your data, queries or credentials. Turn it off with `-e DOCUMENTDB_USAGE_TELEMETRY=false`, `-e NO_ANALYTICS=1` or `-e DO_NOT_TRACK=1`, or pass `--disable-usage-telemetry` after the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
-- **Health check.** The first health check runs about 30 seconds after start. Wait until `docker inspect -f '{{.State.Health.Status}}' docdb-rc2` reports `healthy`.
-- **Stale `postmaster.pid`.** After `docker kill`, `docker rm -f` or a crash, the next start removes the stale file, as 0.117 did, but only when the volume's lock shows an RC2 container wrote it. Otherwise it refuses to start: re-create the container once with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then without it. Don't share a volume between hosts. As in 0.117, a second container on a volume that is already in use exits immediately.
-- **PostgreSQL loss stops the container.** If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (`DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT`).
-- **`--disable-extended-rum` is ignored**, apart from a deprecation warning.
-- **`--toast-compression lz4|pglz|default`** is new and defaults to `lz4`.
-
-To remove the test instance and its data:
-
-```bash
-docker stop docdb-rc2 && docker rm docdb-rc2 && docker volume rm documentdb-rc2-data
-```
-
-## Linux packages
-
-The RC is not in the package repository. Use a clean, disposable Ubuntu 24.04 or RHEL-compatible 9 host that has never had DocumentDB installed and runs systemd (not WSL without systemd, a chroot or a plain container). Then run the installer with `--version`:
-
-```sh
-curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh &&
-sh documentdb-install.sh --version v1.0-RC2
-```
-
-It enables PGDG (plus EPEL and CRB on EL9), downloads this host's five RC2 packages from the [release](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2), verifies them against its `SHA256SUMS` and runs the setup wizard. It doesn't add the DocumentDB package repository, so the host never picks up a stable release by accident. PostgreSQL 18 is the default; add `--pg-major 17` for 17, or `--dry-run` to see the plan first. Without `--version`, the same installer sets up v0.117-0.
-
-After an RC run, the installer refuses that host, even in stable mode or for a later RC, so an RC1 host can't take RC2. Use a fresh host for anything else.
-
-To check what you got, run `dpkg-query -W 'documentdb*' '*-documentdb'` or `rpm -qa '*documentdb*'`. RC2 packages are version `1.0~rc2`, `documentdb-gateway --version` prints `1.0.0-rc2`, and the extension version is `1.0-0`.
-
-### Manual installation
-
-Enable PGDG first, but not the DocumentDB package repository. On Ubuntu 24.04:
-
-```bash
-sudo apt update &&
-sudo apt install -y postgresql-common gnupg &&
-sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
-```
-
-On RHEL-compatible 9, also enable EPEL and CRB. Enable CRB on Rocky Linux, AlmaLinux or CentOS Stream 9:
-
-```bash
-sudo dnf install -y dnf-plugins-core &&
-sudo dnf config-manager --set-enabled crb
-```
-
-Or on RHEL 9:
-
-```bash
-sudo subscription-manager repos --enable "codeready-builder-for-rhel-9-$(arch)-rpms"
-```
-
-Then enable EPEL and PGDG:
-
-```bash
-sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm &&
-sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm &&
-sudo dnf -qy module disable postgresql
-```
-
-Download and verify the release files:
-
-```bash
-base=https://github.com/documentdb/documentdb/releases/download/v1.0-RC2
-mkdir pkgs-rc2 && cd pkgs-rc2 &&
-curl -fsSLO "$base/SHA256SUMS" &&
-awk '{print $2}' SHA256SUMS | xargs -I{} curl -fsSLO "$base/{}" &&
-sha256sum -c SHA256SUMS
-```
-
-Continue only if every file reports `OK`. The install commands below check again and stop on any mismatch.
-
-Install the five packages for PostgreSQL 18. On Ubuntu 24.04:
-
-```bash
-arch=$(dpkg --print-architecture)
-sha256sum -c --quiet SHA256SUMS &&
-sudo apt install -y ./ubuntu24.04-documentdb-{18,common,postgresql-tools}_*_all.deb \
-                    ./ubuntu24.04-documentdb-gateway_*_"$arch".deb \
-                    ./ubuntu24.04-postgresql-18-documentdb_*_"$arch".deb
-```
-
-On RHEL-compatible 9:
-
-```bash
-sha256sum -c --quiet SHA256SUMS &&
-sudo dnf install -y ./documentdb-{18,common,postgresql-tools}-[0-9]*.noarch.rpm \
-                    ./documentdb-gateway-*.el9.$(uname -m).rpm \
-                    ./rhel9-postgresql18-documentdb-*.el9.$(uname -m).rpm
-```
-
-For PostgreSQL 17, replace `18` with `17` in the first and last package names, and in `--pg-version` below.
-
-The setup wizard binds the gateway on all interfaces on port 10260, with a self-signed TLS certificate. On a host reachable from other networks, block port 10260 with the host firewall first. Then run the wizard:
-
-```bash
-sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin
-```
-
-The wizard now sets `default_toast_compression = 'lz4'`. To keep another setting, run the wizard directly and pass it through `sudo`, for example `sudo DOCUMENTDB_TOAST_COMPRESSION=pglz documentdb-setup ...`; `default` leaves PostgreSQL's own setting alone. The installer doesn't forward this variable.
-
-To remove the RC, uninstall its packages and discard the host or its data directories. Don't reuse them for a stable installation.
-
-## Known issues
-
-- **`distinct` or `count` on a grouped view can crash the server.** `distinct` on a view whose pipeline ends in `$group`, or `count` with a query on such a view, crashes the PostgreSQL backend. PostgreSQL restarts and disconnects every other session.
-- **An expensive `$replaceAll` can outlive `maxTimeMS`.** A very costly `$replaceAll` on a large string can keep running after `maxTimeMS` expires and can't be cancelled.
-- **`updateOne` can miss a match.** With a filter on a field other than `_id`, `updateOne` can report no match when PostgreSQL runs the statement with a generic plan. This is rare with default settings. Setting `plan_cache_mode = force_custom_plan` in the PostgreSQL configuration avoids it.
-- **The setup admin can't create or drop users.** The admin user created at setup can't run `createUser` or `dropUser` over the MongoDB protocol. On a package install, manage users on the host instead:
-
-  ```bash
-  sudo documentdb-gateway-admin create-user --username app --password-file app.pw \
-    --roles '[{"role":"readAnyDatabase","db":"admin"}]'
-  sudo documentdb-gateway-admin drop-user --username app
-  ```
-
-- **Container options.** `--log-level` and `--enable-telemetry` have no effect, and a `--data-path` that contains a space fails.
-- **Collation is off by default.** `find`, `aggregate` and `count` with a `collation` fail as unsupported unless `documentdb_core.enableCollation` is on.
-
-## Report issues
-
-Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) and include `v1.0-RC2`, your PostgreSQL major version, and either the package versions or the `Release Version` line from `docker logs docdb-rc2`, which names the build commit. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v1.0-RC2) list what changed since 0.117.
+Upgrading hosts and data volumes that ran a release candidate to 1.0 isn't supported, and the installer refuses such hosts. Install 1.0 on a fresh host or a new volume, following [Pre-built Packages](prebuilt-packages.md) or [DocumentDB Local](../documentdb-local/index.md), and move any data you need with `mongodump` and `mongorestore`.
diff --git a/getting-started/release-notes-1.0.md b/getting-started/release-notes-1.0.md
new file mode 100644
index 0000000..7fa9d41
--- /dev/null
+++ b/getting-started/release-notes-1.0.md
@@ -0,0 +1,68 @@
+---
+title: DocumentDB 1.0 Release Notes
+description: What's new in DocumentDB 1.0, where to get it, how to upgrade from 0.117, and the known issues that ship with it.
+---
+
+# DocumentDB 1.0 release notes
+
+[DocumentDB v1.0-0](https://github.com/documentdb/documentdb/releases/tag/v1.0-0) was released on **2026-10-19**. It is built from the same commit as the second release candidate, v1.0-RC2. The [changelog](https://github.com/documentdb/documentdb/blob/v1.0-0/CHANGELOG.md) lists the engine changes.
+
+## Where to get it
+
+| Channel | 1.0 version | Platforms |
+| --- | --- | --- |
+| [Linux packages](prebuilt-packages.md) | packages `1.0.0`, extension `1.0-0` | Ubuntu 24.04 and RHEL-compatible 9, PostgreSQL 17 and 18, amd64 and arm64 |
+| [Container image](../documentdb-local/index.md) | `pg15-1.0.0` to `pg18-1.0.0`; `latest` is `pg17-1.0.0` | Linux amd64 and arm64 |
+| [Kubernetes operator](../kubernetes-operator/index.md) | operator `1.0.0`, which runs engine `1.0-0` | Kubernetes 1.33+ with the `ImageVolume` feature gate on (on by default from 1.35, GA in 1.36) |
+
+The SQL extension version is `1.0-0` everywhere, and `hello` reports it in `internal.documentdb_versions`.
+
+## What's new since 0.117
+
+- **Usage telemetry in the container image.** The `documentdb-local` image reports its version, platform and CPU architecture to Scarf at startup and hourly, on by default. Native packages send nothing. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry) to turn it off.
+- **Security fixes.** `find` and `aggregate` with `batchSize: 0` now check that the caller can read the collection. `$merge` and `$out` now need insert or update permission on the target collection, not just read. `createUser` and `updateUser` reject passwords that fail SASLprep.
+- **Collation** now works with `count` and the `$stdDevPop`, `$stdDevSamp`, `$median` and `$percentile` accumulators, and applies to the symbol type. Collation is still off by default; see [Known issues](#known-issues).
+- **Custom roles.** With `documentdb.enableRoleCrud` on (off by default), `createRole` and `dropRole` keep custom roles in a roles catalog. `updateRole` is still unsupported.
+- **`compact`** reports `bytesFreed` as the measured change in on-disk size.
+- **Gateway.** The gateway runs on its new v2 runtime by default. It now returns retryable or specific error codes for backend connection and pool failures instead of `InternalError`, and exits with an error instead of panicking when PostgreSQL is unreachable at startup.
+- **Crash and correctness fixes**, including `$getField`/`$setField`/`$unsetField` on system variables, `$firstN`/`$lastN` without a sort, `$documents` inside `$facet`, `$near`/`$geoNear` ordering on `2dsphere` indexes, overlapping `dropIndexes` deadlocks, and several RUM index scan and vacuum fixes.
+- **Container behavior.** An error in an `--init-data-path` script now stops the container. A stale `postmaster.pid` is removed on the next start only when the volume's lock shows a 1.0 container wrote it; otherwise the container refuses to start. The container exits if PostgreSQL inside it stops. TOAST compression defaults to `lz4`, and `--disable-extended-rum` is deprecated and ignored. See [Container lifecycle](../documentdb-local/index.md#container-lifecycle).
+- **Packages.** The setup wizard sets `default_toast_compression = 'lz4'`; pass `DOCUMENTDB_TOAST_COMPRESSION=pglz` or `default` through `sudo` to keep another setting.
+
+## Upgrading
+
+- **Packages:** 0.116 and 0.117 installations can be upgraded in place: upgrade the packages, restart PostgreSQL so it loads the new libraries, then update the extensions. See [Upgrading](https://documentdb.io/docs/linux-packages#upgrading).
+- **Containers:** a 1.0 image on an existing volume doesn't update the extensions. Move the data to a new volume with `mongodump` and `mongorestore`. See [Upgrading the image](../documentdb-local/index.md#upgrading-the-image).
+- **Release candidates:** upgrading hosts and volumes that ran an RC isn't supported. Start 1.0 on a fresh host or a new volume.
+
+## Known issues
+
+- **The setup admin can't create or drop users or roles** ([#752](https://github.com/documentdb/documentdb/issues/752)). `createUser`, and `createRole` with `documentdb.enableRoleCrud` on, fail with `User is not authorized to perform this action` when run as the admin user created at setup or by the container. On a package install, manage users on the host instead:
+
+  ```bash
+  printf 'Password for app: '; IFS= read -r -s APP_PASSWORD; echo
+  printf '%s' "$APP_PASSWORD" | sudo documentdb-gateway-admin create-user --username app \
+    --password-stdin --roles '[{"role":"readAnyDatabase","db":"admin"}]'
+  sudo documentdb-gateway-admin drop-user --username app
+  ```
+
+- **`distinct` or `count` on a grouped view can crash the server.** `distinct` on a view whose pipeline ends in `$group` with an accumulator such as `$sum`, or `count` with a query on such a view, crashes the PostgreSQL backend. PostgreSQL restarts and disconnects every other session.
+- **A newer container image doesn't upgrade an existing volume** ([#773](https://github.com/documentdb/documentdb/issues/773)). The image never runs `ALTER EXTENSION ... UPDATE`, and a changed `--password` on an existing volume is ignored.
+- **A 1.0 container can refuse a volume an older container used.** If the volume still has an older container's `postmaster.pid`, the 1.0 image reports that it exists and refuses to start. Stop the old container first: for 0.116 and 0.117, `docker stop` removes the file. Images 0.114 and earlier don't normally stop PostgreSQL cleanly and usually leave it behind. Once nothing else uses the volume, re-create the container with `-e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true`, then re-create it again without the variable, because it skips the in-use check on every start.
+- **A single-document update can miss a match.** An update with `multi: false`, or a `findAndModify`, whose filter uses fields other than `_id` can report no match when PostgreSQL runs it with a generic plan; with `upsert` it then inserts a duplicate. This is rare with default settings; setting `plan_cache_mode = force_custom_plan` in the PostgreSQL configuration avoids it.
+- **An expensive `$replaceAll` or `$regexFindAll` can outlive `maxTimeMS`.** A very costly call on a large string can keep running after `maxTimeMS` expires and can't be cancelled.
+- **A write can be applied twice** ([#767](https://github.com/documentdb/documentdb/issues/767)). If the backend connection is lost after a write commits but before the reply, the gateway retries it, so a non-idempotent update such as `$inc` can be applied twice even with `retryWrites=false`.
+- **`$lookup` can fail on a collection with a wildcard index** ([#769](https://github.com/documentdb/documentdb/issues/769)), with `Unrecognized BSON data type code 0`.
+- **Collation is off by default.** `find`, `aggregate`, `count` and `delete` with a `collation` fail as unsupported unless `documentdb_core.enableCollation` is on. `distinct`, `findAndModify` and `update` don't support `collation` at all.
+- **Container options that do nothing.** `--log-level` and `--enable-telemetry` are validated but have no effect, and a `--data-path` that contains a space fails.
+- **Open packaging and container issues:**
+  - [#771](https://github.com/documentdb/documentdb/issues/771): package remove, purge, upgrade and rerun paths that can leave the stack down or stuck.
+  - [#759](https://github.com/documentdb/documentdb/issues/759): container init, runtime and quick-start gaps.
+  - [#758](https://github.com/documentdb/documentdb/issues/758): container settings that aren't secure by default.
+  - [#735](https://github.com/documentdb/documentdb/issues/735): gateway state ownership isn't preserved across an RPM erase and reinstall.
+  - [#685](https://github.com/documentdb/documentdb/issues/685): a `--password` argument is readable in the container's process list; pass `-e PASSWORD` instead.
+  - [#389](https://github.com/documentdb/documentdb/issues/389): the Debian packages lack a copyright file.
+
+## Report issues
+
+Open an issue in [documentdb/documentdb](https://github.com/documentdb/documentdb/issues) with your DocumentDB and PostgreSQL versions, and either the package versions or the `Release Version` line from `docker logs`.
diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md
index 454cde9..26450f1 100644
--- a/getting-started/vscode-quickstart.md
+++ b/getting-started/vscode-quickstart.md
@@ -44,6 +44,8 @@ This is the fastest way to get a database running. The wizard handles the contai
 
    The defaults give you an available port (starting at `10260`), generated credentials, the `latest` official image, and optional sample data. Expand the advanced options to set the port, the image tag, or the credentials yourself, or to skip the sample data.
 
+   > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. Extension 1.0.0 and later turn it off for a container it creates if VS Code telemetry is disabled at that moment; to turn it off yourself, start the container as shown under the alternative below. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
+
 4. Wait for setup to finish. The extension pulls the image if needed, creates a container named `vscode-documentdb-local` with a persistent volume, starts it, and waits until the database accepts connections.
 
 5. Select **Open Connection** to reveal the saved connection in the Connections view, then expand it to browse databases and collections.
@@ -65,11 +67,10 @@ Use this if you already run DocumentDB Local outside VS Code, or you want to man
    ```bash
    docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
    docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb
-   read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
-   read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
-   printf '\n'
+   printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
+   printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
    export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD
-   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"; then
+   if docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container -e USERNAME="${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" -e PASSWORD="${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" documentdb; then
      docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest || echo "No existing documentdb image to remove"
    fi
    ```
@@ -85,7 +86,7 @@ Use this if you already run DocumentDB Local outside VS Code, or you want to man
    if ([string]::IsNullOrWhiteSpace($env:DOCUMENTDB_USERNAME) -or [string]::IsNullOrWhiteSpace($env:DOCUMENTDB_PASSWORD)) {
        throw 'DocumentDB credentials cannot be empty'
    } else {
-       docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container documentdb --username "$env:DOCUMENTDB_USERNAME" --password "$env:DOCUMENTDB_PASSWORD"
+       docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container -e "USERNAME=$env:DOCUMENTDB_USERNAME" -e "PASSWORD=$env:DOCUMENTDB_PASSWORD" documentdb
        if ($LASTEXITCODE -eq 0) {
            docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest
            if ($LASTEXITCODE -ne 0) { echo "No existing documentdb image to remove" }
@@ -97,6 +98,8 @@ Use this if you already run DocumentDB Local outside VS Code, or you want to man
    >
    > **Note:** Both versions prompt for credentials and reject empty values so the container cannot fall through to the public `default_user` / `Admin100` defaults. Enter the same values when the extension asks for the local connection credentials.
    >
+   > **Telemetry note:** The 1.0 image sends usage data (its version, platform and CPU architecture) by default. To turn it off, add `-e DOCUMENTDB_USAGE_TELEMETRY=false` before the image name. See [Usage telemetry](../documentdb-local/index.md#usage-telemetry).
+   >
    > **Network Note:** The example binds the gateway only to the local host. Expose it to other machines only after adding firewall rules and a certificate those clients can validate.
    >
    > **Port Note:** To use host port `27017` while leaving the gateway on its default container port, publish `-p 127.0.0.1:27017:10260` and enter `27017` in the extension. To change the gateway's internal port too, add `--documentdb-port 27017` after the image name and publish that container port.
diff --git a/kubernetes-operator/index.md b/kubernetes-operator/index.md
index f776bcd..549b1d7 100644
--- a/kubernetes-operator/index.md
+++ b/kubernetes-operator/index.md
@@ -9,19 +9,31 @@ The [DocumentDB Kubernetes Operator](https://github.com/documentdb/documentdb-ku
 
 The operator is a separate project, with its own repository, release cadence, and documentation. This page covers when to reach for it and what your cluster needs; the operator's own documentation covers everything else.
 
+## Versions
+
+Operator **1.0.0** runs DocumentDB engine **1.0-0**. Pin the chart version for repeatable installs (cert-manager must be installed first; see the quickstarts below):
+
+```bash
+helm install documentdb-operator oci://ghcr.io/documentdb/documentdb-operator \
+  --version 1.0.0 \
+  --namespace documentdb-operator \
+  --create-namespace \
+  --wait
+```
+
 ## When to use it
 
 | Option | Best for |
 |---|---|
-| [DocumentDB Local](https://documentdb.io/docs/documentdb-local/) | A single container for development, prototyping, and integration tests. |
-| [Pre-built packages](https://documentdb.io/docs/getting-started/packages/) | Adding DocumentDB to a PostgreSQL server you already run and operate yourself. |
+| [DocumentDB Local](../documentdb-local/index.md) | A single container for development, prototyping, and integration tests. |
+| [Pre-built packages](../getting-started/prebuilt-packages.md) | Adding DocumentDB to a PostgreSQL server you already run and operate yourself. |
 | Kubernetes Operator | Running DocumentDB as a replicated service, with automatic failover, rolling upgrades, backup and restore, and multi-region deployments. |
 
 ## What your cluster needs
 
 Check one thing before you plan a deployment. The operator mounts the DocumentDB extension into PostgreSQL pods using the Kubernetes [ImageVolume](https://kubernetes.io/docs/concepts/storage/volumes/#image) feature, which constrains where it can run:
 
-- **Kubernetes 1.35 or later**, where ImageVolume is generally available. On 1.33 and 1.34 the feature is beta, and works only if you enable the `ImageVolume` feature gate on the API server and the kubelets.
+- **Kubernetes 1.35 or later.** ImageVolume is GA from 1.36. In 1.35 it is beta and on by default, so check that your cluster hasn't turned the `ImageVolume` feature gate off. On 1.33 and 1.34 it is off by default, and works only if you enable the gate on the API server and the kubelets.
 - **containerd or CRI-O** as the container runtime. The Docker runtime does not support ImageVolume.
 
 If the feature is unavailable, the operator's admission webhook rejects the `DocumentDB` resource with an explanatory error rather than leaving pods stuck. Managed Kubernetes offerings vary in the versions and runtimes they expose, and local tools often need an explicit flag to select a supported runtime, so confirm both up front. [Before You Start](https://documentdb.io/documentdb-kubernetes-operator/latest/preview/getting-started/before-you-start/) has the full prerequisite list, including supported tooling versions and resource sizing.
diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md
index afac91a..8b04b8a 100644
--- a/postgres-api/configuration.md
+++ b/postgres-api/configuration.md
@@ -1,11 +1,11 @@
 ---
 title: Configuration
-description: Server GUCs and gateway environment variables for configuring DocumentDB, including the RUM library default introduced in v0.117-0.
+description: Server GUCs and gateway environment variables for configuring DocumentDB 1.0, including the required extended RUM index library, collation, and role management flags.
 ---
 
 # Configuration
 
-DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `postgresql.conf`) and the gateway process (via environment variables or a JSON config file). This page covers the most commonly adjusted settings, including the RUM library default introduced in **v0.117-0**.
+DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `postgresql.conf`) and the gateway process (via environment variables or a JSON config file). This page covers the most commonly adjusted settings in DocumentDB 1.0.
 
 ## Extension GUCs
 
@@ -15,28 +15,38 @@ DocumentDB is configured at two layers: the PostgreSQL extension (via GUCs in `p
 
 | GUC | Default | Description |
 | --- | --- | --- |
-| `documentdb.enableSchemaValidation` | `on` (since v0.114-0) | Enforces collection `$jsonSchema` validators on write operations. When `off`, a collection's validator is stored but not enforced. |
+| `documentdb.enableSchemaValidation` | `on` | Enforces collection `$jsonSchema` validators on write operations. When `off`, a collection's validator is stored but not enforced. |
 
-Collections with a `validator` are enforced on `insert`, `update`, `findAndModify`, and aggregation output stages (`$merge`, `$out`) when the collection's `validationLevel` is not `off` and its `validationAction` is `error`. (A `validationAction` of `warn` is not rejected on the write path, and a write that sets `bypassDocumentValidation` skips enforcement — see `documentdb.enableBypassDocumentValidation`.) Prior to v0.114-0 enforcement was opt-in; it is now enabled by default.
+Collections with a `validator` are enforced on `insert`, `update`, `findAndModify`, and aggregation output stages (`$merge`, `$out`) when the collection's `validationLevel` is not `off` and its `validationAction` is `error`. (A `validationAction` of `warn` is not rejected on the write path, and a write that sets `bypassDocumentValidation` skips enforcement — see `documentdb.enableBypassDocumentValidation`.)
 
 ### RUM index library
 
 | GUC | Default | Description |
 | --- | --- | --- |
-| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` (since v0.117-0) | Requires the DocumentDB extended RUM library on every supported PostgreSQL major version, not only PG18. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. |
+| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` | Requires the DocumentDB extended RUM library (`pg_documentdb_extended_rum`) on every supported PostgreSQL major version. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. |
 
 The package setup wizard and container startup handle the required extension setup. For a manually configured PostgreSQL instance, create both `documentdb` and `documentdb_extended_rum`; `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. Follow the [package setup guidance](https://documentdb.io/docs/getting-started/packages/) before creating indexes.
 
-Setting the option to `none` opts out of the library-load requirement.
+Leave this at the default on package and container installs: they also set `documentdb.alternate_index_handler_name = 'extended_rum'`, and with `none` index builds crash the server (and the PostgreSQL 18 image, which ships no upstream `rum` library, doesn't start). On a server you built yourself, `none` loads the upstream `rum` library instead, which must be installed. `prefer_documentdb_extended_rum` falls back to `rum` only when the extended library loads but lacks its index handler; if the library itself is missing, PostgreSQL still fails to start.
 
 ### Non-blocking unique index builds
 
 | GUC | Default | Description |
 | --- | --- | --- |
-| `documentdb.enableNonBlockingUniqueIndexBuild` | `on` (since v0.114-0) | Builds unique ordered indexes without holding a long write lock, using `CREATE INDEX CONCURRENTLY` with post-processing to register the exclusion constraint and validate existing rows. |
+| `documentdb.enableNonBlockingUniqueIndexBuild` | `on` | Builds unique ordered indexes without holding a long write lock, using `CREATE INDEX CONCURRENTLY` with post-processing to register the exclusion constraint and validate existing rows. |
 
 When enabled, creating a unique ordered index on an existing collection no longer blocks concurrent writes for the duration of the build.
 
+### Collation
+
+| GUC | Default | Description |
+| --- | --- | --- |
+| `documentdb_core.enableCollation` | `off` | Accepts the `collation` option on queries. It is defined by `pg_documentdb_core`, hence the `documentdb_core.` prefix, and can be set per session. |
+
+While `off`, `find`, `aggregate`, and `count` reject a `collation` option with "collation is not supported in the find command yet." (or `aggregate` / `count` in place of `find`). `delete` follows the flag too. `distinct`, `findAndModify` and `update` reject `collation` whether or not the flag is on.
+
+With the flag on, a few aggregation stages still reject a collation, including `$bucket`, `$bucketAuto`, `$densify`, `$fill`, `$geoNear`, `$merge`, `$setWindowFields`, and `$sortByCount`.
+
 ### Off-by-default feature flags
 
 These flags gate functionality that is otherwise silently unavailable — in each case the command still succeeds, so the symptom is a missing effect rather than an error.
@@ -53,14 +63,14 @@ Unlike the flags above, these two produce an error rather than a missing effect,
 
 | 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. |
+| `documentdb.enableRoleCrud` | `off` | Enables custom roles through the data plane. When `on`, `createRole` creates the role and records it in the `documentdb_api_catalog.roles` table, and `dropRole` drops only roles recorded there. While `off`, `create_role`, `drop_role`, and `roles_info` each raise before doing any work, for example "The CreateRole command is currently unsupported." `update_role` is not implemented either way and always raises "UpdateRole command is not supported in preview." |
+| `documentdb.enableRolesAdminDBCheck` | `on` | 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.)*
+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.
 
-> **Note:** Since v0.116-0 the packaged gateway service — its systemd unit and per-major `gateway.env` file — is published as a release asset (`documentdb-gateway`, together with `documentdb-common`, which owns the unit templates). The `DOCUMENTDB_*` settings below apply to that packaged service, to the `documentdb-gateway` binary directly (which the `documentdb-local` container image configures internally), and to downstream packaging that installs its own unit. On a packaged install, `documentdb-setup` writes the managed block in `/etc/documentdb/local/<major>/gateway.env`; edits outside that block are preserved, but the managed block is rebuilt whenever the wizard re-runs.
+> **Note:** The packaged gateway service — its systemd unit and per-major `gateway.env` file — is published as a release asset (`documentdb-gateway`, together with `documentdb-common`, which owns the unit templates). The `DOCUMENTDB_*` settings below apply to that packaged service, to the `documentdb-gateway` binary directly (which the `documentdb-local` container image configures internally), and to downstream packaging that installs its own unit. On a packaged install, `documentdb-setup` writes the managed block in `/etc/documentdb/local/<major>/gateway.env`; edits outside that block are preserved, but the managed block is rebuilt whenever the wizard re-runs.
 
 | Environment variable | Purpose |
 | --- | --- |
@@ -76,7 +86,7 @@ For systemd-managed installs these are typically set through the unit's `Environ
 
 ### Connectivity check
 
-The gateway binary provides a `check` subcommand (added in v0.114-0) that acts as a post-install connectivity probe:
+The gateway binary provides a `check` subcommand that acts as a post-install connectivity probe:
 
 ```bash
 documentdb-gateway check [--config <path>]
diff --git a/postgres-api/functions.md b/postgres-api/functions.md
index 1402de4..b202ffd 100644
--- a/postgres-api/functions.md
+++ b/postgres-api/functions.md
@@ -1,6 +1,6 @@
 ---
 title: Functions
-description: Reference for the PostgreSQL functions exposed by the pg_documentdb extension in v0.114-0, including CRUD, schema, index, diagnostics, user and role management.
+description: Reference for the PostgreSQL functions exposed by the pg_documentdb extension in DocumentDB 1.0, including CRUD, schema, index, diagnostics, user and role management.
 ---
 
 # Functions
@@ -9,7 +9,7 @@ description: Reference for the PostgreSQL functions exposed by the pg_documentdb
 
 All BSON parameters are encoded as PostgreSQL `bson` values (provided by the `pg_documentdb_core` extension). For example, you can pass a literal BSON spec using the cast `'{ ... }'::documentdb_core.bson` in `psql`.
 
-> **This page describes v0.114-0.** It has not yet been revised for the current release (v0.117-0); behavior added upstream after the v0.114-0 tag is not documented here.
+> **This page describes DocumentDB 1.0** (extension version `1.0-0`).
 
 > **Reading the signatures below.** Parameter names are the ones the extension actually declares in `pg_documentdb/sql/udfs/`, so they are safe to use in named-argument calls such as `p_database_name => 'mydb'`. They are unquoted identifiers, so PostgreSQL folds them to lower case — `\df documentdb_api.*` prints `commandspec` where the source writes `commandSpec`, and `bigint`/`boolean`/`double precision` where the source writes `int8`/`bool`/`float8`. Either spelling works in a call. Types are written unqualified: `bson` and `bsonsequence` live in `documentdb_core`. A function with **two or more** `OUT` parameters returns a `record` and should be called as `SELECT * FROM ...`; one with a single `OUT` parameter returns that parameter's type directly, so a plain `SELECT fn(...)` is fine. A few wire-protocol entry points are PostgreSQL `PROCEDURE`s and must be invoked with `CALL`; these are called out individually.
 
@@ -25,7 +25,7 @@ Functions for creating, reading, updating, and deleting documents.
 | `documentdb_api.find_and_modify(p_database_name text, p_message bson, p_transaction_id text DEFAULT NULL, OUT p_result bson, OUT p_success boolean)` | Executes a MongoDB `findAndModify` command. |
 | `documentdb_api.insert_one(p_database_name text, p_collection_name text, p_document bson, p_transaction_id text DEFAULT NULL)` | Convenience wrapper that inserts a single document by database and collection name and returns the `insert` response. |
 | `documentdb_api_internal.insert_one(p_collection_id bigint, p_shard_key_value bigint, p_document bson, p_transaction_id text)` | **Deprecated and non-functional.** The implementation is a stub that always raises `insert_one is deprecated and should not be called`. Use the public `documentdb_api.insert_one` above. |
-| `CALL documentdb_api.bulkWrite(p_command bson, p_ops bsonsequence DEFAULT NULL, p_ns_info bsonsequence DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | **Command surface only — not implemented in v0.114-0.** The `PROCEDURE` exists (its SQL definition landed in v0.111-0) but every call raises `bulkWrite is not yet implemented`, and it also rejects being called inside a transaction. |
+| `CALL documentdb_api.bulkWrite(p_command bson, p_ops bsonsequence DEFAULT NULL, p_ns_info bsonsequence DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | **Not implemented in 1.0.** The `PROCEDURE` exists but every call raises `bulkWrite is not yet implemented`, and it also rejects being called inside a transaction. |
 | `documentdb_api.find_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Opens a cursor for a `find` command and returns its first page. Omit `cursorId` to have the server generate one. |
 | `documentdb_api.aggregate_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Opens a cursor for an `aggregate` command and returns its first page. Omit `cursorId` to have the server generate one. |
 | `documentdb_api.list_collections_cursor_first_page(database text, commandSpec bson, cursorId int8 DEFAULT 0, OUT cursorPage bson, OUT continuation bson, OUT persistConnection bool, OUT cursorId int8)` | Returns the `listCollections` result. Despite the name this is always a single batch — see the note below. |
@@ -43,7 +43,7 @@ Functions for creating, reading, updating, and deleting documents.
 
 ### Write procedures
 
-`insert` and `update` are also exposed as `PROCEDURE`s. `delete` has no procedure form in v0.114-0.
+`insert`, `update`, and `delete` are also exposed as `PROCEDURE`s. `delete` has a `_txn_proc` form but no `_bulk` form.
 
 | Procedure | Description |
 | --- | --- |
@@ -51,10 +51,11 @@ Functions for creating, reading, updating, and deleting documents.
 | `CALL documentdb_api.update_bulk(p_database_name text, p_update bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `update` equivalent of `insert_bulk`. |
 | `CALL documentdb_api.insert_txn_proc(p_database_name text, p_insert bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | Inserts documents without opening a subtransaction per statement. |
 | `CALL documentdb_api.update_txn_proc(p_database_name text, p_update bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `update` equivalent of `insert_txn_proc`. |
+| `CALL documentdb_api.delete_txn_proc(p_database_name text, p_delete bson, p_insert_documents bsonsequence DEFAULT NULL, p_transaction_id text DEFAULT NULL, INOUT p_result bson DEFAULT NULL, INOUT p_success boolean DEFAULT NULL)` | `delete` equivalent of `insert_txn_proc`. |
 
-> **None of these procedures may be called inside an explicit transaction block.** Each one raises `the insert procedure cannot be used in transactions. Please use the insert function instead` (`ERRCODE_DOCUMENTDB_OPERATIONNOTSUPPORTEDINTRANSACTION`) when it detects an open transaction. They differ from each other only in commit granularity, not in transaction support: `_bulk` commits per sub-batch, `_txn_proc` skips the per-statement subtransaction. Inside a transaction, use the plain `insert`/`update` functions.
+> **None of these procedures may be called inside an explicit transaction block.** Each one raises an error such as `the insert procedure cannot be used in transactions. Please use the insert function instead` (`ERRCODE_DOCUMENTDB_OPERATIONNOTSUPPORTEDINTRANSACTION`) when it detects an open transaction. They differ from each other only in commit granularity, not in transaction support: `_bulk` commits per sub-batch, `_txn_proc` skips the per-statement subtransaction. Inside a transaction, use the plain `insert`/`update`/`delete` functions.
 
-> **The gateway does not use these by default.** Both are gated by gateway settings that default to `false` — `enableWriteProcedures` selects the `_txn_proc` variants and `enableWriteProceduresWithBatchCommit` selects the `_bulk` variants. Out of the box every wire-protocol write goes through `documentdb_api.insert` / `documentdb_api.update`.
+> **The gateway does not use these by default.** They are gated by gateway settings that default to `false` — `enableWriteProcedures` selects the `_txn_proc` variants and `enableWriteProceduresWithBatchCommit` selects the `_bulk` variants (insert and update only) — and even when enabled the gateway uses them only for writes outside a transaction. Out of the box every wire-protocol write goes through `documentdb_api.insert` / `documentdb_api.update` / `documentdb_api.delete`.
 
 ## Collection and Database Management
 
@@ -68,13 +69,13 @@ Functions for managing collections, views, databases, and sharding.
 | `documentdb_api.rename_collection(p_database_name text, p_collection_name text, p_target_name text, p_drop_target bool DEFAULT false)` | Renames a collection using explicit arguments. |
 | `documentdb_api.rename_collection(p_commandspec bson)` | Overload taking a wire-protocol `renameCollection` BSON spec. This is the form the gateway calls. |
 | `documentdb_api.drop_database(p_database_name text, p_write_concern bson DEFAULT NULL)` | Drops a database and all of its collections. |
-| `documentdb_api.list_databases(p_list_databases_spec bson)` | Returns information about all databases (added in v0.102-0). |
+| `documentdb_api.list_databases(p_list_databases_spec bson)` | Returns information about all databases. |
 | `documentdb_api.shard_collection(p_database_name text, p_collection_name text, p_shard_key bson, p_is_reshard bool DEFAULT true)` | Shards or reshards a collection on the supplied key. This is the form the gateway calls. **Pass `p_is_reshard => false` when sharding for the first time** — see the notes below. |
 | `documentdb_api.shard_collection(p_shard_key_spec bson)` | Single-argument overload taking the whole request as BSON. |
 | `documentdb_api.reshard_collection(p_shard_key_spec bson)` | Re-shards an already-sharded collection. |
 | `documentdb_api.unshard_collection(p_shard_key_spec bson)` | Removes the shard key from a sharded collection, returning it to a single unsharded table. |
 | `documentdb_api.coll_mod(p_database_name text, p_collection_name text, p_spec bson)` | Executes a MongoDB `collMod` command. Changes collection options — `viewOn`, `pipeline`, `validator`, `expireAfterSeconds`, `changeStreamPreAndPostImages` — on an existing collection. |
-| `documentdb_api.compact(p_spec bson)` | Compacts a collection's data and indexes (added in v0.104-0). Requires a GUC that is off by default — see the note below. |
+| `documentdb_api.compact(p_spec bson)` | Executes a MongoDB `compact` command. `mode` is `standard` (default, a plain `VACUUM`), `full` (`VACUUM FULL`), or `updateStats` (`ANALYZE`). `full` requires a GUC that is off by default — see the note below. |
 
 > **Shard keys must be hashed.** Every value in the shard key document has to be the string `"hashed"`; anything else raises `only shard keys that use hashed are supported` (or `Shard key value provided is invalid` for a different string). A first-time shard therefore looks like `SELECT documentdb_api.shard_collection('mydb', 'users', '{ "value": "hashed" }'::documentdb_core.bson, false);`.
 
@@ -82,14 +83,14 @@ Functions for managing collections, views, databases, and sharding.
 
 > **Sharding operations rewrite the whole collection.** `shard_collection`, `reshard_collection`, and `unshard_collection` each build a shadow table and re-insert every document, so plan for roughly double the collection's disk footprint for the duration and expect a runtime proportional to collection size. None of them warn about this.
 
-> **`compact` requires `documentdb.enableCompactVacuumFull`, which defaults to `off`.** With the GUC off, `compact` returns `{ "ok": 1, "bytesFreed": 0 }` and reclaims nothing — no error, no warning. Turn the GUC on to actually run the (blocking) `VACUUM FULL`. `compact` also required a separate `documentdb.enableCompact` GUC when it was introduced in v0.104-0; that flag was removed in v0.109-0.
+> **`compact` with `mode: "full"` requires `documentdb.enableCompactVacuumFull`, which defaults to `off`.** With the GUC off, a `full` compact returns `{ "ok": 1, "bytesFreed": 0 }` and reclaims nothing — no error, no warning. Turn the GUC on to run the blocking `VACUUM FULL`. The `standard` and `updateStats` modes always run. `bytesFreed` is the measured drop in the collection's on-disk size across the vacuum, so a `standard` compact usually reports `0`: a plain `VACUUM` makes space reusable but rarely shrinks the files. (Until `ALTER EXTENSION documentdb UPDATE` brings the schema to `1.0-0`, `bytesFreed` falls back to the older bloat estimate.) `dryRun: true` returns that estimate as `estimatedBytesFreed` without vacuuming.
 
 ## Index Management
 
 | Function | Description |
 | --- | --- |
 | `documentdb_api_internal.create_indexes_non_concurrently(p_database_name text, p_arg bson, p_skip_check_collection_create boolean DEFAULT false)` | Creates indexes in the foreground, blocking writes for the duration. With the default `p_skip_check_collection_create => false` this raises on any collection whose data table was not created in the current transaction, so a direct call on an existing collection needs `p_skip_check_collection_create => true`. The background path below calls it internally when it creates the collection itself. |
-| `documentdb_api.create_indexes_background(p_database_name text, p_index_spec bson, OUT retval bson, OUT ok boolean, OUT requests bson)` | Validates an index spec and **queues** the build, then returns immediately — it does not wait for the index to be built. Present since the initial release; background builds became the working default in v0.104-0, when the drain job started being scheduled automatically. |
+| `documentdb_api.create_indexes_background(p_database_name text, p_index_spec bson, OUT retval bson, OUT ok boolean, OUT requests bson)` | Validates an index spec and **queues** the build, then returns immediately — it does not wait for the index to be built. |
 | `documentdb_api_internal.check_build_index_status(p_arg bson, OUT retval bson, OUT ok boolean, OUT complete boolean)` | Reports on builds queued by `create_indexes_background`. Takes the `requests` document returned by that call. |
 | `CALL documentdb_api.drop_indexes(p_database_name text, p_arg bson, INOUT retval bson DEFAULT NULL)` | Drops indexes via the wire-protocol `dropIndexes` command. Implemented as a `PROCEDURE`. |
 
@@ -141,9 +142,9 @@ Functions backing diagnostic and administrative wire protocol commands.
 | `documentdb_api.coll_stats(p_database_name text, p_collection_name text, p_scale float8 DEFAULT 1)` | Returns storage and index statistics for a collection (`collStats`). |
 | `documentdb_api.db_stats(p_database_name text, p_scale float8 DEFAULT 1, p_freestorage bool DEFAULT false)` | Returns storage statistics for a database (`dbStats`). |
 | `documentdb_api.validate(database text, validateSpec bson, OUT document bson)` | Validates a collection's indexes (`validate`). |
-| `documentdb_api.connection_status(p_spec bson)` | Returns authentication and role information for the current connection (`connectionStatus`, added in v0.105-0). |
-| `documentdb_api.kill_op(p_command_spec bson)` | Cancels a running operation by op id (`killOp`, added in v0.109-0). |
-| `documentdb_api.current_op_command(p_spec bson, OUT document bson)` | Backs the `currentOp` wire-protocol command (added in v0.102-0). The `$currentOp` aggregation stage uses the internal `documentdb_api_internal.current_op_aggregation(p_spec bson, OUT document bson)` set-returning helper, which has existed since v0.101-0. |
+| `documentdb_api.connection_status(p_spec bson)` | Returns authentication and role information for the current connection (`connectionStatus`). |
+| `documentdb_api.kill_op(p_command_spec bson)` | Cancels a running operation by op id (`killOp`). |
+| `documentdb_api.current_op_command(p_spec bson, OUT document bson)` | Backs the `currentOp` wire-protocol command. The `$currentOp` aggregation stage uses the internal `documentdb_api_internal.current_op_aggregation(p_spec bson, OUT document bson)` set-returning helper. |
 
 ## User Management
 
@@ -158,14 +159,14 @@ Functions for creating, updating, and managing database users. Backed by the wir
 
 ## Role Management
 
-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`.
+Functions for custom roles. Backed by the wire protocol `createRole`, `dropRole`, `rolesInfo`, and `updateRole` commands.
 
-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.
+`create_role`, `drop_role`, and `roles_info` are gated behind `documentdb.enableRoleCrud`, which is off by default, so on a stock build they raise "The CreateRole command is currently unsupported." and its equivalents before doing any work. With it on, `create_role` creates the role, grants its parent roles, and records it in the `documentdb_api_catalog.roles` table. A non-empty `privileges` array fails with "Privileges on a collection are currently unsupported.", so a custom role can only inherit built-in roles. While `documentdb.enableRolesAdminDBCheck` is on (the default), the role functions require `"$db": "admin"` in the spec, from SQL as well as over the wire: they fail with "The required $db property is missing." without it and reject any other database. With the check off, neither is enforced.
 
 | 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.create_role(p_spec bson)` | Creates a custom role. |
+| `documentdb_api.drop_role(p_spec bson)` | Drops a custom role. Built-in roles raise "Cannot drop built-in role", and a role not recorded in `documentdb_api_catalog.roles` raises "The specified role '...' does not exist." |
 | `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. |
 
diff --git a/postgres-api/index.md b/postgres-api/index.md
index 758e488..28373bb 100644
--- a/postgres-api/index.md
+++ b/postgres-api/index.md
@@ -1,11 +1,11 @@
 ---
 title: Components
-description: Learn about pg_documentdb_core, pg_documentdb, and pg_documentdb_gw — the two PostgreSQL extensions and the gateway that enable BSON support, document operations, and MongoDB wire protocol compatibility in Postgres.
+description: Learn about pg_documentdb_core, pg_documentdb, pg_documentdb_extended_rum, and pg_documentdb_gw — the three PostgreSQL extensions and the gateway that enable BSON support, document operations, indexing, and MongoDB wire protocol compatibility in Postgres.
 ---
 
 # Components
 
-The DocumentDB implementation consists of two PostgreSQL extensions and a gateway that work together to provide MongoDB-compatible document database functionality on top of PostgreSQL.
+The DocumentDB implementation consists of three PostgreSQL extensions and a gateway that work together to provide MongoDB-compatible document database functionality on top of PostgreSQL.
 
 ## pg_documentdb_core
 
@@ -39,6 +39,20 @@ The DocumentDB implementation consists of two PostgreSQL extensions and a gatewa
 
 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_extended_rum
+
+`pg_documentdb_extended_rum` (SQL extension name `documentdb_extended_rum`) is DocumentDB's fork of the PostgreSQL RUM index access method, which backs DocumentDB's document indexes. It keeps RUM's on-disk format and extends the query path for document workloads.
+
+It is required in 1.0: `documentdb.rum_library_load_option` defaults to `require_documentdb_extended_rum`, so `pg_documentdb` loads its index handler from the extended RUM library. The library loads only from `shared_preload_libraries`, and `CREATE EXTENSION documentdb CASCADE` does not create the extension, so a manually configured server needs both steps before indexes are built:
+
+```sql
+-- postgresql.conf: add pg_documentdb_extended_rum to shared_preload_libraries and set
+-- documentdb.alternate_index_handler_name = 'extended_rum', then restart
+CREATE EXTENSION documentdb_extended_rum;
+```
+
+The package setup wizard and the `documentdb-local` image do this for you. See [Configuration](https://documentdb.io/docs/postgres-api/configuration/) for the load option.
+
 ## pg_documentdb_gw
 
 `pg_documentdb_gw` is the gateway protocol translation layer that converts the user's MongoDB wire protocol commands into PostgreSQL queries against the `pg_documentdb` API. It is what allows MongoDB-compatible drivers and tools (`mongosh`, PyMongo, the official MongoDB Node.js driver, the VS Code extension, and others) to talk to a DocumentDB instance unmodified.
@@ -53,4 +67,4 @@ To use `pg_documentdb`, you need to have `pg_documentdb_core` installed and conf
 
 - **Cursor and Session Management:** Translates `getMore`, `killCursors`, `killSessions`, and `killOp` commands to the corresponding backend operations.
 
-- **Deployment Options:** Can be run as a standalone process (the default in the `documentdb-local` container) or, since v0.108-0, as a PostgreSQL background worker via the `pg_documentdb_gw_host` extension.
+- **Deployment Options:** Can be run as a standalone process (the default in the `documentdb-local` container) or, when built from source, as a PostgreSQL background worker via the `pg_documentdb_gw_host` extension, which the packages and the container image don't include.