feat(memory): add embedding hint routes and upgrade guidance

docs/config-reference.md

@@ -87,9 +87,37 @@ Notes:
 | `backend` | `sqlite` | `sqlite`, `lucid`, `markdown`, `none` |
 | `auto_save` | `true` | automatic persistence |
 | `embedding_provider` | `none` | `none`, `openai`, or custom endpoint |
+| `embedding_model` | `text-embedding-3-small` | embedding model ID, or `hint:<name>` route |
+| `embedding_dimensions` | `1536` | expected vector size for selected embedding model |
 | `vector_weight` | `0.7` | hybrid ranking vector weight |
 | `keyword_weight` | `0.3` | hybrid ranking keyword weight |
 
+## `[[model_routes]]` and `[[embedding_routes]]`
+
+Use route hints so integrations can keep stable names while model IDs evolve.
+
+```toml
+[memory]
+embedding_model = "hint:semantic"
+
+[[model_routes]]
+hint = "reasoning"
+provider = "openrouter"
+model = "provider/model-id"
+
+[[embedding_routes]]
+hint = "semantic"
+provider = "openai"
+model = "text-embedding-3-small"
+dimensions = 1536
+```
+
+Upgrade strategy:
+
+1. Keep hints stable (`hint:reasoning`, `hint:semantic`).
+2. Update only `model = "...new-version..."` in the route entries.
+3. Validate with `zeroclaw doctor` before restart/rollout.
+
 ## `[channels_config]`
 
 Top-level channel options are configured under `channels_config`.

docs/providers-reference.md

@@ -143,3 +143,56 @@ Then call with a hint model name (for example from tool or integration paths):
 ```text
 hint:reasoning
 ```
+
+## Embedding Routing (`hint:<name>`)
+
+You can route embedding calls with the same hint pattern using `[[embedding_routes]]`.
+Set `[memory].embedding_model` to a `hint:<name>` value to activate routing.
+
+```toml
+[memory]
+embedding_model = "hint:semantic"
+
+[[embedding_routes]]
+hint = "semantic"
+provider = "openai"
+model = "text-embedding-3-small"
+dimensions = 1536
+
+[[embedding_routes]]
+hint = "archive"
+provider = "custom:https://embed.example.com/v1"
+model = "your-embedding-model-id"
+dimensions = 1024
+```
+
+Supported embedding providers:
+
+- `none`
+- `openai`
+- `custom:<url>` (OpenAI-compatible embeddings endpoint)
+
+Optional per-route key override:
+
+```toml
+[[embedding_routes]]
+hint = "semantic"
+provider = "openai"
+model = "text-embedding-3-small"
+api_key = "sk-route-specific"
+```
+
+## Upgrading Models Safely
+
+Use stable hints and update only route targets when providers deprecate model IDs.
+
+Recommended workflow:
+
+1. Keep call sites stable (`hint:reasoning`, `hint:semantic`).
+2. Change only the target model under `[[model_routes]]` or `[[embedding_routes]]`.
+3. Run:
+   - `zeroclaw doctor`
+   - `zeroclaw status`
+4. Smoke test one representative flow (chat + memory retrieval) before rollout.
+
+This minimizes breakage because integrations and prompts do not need to change when model IDs are upgraded.