diff --git a/apps/docs/migration/api-v5-recall.mdx b/apps/docs/migration/api-v5-recall.mdx
index f3c024ba..355a72f6 100644
--- a/apps/docs/migration/api-v5-recall.mdx
+++ b/apps/docs/migration/api-v5-recall.mdx
@@ -1,6 +1,6 @@
---
title: "Migrate search to v5"
-description: "Upgrade search modes, filters, attachments, defaults, and response readers"
+description: "Upgrade search modes, filters, included context, defaults, and response readers"
sidebarTitle: "Search"
---
diff --git a/apps/docs/snippets/api-v5-content-management.mdx b/apps/docs/snippets/api-v5-content-management.mdx
index 04e8ae4b..0f197501 100644
--- a/apps/docs/snippets/api-v5-content-management.mdx
+++ b/apps/docs/snippets/api-v5-content-management.mdx
@@ -9,11 +9,11 @@ GET /v3/documents/{id}/chunks
```
```bash v5
-GET /ns/{namespace}/document/{id}?attach=chunks&attach=memories
+GET /ns/{namespace}/document/{id}?include=chunks,memories
```
-Repeat `attach` to include chunks, memories, or both. Omitted attachment keys are absent; requested attachments with no results are empty arrays. Lifecycle fields move under `system`:
+Pass `include` as a comma-separated list to return chunks, memories, or both. Keys you omit are absent; requested keys with no results are empty arrays. Lifecycle fields move under `system`:
```json
{"system":{"status":"done","createdAt":"...","updatedAt":"..."}}
@@ -66,7 +66,7 @@ See [memory forgetting](./api-v5-memory-forgetting) for the complete dry-run, ap
### Verification
-- Assert requested empty attachments are `[]`, while omitted attachments are absent.
+- Assert requested empty includes are `[]`, while omitted includes are absent.
- Paginate each resource type until `currentPage >= totalPages`; unselected arrays stay empty.
- Verify chunk rows contain their parent `documentId`.
- Exercise partial document-delete failures and semantic dry runs.
diff --git a/apps/docs/snippets/api-v5-overview.mdx b/apps/docs/snippets/api-v5-overview.mdx
index 7d8b6743..2239a314 100644
--- a/apps/docs/snippets/api-v5-overview.mdx
+++ b/apps/docs/snippets/api-v5-overview.mdx
@@ -19,7 +19,7 @@ The API base URL and bearer keys do not change. v5 application routes are unvers
Apply [ingestion](./api-v5-document-writes), [updates](./api-v5-document-updates), [content management](./api-v5-document-reads), [search](./api-v5-recall), [profiles](./api-v5-profiles), [forgetting](./api-v5-memory-forgetting), [namespaces](./api-v5-settings), [organization](./api-v5-organization), and [filter](./api-v5-filters) changes independently.
- Migrate envelopes, attachments, pagination, profile buckets, system fields, and partial-error handling before switching traffic.
+ Migrate envelopes, includes, pagination, profile buckets, system fields, and partial-error handling before switching traffic.
Follow the [verification and rollout guide](./api-v5-rollout). Compare identity and behavior—not raw JSON ordering—and set changed defaults explicitly during rollout.
diff --git a/apps/docs/snippets/api-v5-rollout.mdx b/apps/docs/snippets/api-v5-rollout.mdx
index 35e05f64..bf468250 100644
--- a/apps/docs/snippets/api-v5-rollout.mdx
+++ b/apps/docs/snippets/api-v5-rollout.mdx
@@ -15,7 +15,7 @@ Record each legacy request, v5 request, expected semantic result, and intentiona
### Compare reads and recall
-- Document attachments are absent when omitted and empty arrays when requested without results.
+- Document includes are absent when omitted and empty arrays when requested without results.
- Unified list responses populate only the selected resource array.
- Search parity uses explicit v4-equivalent mode and threshold before testing v5 defaults.
- Profiles always contain static, dynamic, and bucket sections.
diff --git a/apps/docs/snippets/api-v5-search.mdx b/apps/docs/snippets/api-v5-search.mdx
index 2ba00d86..023189e7 100644
--- a/apps/docs/snippets/api-v5-search.mdx
+++ b/apps/docs/snippets/api-v5-search.mdx
@@ -1,4 +1,4 @@
-v5 searches one namespace, defaults to hybrid recall, and moves ranking controls into a typed request body.
+v5 searches one namespace, defaults to hybrid recall, and takes every option in one typed JSON body. Search has no query-string parameters.
### Request mapping
@@ -6,13 +6,13 @@ v5 searches one namespace, defaults to hybrid recall, and moves ranking controls
| --- | --- |
| `containerTag` | `/ns/{namespace}` |
| body `q` | body `query` |
-| body `limit` | query `limit` |
-| `searchMode: "documents"` | `searchMode=chunks` |
-| omitted search mode | `searchMode=hybrid` |
+| body `limit` | body `limit` |
+| `searchMode: "documents"` | `searchMode: "chunks"` |
+| omitted search mode | `searchMode: "hybrid"` |
| `filters` | singular `filter` |
-| `include.documents` or `.summaries` | `attach.documents` |
-| `include.relatedMemories` | `attach.related` |
-| `include.forgottenMemories` | `attach.forgotten` |
+| `include.documents` or `.summaries` | `include.documents` |
+| `include.relatedMemories` | `include.related` |
+| `include.forgottenMemories` | `include.forgotten` |
| `rerank: true` / `aggregate: true` | `rerank: "order"` / `"aggregate"` |
@@ -22,8 +22,8 @@ POST /v4/search
```
```bash v5
-POST /ns/user_1/search?limit=10&searchMode=memories
-{"query":"What did the user decide?","threshold":0.6,"rewriteQuery":false}
+POST /ns/user_1/search
+{"query":"What did the user decide?","limit":10,"searchMode":"memories","threshold":0.6,"rewriteQuery":false}
```
@@ -48,11 +48,13 @@ Set mode and threshold explicitly while comparing versions. After parity testing
Legacy `include.chunks` has no v5 equivalent. Choose `chunks` or `hybrid` instead.
-### Attachments and ranking
+### Included context and ranking
-- `attach.documents` adds the most relevant source document to each result.
-- `attach.related` adds parent, child, and sibling memories.
-- `attach.forgotten` allows forgotten memories in related context; it does not make them primary results.
+`include` is an object of booleans in the body, e.g. `"include": {"documents": true, "related": true}`. Each flag defaults to `false`.
+
+- `include.documents` adds the most relevant source document to each result.
+- `include.related` adds parent, child, and sibling memories.
+- `include.forgotten` lets forgotten and expired memories appear in results, including as primary results.
- `rerank` accepts `none`, `order`, or `aggregate`; `rewriteQuery` controls retrieval-oriented query rewriting.
### Response mapping
@@ -71,5 +73,5 @@ Each primary result contains either `memory`, `chunk`, or both only if the contr
- Compare IDs using explicit v4-equivalent defaults, then test v5 hybrid behavior separately.
- Cover all three modes, thresholds at `0` and `1`, each rerank option, and query rewriting.
-- Cover every attachment alone and in combination, including empty attachments.
+- Cover every include alone and in combination, including empty results.
- Verify filters, namespace isolation, result limits, and invalid body/query placement.
diff --git a/apps/docs/v5/api-reference/search.mdx b/apps/docs/v5/api-reference/search.mdx
index 9532fc1a..92cb0121 100644
--- a/apps/docs/v5/api-reference/search.mdx
+++ b/apps/docs/v5/api-reference/search.mdx
@@ -5,8 +5,8 @@ description: "Recall the most relevant memories and source context"
icon: "book-open"
---
-`POST /ns/{namespace}/search` recalls the most useful memories and source chunks for a query. Hybrid search combines both by default; use `searchMode=memories` or `searchMode=chunks` when your experience needs one result type.
+`POST /ns/{namespace}/search` recalls the most useful memories and source chunks for a query. Hybrid search combines both by default; set `searchMode` to `memories` or `chunks` when your experience needs one result type.
-Tune relevance with threshold, reranking, query rewriting, filters, and related context in the request body. Result controls `limit` and `searchMode` belong in the query string.
+Every option goes in the JSON request body: `query`, `searchMode`, `limit`, `threshold`, `filter`, `include`, `rerank`, and `rewriteQuery`.
See [search migration](/migration/api-v5-recall) and [typed filter migration](/migration/api-v5-filters).