docs: document internal semantic infrastructure

README.md

@@ -6,8 +6,7 @@ external in this profile, except for the mandatory internal semantic services bu
 
 ## Docker Compose: local startup
 
-Requirements: Docker Engine with Compose v2. The mandatory stack is `frontend`, `core`,
-`qdrant`, `embedding`, and the one-shot `embedding-model-init`. DWH and LLM remain external,
+Requirements: Docker Engine with Compose v2. The mandatory stack is `frontend`, `core`, `qdrant`, `embedding`, and the one-shot `embedding-model-init`. DWH and LLM remain external,
 configurable endpoints—even when they are co-located with ThothII.
 
 From a fresh clone, run these commands from the repository root:
@@ -44,9 +43,11 @@ loopback port).
 Credentials and certificates are local protected files. Do not put them in environment examples,
 workspace YAML, URLs, or Compose interpolation values.
 
-Application state is split across the named `settings`, `pi-state`, `workspace-registry`, and
-`sessions` volumes. `docker compose down` keeps them. Only an explicit destructive command such
-as `docker compose down --volumes` removes them.
+Application state is split across the named `settings`, `pi-state`, `workspace-registry`,
+`sessions`, `qdrant-data`, and `embedding-models` volumes. `docker compose down` keeps them.
+`qdrant-data` is a derived but persistent index store; `embedding-models` is an Ollama model
+cache for `qwen3-embedding:0.6b` with fixed `1024`-dimension embeddings. Only an explicit destructive command such as `docker compose
+down --volumes` removes them.
 
 The frontend depends on the core health check and proxies `/health` and `/api/*` to it. The
 application health endpoint intentionally checks process readiness only; external dependency
@@ -69,6 +70,11 @@ every revision referenced by an open, closed, or failed unarchived session. It r
 single local installation list or from a server administrator's complete session list, never from
 a remote user's partial list.
 
+Schema-v3 is the operational descriptor contract. Schema-v1/v2 descriptors remain
+`migration_required` until an explicit reviewed migration writes schema version 3. One workspace
+owns one Qdrant collection; schema, Evidence, and Memory records share that collection and stay
+separated by indexed payload `kind`.
+
 Connector `ssh_tunnel` bindings are diagnostic-only in this release: their bounded probe always
 cleans up the loopback forward and returns `workspace_not_activatable`; session creation is rejected
 before persistence. Git registry access over SSH is unaffected. Use direct or REST connector
@@ -211,7 +217,7 @@ archive path.
 
 Restore targets that same exact project-scoped `qdrant-data` volume. Because restore replaces the
 persistent Qdrant data in place, it requires an explicit confirmation that exactly repeats the
-Compose project name:
+Compose project name by passing `--confirm-project`:
 
 ```sh
 ./scripts/vector-restore.sh \
@@ -223,7 +229,9 @@ Compose project name:
 The restore script stops `qdrant`, validates the exact labeled target, stages the current volume
 contents for rollback, extracts the requested archive into the volume, and then returns the
 service to its prior running state. After restore, run the backend health checks and a known
-retrieval query before reopening write traffic.
+retrieval query before reopening write traffic. Restore does not migrate schema-v1/v2 workspace
+descriptors, does not rename collections, and does not reconcile an incompatible collection
+contract; those remain explicit reviewed recovery steps outside the helper.
 
 ## Production trust boundary and secrets