## What and why
Add an agent-oriented V3/V4 to V5 migration guide covering document
ingestion and updates, content management, search, profiles, memory
forgetting, namespaces, organization settings, typed filters, and
rollout verification. Shared snippets keep the comprehensive guide and
the focused topic pages consistent, following the existing
`/snippets/*.mdx` import convention used elsewhere in the docs.
```mermaid
flowchart LR
Legacy[Legacy integration inventory] --> Mapping[Domain migration guidance]
Mapping --> V5[V5 requests and response readers]
V5 --> Verify[Side-by-side verification and rollout]
```
## Grounding
Every old-vs-new claim traces to code in this repository:
- `packages/validation/api.ts` - `SearchRequestSchema`,
`Searchv4RequestSchema`, `ListMemoriesQuerySchema`,
`MemoryUpdateSchema`, `BulkDeleteMemoriesSchema`,
`ContainerTagListTypeSchema`, `SearchFiltersSchema`.
- `packages/validation/schemas.ts` - `MemoryEntrySchema`,
`OrganizationSettingsSchema`, `MemoryRelationEnum`.
- `packages/tools/src/shared/memory-client.ts` and
`packages/tools/src/shared/types.ts` - the `/v4/profile` request and
`profile.static` / `profile.dynamic` / `profile.buckets` reader.
- `apps/mcp/src/server/client/index.ts` - live `/v3/container-tags/list`,
`/v4/memories/list`, and `/v3/documents/file` call sites.
## Notable findings documented
- `SearchFiltersSchema` is `z.array(z.unknown())` behind a
`// TODO: Improve filter schema` comment, so legacy conditions were
never validated at the edge. The typed-filter page documents the
mechanical conversion and calls out the numeric-string-to-JSON-number
trap that a straight rename would miss.
- `OrganizationSettingsSchema` carries connector credentials that are
absent from the public V5 `/organization` response; the page warns
against reading them from `GET /v3/settings`.
- Operations with no V5 replacement are listed explicitly rather than
given invented substitutes.
## Validation
- `docs.json` parses as JSON; all 11 new nav entries resolve to authored
pages, and every pre-existing nav entry still resolves.
- All 12 snippet imports and every relative/absolute link across the 23
new files resolve to real targets.
- Fences, braces, and JSX component tags balance across all new files;
frontmatter parses as YAML.
- `git diff --check` passes.
## Impact
Documentation only. No runtime, schema, or SDK behavior changes.
Keep docs asset URLs repo-root-relative and pass images as literal MDX children so Mintlify can compile them through OptimizedImage under the /docs mount.
Mintlify's official guidance says: “Image paths are root-relative from your docs repository.” It also says relative paths such as `./screenshot.png` are unsupported. See [Image embeds](https://www.mintlify.com/docs/create/image-embeds).
The existing `/images/...` paths were correct. The failure came from passing them through custom-component string props, which kept Mintlify from seeing those images during its MDX transform.
- fix hero, building-block, and Slack avatar images
- preserve Slack avatar clipping
- normalize Hermes and Company Brain icon sizing
Tested with Mintlify validation, broken-link checks, and browser checks across every changed route.
Fixes broken docs navigation and asset paths from the site audit.
- serves docs images from `/images` and adds the missing Cartesia icon
- corrects homepage, console, and LinkedIn destinations
- removes agent-only comparison headings from the web TOC
Tested with Mintlify validate and Mintlify broken-links.
