docs: fix vector search guidance, navigation, and example

docs/en/api-index.md

@@ -96,7 +96,7 @@ This index documents the current stable MongoDB adapter APIs and shared runtime
 |----------|--------|-------------|
 | [Aggregation pipeline](aggregate.md) | `aggregate()` | Aggregation pipeline query |
 | [Vector search](vector-search.md) | Collection / Model `vectorSearch()` | MongoDB Vector Search query with Model soft-delete visibility when applicable |
-| [Search indexes](search-indexes.md) | Collection / Model `createSearchIndex()` and related methods | Create, inspect, update, drop, and wait for Search / Vector Search indexes |
+| [Search indexes](search-indexes.md) | Collection / Model `createSearchIndex()` and related methods | Create, inspect, update, drop, and wait for Search indexes (`search` and `vectorSearch` types) |
 | [GridFS](gridfs.md) | `msq.gridfs()` / Model `gridfs()` | Upload, download, and resume GridFS files |
 
 ---
@@ -174,7 +174,7 @@ This index documents the current stable MongoDB adapter APIs and shared runtime
 
 - [Aggregation pipeline](aggregate.md) - Aggregation pipelines
 - [Vector search](vector-search.md) - MongoDB Vector Search queries
-- [Search indexes](search-indexes.md) - Search / Vector Search index lifecycle
+- [Search indexes](search-indexes.md) - Search index lifecycle (`search` and `vectorSearch` types)
 - [GridFS](gridfs.md) - GridFS upload, download, and resumable upload
 - [Query plans](explain.md) - Query plans
 - [Chain queries](chaining-api.md) - Chain queries

docs/en/capability-index.md

@@ -23,6 +23,7 @@ Principles:
 | Model | `msq.model()` / `MonSQLize.Model` | Supports model registration, relations, virtuals, populate, and common query entries |
 | write-path-policy | `writePathPolicy` | Optional runtime guard for Model-only write namespaces, including the `gridfs` category |
 | GridFS | `msq.gridfs()` / `model.gridfs()` | Upload, download, and phase-1 resumable GridFS upload. See [GridFS](./gridfs.md) |
+| Search index and vector search | `createSearchIndex()` / `vectorSearch()` | Search index lifecycle for types `search` and `vectorSearch`, then vector queries. See [Search indexes](./search-indexes.md) and [vectorSearch()](./vector-search.md) |
 | cache | Query `cache` options / `msq.cache` | Database query cache, multi-layer cache access, invalidation, and statistics |
 | transaction | `startSession()` / `withTransaction()` | Supports MongoDB transaction wrappers and transaction statistics |
 | pool | `pools` / `pool()` / `ConnectionPoolManager` | Declare `pools: PoolConfig[]` in the constructor, route with `pool()`, and use the low-level manager for advanced inspection or manual management |

docs/en/capability-traceability.md

@@ -10,7 +10,8 @@
 | Query (find / findOne / count / distinct) | `find.md` / `findOne.md` / `count.md` / `distinct.md` | `examples/docs/find.ts` / `find-one.ts` / `count.ts` / `distinct.ts` | `test/integration/mongodb/queries.test.ts` |
 | Paging / Chain query | `findPage.md` / `chaining-api.md` | `examples/docs/find-page.ts` / `chaining-api.ts` | `test/integration/model/model-features.test.ts` + `npm run test:examples` |
 | Aggregation / Expression | `aggregate.md` / `expression-functions.md` | `examples/docs/aggregate.ts` / `aggregate-advanced.ts` / `expression-functions.ts` | `test/unit/expression/*.test.ts` |
-| Collection / Model vector search | `vector-search.md` | Documented API example; requires an external Vector Search deployment and index | `test/unit/runtime/vector-search.test.ts` / `test/unit/runtime/model-relations-p0.test.ts` |
+| Collection / Model vector search | `vector-search.md` | `examples/docs/vector-search.ts` (Atlas, atlas-local, or Community 8.2+ with mongot; skips when no Search URI is set) | `test/unit/runtime/vector-search.test.ts` / `test/unit/runtime/model-relations-p0.test.ts` |
+| Search index lifecycle (`search` and `vectorSearch`) | `search-indexes.md` | `examples/docs/vector-search.ts` | `test/unit/search-indexes/` / `test/integration/search-indexes/` / `test/types/search-index-usage.test-d.ts` |
 | Write extension / Batch | `write-operations.md` / `updateBatch.md` / `deleteBatch.md` | `examples/docs/update.ts` / `batch-operations.ts` | `test/unit/writes/batch.test.ts` + `test/integration/mongodb/writes-batch.test.ts` |
 | Collection management capabilities | `collection-management.md` / `create-index.md` / `database-ops.md` | `examples/docs/collection-management.ts` | `test/integration/mongodb/management.test.ts` |
 | Production data tasks / index rollout | `production-data-migration.md` / `data-tasks.md` / `production-rollout.md` | `examples/docs/data-tasks.ts` | `test/unit/data-tasks/data-task-job-*.test.ts` / `test/integration/data-tasks/data-task-job-facade.test.ts` / `test/smoke/data-task-cli.test.ts` |

docs/en/error-codes.md

@@ -65,7 +65,7 @@ See [Data Tasks](./data-tasks.md) for the preview, approval, apply, backup, and
 | `POOL_NOT_FOUND` | The specified connection pool does not exist or the health checker cannot find the pool | Whether the pool name is registered, whether the case is consistent, and whether `pools` is passed in |
 | `INVALID_OPERATION` | The query is executed repeatedly, all connection pools are unavailable, and the transaction status is not allowed | Whether to repeat `toArray()`, pool health status, transaction life cycle |
 | `INVALID_ARGUMENT` | Query chain parameters, collection management parameters, function cache parameters | Parameter type, value range, non-empty string/object/array |
-| `INVALID_VECTOR_SEARCH` | Local Vector Search option validation | Vector index/path, finite query vector, ANN/ENN combination, filter/projection shape |
+| `INVALID_VECTOR_SEARCH` | Local Vector Search option validation | index name and path, finite query vector, ANN/ENN combination, filter/projection shape |
 | `INVALID_SEARCH_INDEX_DEFINITION` | Local Search index validation | Index name/type/definition, vectorSearch fields, option values |
 | `SEARCH_INDEX_EXISTS` | Search index name already exists | `ifExists` option, duplicate names in `createSearchIndexes` |
 | `SEARCH_INDEX_NOT_FOUND` | Search index target is missing | Index name, collection, `ignoreMissing` |

docs/en/examples.md

@@ -2,7 +2,7 @@
 
 Every core API in the documentation site should map, as much as possible, to an example that can run directly inside the current repository.
 
-> See the [official examples index](https://github.com/devcodex-labs/monSQLize/blob/main/examples/README.md) for the full source list. `npm run test:examples` compiles and executes the current **58** TypeScript examples. [`examples/helpers/bootstrap.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/helpers/bootstrap.ts) is a helper module and is not executed on its own.
+> See the [official examples index](https://github.com/devcodex-labs/monSQLize/blob/main/examples/README.md) for the full source list. `npm run test:examples` compiles and executes the current **59** TypeScript examples. [`examples/helpers/bootstrap.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/helpers/bootstrap.ts) is a helper module and is not executed on its own. [`examples/docs/vector-search.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/vector-search.ts) exits without calling Search when `MONSQLIZE_VECTOR_SEARCH_URI` and `MONSQLIZE_ATLAS_LOCAL_URI` are unset.
 
 ## How to Run
 
@@ -34,12 +34,16 @@ node .generated/examples-dist/examples/docs/find.js
 |----------|---------|
 | [`find.md`](./find.md) | [`examples/docs/find.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find.ts) |
 | [`findOne.md`](./findOne.md) | [`examples/docs/find-one.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find-one.ts) |
+| [`find-one-by-id.md`](./find-one-by-id.md) | [`examples/docs/find-one-by-id.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find-one-by-id.ts) |
+| [`find-by-ids.md`](./find-by-ids.md) | [`examples/docs/find-by-ids.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find-by-ids.ts) |
 | [`findPage.md`](./findPage.md) | [`examples/docs/find-page.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find-page.ts) |
 | [`find-and-count.md`](./find-and-count.md) | [`examples/docs/find-and-count.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/find-and-count.ts) |
 | [`count.md`](./count.md) | [`examples/docs/count.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/count.ts) |
 | [`count-queue.md`](./count-queue.md) | [`examples/docs/count-queue.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/count-queue.ts) |
 | [`distinct.md`](./distinct.md) | [`examples/docs/distinct.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/distinct.ts) |
 | [`aggregate.md`](./aggregate.md) | [`examples/docs/aggregate.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/aggregate.ts) |
+| [`vector-search.md`](./vector-search.md) | [`examples/docs/vector-search.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/vector-search.ts) |
+| [`search-indexes.md`](./search-indexes.md) | [`examples/docs/vector-search.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/vector-search.ts) |
 | [`explain.md`](./explain.md) | [`examples/docs/explain.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/explain.ts) |
 | [`chaining-api.md`](./chaining-api.md) | [`examples/docs/chaining-api.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/chaining-api.ts) |
 

docs/en/recipes.md

@@ -197,6 +197,12 @@ Model schema callbacks use the isolated `schema-dsl/runtime` owned by the `MonSQ
 
 Example source: [`examples/docs/model.ts`](https://github.com/devcodex-labs/monSQLize/blob/main/examples/docs/model.ts)
 
+## Query with vectorSearch
+
+`vectorSearch()` queries a Search index of type `vectorSearch`. Create and wait for that index with the [Search index lifecycle API](./search-indexes.md), then run the query described in [`vectorSearch()`](./vector-search.md).
+
+The runnable example is [`examples/docs/vector-search.ts`](../../examples/docs/vector-search.ts). It needs MongoDB Atlas, `mongodb/mongodb-atlas-local`, or Community/Enterprise 8.2+ with `mongot`. Set `MONSQLIZE_VECTOR_SEARCH_URI` or `MONSQLIZE_ATLAS_LOCAL_URI`. `mongodb-memory-server` cannot run the Search calls. When those variables are unset, the example exits without calling Search.
+
 ## Troubleshoot by Error Code
 
 ```ts