diff --git a/api-reference/operators/aggregation/$currentop.md b/api-reference/operators/aggregation/$currentop.md
new file mode 100644
index 0000000..46bc49b
--- /dev/null
+++ b/api-reference/operators/aggregation/$currentop.md
@@ -0,0 +1,77 @@
+---
+title: $currentOp
+description: The $currentOp stage returns information on active and queued operations for the database.
+type: operators
+category: aggregation
+---
+
+# $currentOp
+
+The `$currentOp` stage returns a stream of documents containing information on active and queued operations for the database instance. This stage must be the first stage in the pipeline and is run on the `admin` database.
+
+## Syntax
+
+```javascript
+db.adminCommand({
+  aggregate: 1,
+  pipeline: [
+    {
+      $currentOp: {
+        allUsers: <boolean>,
+        idleConnections: <boolean>,
+        idleCursors: <boolean>,
+        idleSessions: <boolean>,
+        localOps: <boolean>
+      }
+    }
+  ],
+  cursor: {}
+})
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| **`allUsers`** | Optional. Boolean. If `true`, reports operations for all users. Default: `false`. |
+| **`idleConnections`** | Optional. Boolean. If `true`, reports on idle connections. Default: `false`. |
+| **`idleCursors`** | Optional. Boolean. If `true`, reports on idle cursors. Default: `false`. |
+| **`idleSessions`** | Optional. Boolean. If `true`, reports on idle sessions. Default: `false`. |
+| **`localOps`** | Optional. Boolean. If `true`, reports operations running locally on the current instance. Default: `false`. |
+
+## Examples
+
+### Example 1: List active operations
+
+Return all currently active operations:
+
+```javascript
+db.adminCommand({
+  aggregate: 1,
+  pipeline: [
+    { $currentOp: { allUsers: true } }
+  ],
+  cursor: {}
+})
+```
+
+### Example 2: Filter active operations
+
+Return active operations for a specific database, combined with `$match`:
+
+```javascript
+db.adminCommand({
+  aggregate: 1,
+  pipeline: [
+    { $currentOp: { allUsers: true } },
+    { $match: { "ns": /^mydb\./ } }
+  ],
+  cursor: {}
+})
+```
+
+## Key Takeaways
+
+- **Must be first stage** — `$currentOp` must be the first stage in the aggregation pipeline
+- **Admin database only** — this stage must be run against the `admin` database using `db.adminCommand()`
+- **Collection-agnostic** — does not operate on a specific collection
diff --git a/api-reference/operators/aggregation/$replaceroot.md b/api-reference/operators/aggregation/$replaceroot.md
new file mode 100644
index 0000000..8cbd483
--- /dev/null
+++ b/api-reference/operators/aggregation/$replaceroot.md
@@ -0,0 +1,136 @@
+---
+title: $replaceRoot
+description: The $replaceRoot stage replaces the input document with the specified document.
+type: operators
+category: aggregation
+---
+
+# $replaceRoot
+
+The `$replaceRoot` stage replaces the input document with the specified document. The operation replaces all existing fields in the input document, including the `_id` field. This is useful for promoting an embedded document to the top level.
+
+## Syntax
+
+```javascript
+{
+  $replaceRoot: {
+    newRoot: <expression>
+  }
+}
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| **`newRoot`** | Required. A document expression that resolves to a document. The expression can be any valid expression that resolves to a document, such as a field path to an embedded document, a `$mergeObjects` expression, or a literal document. |
+
+## 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 }
+    ]
+  }
+}
+```
+
+### Example 1: Promote an embedded document
+
+Promote the `staff.totalStaff` subdocument to the top level:
+
+```javascript
+db.stores.aggregate([
+  { $replaceRoot: { newRoot: "$staff.totalStaff" } },
+  { $limit: 1 }
+])
+```
+
+This query returns:
+
+```json
+[
+  { "fullTime": 8, "partTime": 20 }
+]
+```
+
+### Example 2: Use $mergeObjects to combine fields
+
+Merge the staff subdocument with additional top-level fields:
+
+```javascript
+db.stores.aggregate([
+  {
+    $replaceRoot: {
+      newRoot: {
+        $mergeObjects: [
+          "$staff.totalStaff",
+          { storeName: "$name", totalSales: "$sales.totalSales" }
+        ]
+      }
+    }
+  },
+  { $limit: 1 }
+])
+```
+
+This query returns:
+
+```json
+[
+  {
+    "fullTime": 8,
+    "partTime": 20,
+    "storeName": "First Up Consultants | Beverage Shop - Satterfieldmouth",
+    "totalSales": 75670
+  }
+]
+```
+
+### Example 3: Replace root after $unwind
+
+Extract individual sales categories as top-level documents:
+
+```javascript
+db.stores.aggregate([
+  { $unwind: "$sales.salesByCategory" },
+  {
+    $replaceRoot: {
+      newRoot: {
+        $mergeObjects: [
+          "$sales.salesByCategory",
+          { storeName: "$name" }
+        ]
+      }
+    }
+  },
+  { $limit: 3 }
+])
+```
+
+## Limitations
+
+- If `newRoot` evaluates to a missing value or a non-document type, the operation errors
+
+## Key Takeaways
+
+- **Replaces the entire document** — the output document is the evaluated `newRoot` expression
+- **`$replaceWith` is an alias** — `{ $replaceWith: <expression> }` is shorthand for `{ $replaceRoot: { newRoot: <expression> } }`
+- **Combine with `$mergeObjects`** — use `$mergeObjects` to preserve fields from the original document while promoting an embedded document
diff --git a/api-reference/operators/aggregation/$search.md b/api-reference/operators/aggregation/$search.md
new file mode 100644
index 0000000..51fbe3b
--- /dev/null
+++ b/api-reference/operators/aggregation/$search.md
@@ -0,0 +1,130 @@
+---
+title: $search
+description: The $search stage in the aggregation pipeline runs a vector similarity search through the cosmosSearch or knnBeta operator.
+type: operators
+category: aggregation
+---
+
+# $search
+
+The `$search` stage in the aggregation pipeline runs a vector similarity search over a vector index. It carries exactly one search operator — `cosmosSearch`, or the deprecated `knnBeta` — and returns the documents whose stored embedding is closest to a query vector.
+
+`$search` must be the first stage in the pipeline, and the field named by `path` must be covered by a vector index.
+
+> `$search` in DocumentDB is a vector search stage. It does not accept text-search operators: a spec such as `{ $search: { text: { ... } } }` is rejected with `Unrecognized $search option: text`. For full-text queries, use the `$text` query operator against a text index. For new work, prefer [`$vectorSearch`](./%24vectorsearch.md), which is the current stage for vector search and takes a clearer spec; `$search` remains for compatibility with existing `cosmosSearch` and `knnBeta` queries.
+
+## Syntax
+
+```javascript
+{
+  $search: {
+    index: <string>,
+    cosmosSearch: {
+      path: <string>,
+      vector: [<number>, ...],
+      k: <positiveInteger>,
+      filter: <document>,
+      exact: <boolean>,
+      oversampling: <number>
+    }
+  }
+}
+```
+
+## Parameters
+
+The stage takes exactly one search operator, plus a small number of options alongside it.
+
+| Parameter | Description |
+| --- | --- |
+| **`cosmosSearch`** | The search operator, holding the query spec described below. Exactly one operator must be present — supplying both `cosmosSearch` and `knnBeta` fails with `The $search spec can only contain one search operator.`, and supplying neither fails with `Invalid search spec provided, must include one of the supported operators.` |
+| **`knnBeta`** | Deprecated alias kept for backward compatibility. It takes the same spec as `cosmosSearch`, except that `filter` and `score` are rejected outright. Use `cosmosSearch` instead. |
+| **`index`** | Optional. The name of the index to search, as a string. |
+| **`returnStoredSource`** | Optional. Accepted for compatibility and ignored. |
+| **`count`** | Optional. Parsed and validated, but the resulting count metadata is **not yet emitted in the results**, so the option currently has no observable effect. |
+
+Any other key alongside the operator is rejected with `Unrecognized $search option: <name>`.
+
+### Operator spec
+
+| Field | Description |
+| --- | --- |
+| **`path`** | Required. The document field holding the stored embedding. Must be covered by a vector index. Omitting it fails with `$path is required field for using a vector index.` |
+| **`vector`** | Required. The query embedding, as a non-empty array of numbers. Omitting it fails with `$vector is required field for using a vector index.` |
+| **`k`** | Required. The number of documents to return, as a positive integer. |
+| **`filter`** | Optional. A query document intersected with the vector search. Requires vector pre-filtering to be enabled on the server; when it is not, the query fails with `$filter is not supported for vector search yet.` Not supported at all with `knnBeta`. |
+| **`exact`** | Optional. Boolean. Runs an exact search instead of an approximate one. |
+| **`oversampling`** | Optional. Widens the candidate set considered during an approximate search, improving recall at the cost of latency. |
+| **`score`** | Optional. Not supported with `knnBeta`, which rejects it with `$score is not supported for knnBeta queries.` |
+
+## Examples
+
+The examples on this page use the following documents in a `products` collection, with a vector index on `embedding`.
+
+```json
+[
+  { "_id": 1, "name": "Espresso Machine", "category": "appliance", "embedding": [0.9, 0.1, 0.05] },
+  { "_id": 2, "name": "Coffee Grinder", "category": "appliance", "embedding": [0.85, 0.15, 0.1] },
+  { "_id": 3, "name": "Merlot Bottle", "category": "wine", "embedding": [0.05, 0.9, 0.2] },
+  { "_id": 4, "name": "Chardonnay Bottle", "category": "wine", "embedding": [0.1, 0.85, 0.25] }
+]
+```
+
+### Example 1: Nearest neighbors for a query vector
+
+Return the three documents closest to a query embedding:
+
+```javascript
+db.products.aggregate([
+  {
+    $search: {
+      cosmosSearch: {
+        path: "embedding",
+        vector: [0.88, 0.12, 0.07],
+        k: 3
+      }
+    }
+  },
+  { $project: { name: 1, category: 1 } }
+])
+```
+
+```json
+[
+  { "_id": 1, "name": "Espresso Machine", "category": "appliance" },
+  { "_id": 2, "name": "Coffee Grinder", "category": "appliance" },
+  { "_id": 4, "name": "Chardonnay Bottle", "category": "wine" }
+]
+```
+
+### Example 2: Exact search
+
+Set `exact` to `true` to compare against every indexed vector rather than an approximate candidate set. This is slower, and useful when you need a reference result to measure recall against:
+
+```javascript
+db.products.aggregate([
+  {
+    $search: {
+      cosmosSearch: {
+        path: "embedding",
+        vector: [0.88, 0.12, 0.07],
+        k: 3,
+        exact: true
+      }
+    }
+  },
+  { $project: { name: 1 } }
+])
+```
+
+## Behavior
+
+- **`$search` must come first.** Placing it anywhere else fails with `$search must appear as the initial stage in the pipeline sequence.` The same applies when the pipeline already carries a limit ahead of it.
+- **One operator per spec.** The stage rejects a spec carrying more than one search operator, and a spec carrying none.
+- **`path` must be indexed.** The field named by `path` must be covered by a vector index; see [`$vectorSearch`](./%24vectorsearch.md) for creating one.
+
+## Related content
+
+- [`$vectorSearch`](./%24vectorsearch.md) — the current vector search stage, and the one to prefer for new queries.
+- [`$project`](./%24project.md) — shape the documents returned by the search.
+- [`$limit`](./%24limit.md) — narrow the result set further; `k` already bounds it.
diff --git a/api-reference/operators/aggregation/$setwindowfields.md b/api-reference/operators/aggregation/$setwindowfields.md
new file mode 100644
index 0000000..20fb413
--- /dev/null
+++ b/api-reference/operators/aggregation/$setwindowfields.md
@@ -0,0 +1,197 @@
+---
+title: $setWindowFields
+description: The $setWindowFields stage performs operations on a specified span of documents (a window) and returns results based on the chosen window operator.
+type: operators
+category: aggregation
+---
+
+# $setWindowFields
+
+The `$setWindowFields` stage groups documents into partitions, applies window functions over a defined span of documents within each partition, and outputs a new field with the result for each document. This is useful for running calculations (like running averages, ranks, and cumulative sums) without collapsing documents into groups.
+
+## Syntax
+
+```javascript
+{
+  $setWindowFields: {
+    partitionBy: <expression>,
+    sortBy: {
+      <field1>: <1 or -1>,
+      ...
+    },
+    output: {
+      <outputField1>: {
+        <windowOperator>: <specification>,
+        window: {
+          // a document window:
+          documents: [<lower>, <upper>]
+
+          // -- or a range window, mutually exclusive with the above:
+          // range: [<lower>, <upper>],
+          // unit: <time unit>
+        }
+      },
+      ...
+    }
+  }
+}
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| **`partitionBy`** | Optional. An expression to group documents into partitions. Similar to `$group`'s `_id`. If omitted, all documents belong to a single partition. |
+| **`sortBy`** | A document specifying the sort order within each partition, with each field value `1` (ascending) or `-1` (descending). Optional only in narrow cases: a `range` window requires exactly one ascending sort field, a bounded `documents` window requires a sort field, and several operators require one of their own. See [sortBy requirements](#sortby-requirements). |
+| **`output`** | Required. A document with one or more fields. Each field specifies a window operator and optionally a window frame. |
+
+### Window Frame Options
+
+| Option | Description |
+| --- | --- |
+| **`documents`** | Row-based window bounds. Array of `[lower, upper]` where values can be `"unbounded"`, `"current"`, or an integer offset. |
+| **`range`** | Range-based window bounds. Array of `[lower, upper]` using sort key values. |
+| **`unit`** | Time unit for range-based windows. Values: `"year"`, `"quarter"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`, `"second"`, `"millisecond"`. |
+
+A `window` holds **either** `documents`, **or** `range` with an optional `unit` — never a mix. Combining them fails to parse:
+
+```
+Window bounds may only define either 'documents' or 'unit', but never both.
+```
+
+A `window` carrying neither is rejected as well:
+
+```
+'window' field can only contain 'documents' as the only argument or 'range' with an optional 'unit' field
+```
+
+### sortBy requirements
+
+`sortBy` is parsed as optional, but the window and the operator each impose their own requirement, so most real pipelines need it:
+
+| Situation | Requirement | Error when unmet |
+| --- | --- | --- |
+| `range` window | Exactly one sort field, sorted **ascending**. A descending or compound `sortBy` is rejected, so a `range` window cannot be paired with `-1`. | `Expected a single sort by field for range-based window` / `Expected ascending sortBy field definition` |
+| `documents` window with bounds | A sort field is required. It may be omitted only when the window is unbounded at both ends. | `Missing sortBy field for document-based window` |
+| Rank-style and positional operators | Require a sort field, and several require a non-compound one. `$shift` requires it unconditionally. | `<operator> requires a sortBy` / `<operator> needs a non-compound sortBy parameter` / `'sortBy' parameters must be specified for $shift` |
+
+### Supported Window Operators
+
+`$addToSet`, `$avg`, `$bottom`, `$bottomN`, `$count`, `$covariancePop`, `$covarianceSamp`, `$denseRank`, `$derivative`, `$documentNumber`, `$expMovingAvg`, `$first`, `$firstN`, `$integral`, `$last`, `$lastN`, `$linearFill`, `$locf`, `$max`, `$maxN`, `$min`, `$minN`, `$push`, `$rank`, `$shift`, `$stdDevPop`, `$stdDevSamp`, `$sum`, `$top`, `$topN`
+
+## Examples
+
+Consider this sample document from the stores collection.
+
+```json
+{
+  "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
+  "name": "First Up Consultants | Bed and Bath Center - South Amir",
+  "city": "South Amir",
+  "staff": {
+    "totalStaff": {
+      "fullTime": 18,
+      "partTime": 17
+    }
+  },
+  "sales": {
+    "totalSales": 37701
+  }
+}
+```
+
+### Example 1: Rank stores by sales
+
+Rank all stores by total sales:
+
+```javascript
+db.stores.aggregate([
+  {
+    $setWindowFields: {
+      sortBy: { "sales.totalSales": -1 },
+      output: {
+        salesRank: { $rank: {} }
+      }
+    }
+  },
+  { $project: { name: 1, "sales.totalSales": 1, salesRank: 1 } },
+  { $limit: 3 }
+])
+```
+
+### Example 2: Running average partitioned by city
+
+Calculate a running average of sales within each city, using a 3-document window:
+
+```javascript
+db.stores.aggregate([
+  {
+    $setWindowFields: {
+      partitionBy: "$city",
+      sortBy: { "sales.totalSales": 1 },
+      output: {
+        movingAvgSales: {
+          $avg: "$sales.totalSales",
+          window: { documents: [-1, 1] }
+        }
+      }
+    }
+  },
+  { $project: { name: 1, city: 1, "sales.totalSales": 1, movingAvgSales: 1 } },
+  { $limit: 3 }
+])
+```
+
+### Example 3: Cumulative sum
+
+Calculate a cumulative sum of sales ordered by total sales:
+
+```javascript
+db.stores.aggregate([
+  {
+    $setWindowFields: {
+      sortBy: { "sales.totalSales": 1 },
+      output: {
+        cumulativeSales: {
+          $sum: "$sales.totalSales",
+          window: { documents: ["unbounded", "current"] }
+        }
+      }
+    }
+  },
+  { $project: { name: 1, "sales.totalSales": 1, cumulativeSales: 1 } },
+  { $limit: 3 }
+])
+```
+
+### Example 4: Document number
+
+Assign a sequential number to each document:
+
+```javascript
+db.stores.aggregate([
+  {
+    $setWindowFields: {
+      sortBy: { name: 1 },
+      output: {
+        docNumber: { $documentNumber: {} }
+      }
+    }
+  },
+  { $project: { name: 1, docNumber: 1 } },
+  { $limit: 3 }
+])
+```
+
+## Limitations
+
+- Collation is not supported in `$setWindowFields`
+- `$median` and `$percentile` window operators are not yet supported
+- Cannot use both `documents` and `range` in the same window specification
+
+## Key Takeaways
+
+- **Non-destructive** — unlike `$group`, `$setWindowFields` adds computed fields to each document without collapsing rows
+- **Partitioning** — use `partitionBy` to calculate window functions within groups independently
+- **Flexible windows** — use `documents` for row-based windows or `range` for value-based windows
+- **Ranking** — `$rank`, `$denseRank`, and `$documentNumber` are commonly used for ordering and pagination
diff --git a/api-reference/operators/aggregation/$unionwith.md b/api-reference/operators/aggregation/$unionwith.md
new file mode 100644
index 0000000..1be7a9d
--- /dev/null
+++ b/api-reference/operators/aggregation/$unionwith.md
@@ -0,0 +1,129 @@
+---
+title: $unionWith
+description: The $unionWith stage performs a union of two collections, combining pipeline results from two collections into a single result set.
+type: operators
+category: aggregation
+---
+
+# $unionWith
+
+The `$unionWith` stage performs a union of documents from two collections. It combines the pipeline results from two collections into a single result set, similar to SQL's `UNION ALL`. The stage outputs all documents from both collections, including duplicates.
+
+## Syntax
+
+**String form (simple union):**
+
+```javascript
+{
+  $unionWith: "<collection>"
+}
+```
+
+**Document form (with pipeline):**
+
+```javascript
+{
+  $unionWith: {
+    coll: "<collection>",
+    pipeline: [ <stage1>, <stage2>, ... ]
+  }
+}
+```
+
+## Parameters
+
+| Parameter | Description |
+| --- | --- |
+| **`coll`** | Optional (required if `pipeline` is omitted or doesn't start with `$documents`). The name of the collection to union with. |
+| **`pipeline`** | Optional. An aggregation pipeline to apply to the specified collection before the union. |
+
+## Examples
+
+Consider a `stores` collection and a `warehouses` collection.
+
+**stores collection:**
+
+```json
+{
+  "_id": "store-001",
+  "name": "First Up Consultants | Beverage Shop",
+  "city": "Seattle",
+  "type": "retail"
+}
+```
+
+**warehouses collection:**
+
+```json
+{
+  "_id": "wh-001",
+  "name": "West Coast Distribution Center",
+  "city": "Portland",
+  "type": "warehouse"
+}
+```
+
+### Example 1: Simple union
+
+Combine all documents from both collections:
+
+```javascript
+db.stores.aggregate([
+  { $project: { name: 1, city: 1, type: 1 } },
+  {
+    $unionWith: "warehouses"
+  }
+])
+```
+
+### Example 2: Union with pipeline
+
+Union the stores collection with a filtered and projected subset of the warehouses collection:
+
+```javascript
+db.stores.aggregate([
+  { $project: { name: 1, city: 1 } },
+  {
+    $unionWith: {
+      coll: "warehouses",
+      pipeline: [
+        { $match: { city: "Portland" } },
+        { $project: { name: 1, city: 1 } }
+      ]
+    }
+  }
+])
+```
+
+### Example 3: Union with $documents
+
+Use `$documents` to inject literal documents into the union:
+
+```javascript
+db.stores.aggregate([
+  { $project: { name: 1, city: 1 } },
+  {
+    $unionWith: {
+      pipeline: [
+        { $documents: [
+          { name: "Pop-Up Shop", city: "Austin" },
+          { name: "Online Store", city: "Remote" }
+        ]}
+      ]
+    }
+  }
+])
+```
+
+## Limitations
+
+- The following stages are **not allowed** inside the `$unionWith` pipeline: `$out`, `$merge`, `$changeStream`
+- If `coll` is omitted, the pipeline must start with `$documents`
+- Maximum nested pipeline depth is 20 levels
+
+## Key Takeaways
+
+- **UNION ALL semantics** — duplicates are not removed; use `$group` after the union to deduplicate if needed
+- **Schema flexibility** — the two collections do not need to have the same schema
+- **Pipeline support** — apply transformations to the second collection before unioning
+- **String shorthand** — use the simple string form when no pipeline transformations are needed on the second collection