docs: document internal semantic infrastructure

scripts/test-verify-workspace-install-docs.sh

@@ -11,6 +11,7 @@ trap 'rm -f "$output" "$verifier_functions"; rm -rf "$negative_root"' EXIT HUP I
 "$root/scripts/verify-workspace-install-docs.sh" --fixtures-only >"$output"
 
 for fixture in \
+  "internal semantic infrastructure documentation contract" \
   "local installation guide contract" \
   "source update fail-closed semantics" \
   "Windows line-ending recovery guide contract" \
@@ -35,6 +36,25 @@ for fixture in \
   }
 done
 
+grep -Fq '## Internal Qdrant + Ollama semantic infrastructure' "$root/PROJECT_STATE.md" || {
+  echo "PROJECT_STATE.md does not record the internal Qdrant/Ollama snapshot" >&2
+  exit 1
+}
+grep -Fq 'Qdrant and Ollama are internal Compose services' "$root/AGENTS.md" || {
+  echo "AGENTS.md does not record the stable internal semantic-service guidance" >&2
+  exit 1
+}
+grep -Fq 'Do not add vector or embedding endpoint credentials to the bundle.' \
+  "$root/deploy/secrets/README.md" || {
+  echo "secret bundle guide still permits vector/embedding runtime secrets" >&2
+  exit 1
+}
+if rg -n 'engine: pgvector|provider: ollama_compatible|THT_WS_<NAMESPACE>_VECTOR_TRANSPORT|THT_WS_<NAMESPACE>_EMBEDDING_BASE_URL' \
+  "$root/docs/workspace-diagnostic-protocol.md"; then
+  echo "workspace diagnostic protocol still documents external vector or embedding contracts" >&2
+  exit 1
+fi
+
 server_guide="$root/docs/install/server.md"
 grep -Fq 'scripts/prepare-server-pi-state.sh /srv/thothii/pi-state 10001 10001' "$server_guide" || {
   echo "server guide does not initialize nested Pi-state targets before Compose" >&2

scripts/verify-workspace-install-docs.sh

@@ -43,6 +43,18 @@ verify_path_variable_values() {
   done <"$source"
 }
 
+require_absent() {
+  local source="$1" label="$2"
+  shift 2
+  local forbidden
+  for forbidden in "$@"; do
+    if grep -Fq -- "$forbidden" "$source"; then
+      echo "$label contains forbidden text: $forbidden" >&2
+      return 1
+    fi
+  done
+}
+
 require_headings() {
   local source="$1" label="$2"
   shift 2
@@ -67,6 +79,80 @@ require_text() {
   done
 }
 
+verify_internal_semantic_infrastructure_docs() {
+  local readme="$root/README.md"
+  local agents="$root/AGENTS.md"
+  local project_state="$root/PROJECT_STATE.md"
+  local local_manual="$root/docs/install/local-workspace-registry.md"
+  local server_manual="$root/docs/install/server-workspace-registry.md"
+  local compact_manual="$root/docs/installazione-docker-4-contesti.md"
+  local diagnostics="$root/docs/workspace-diagnostic-protocol.md"
+  local memory="$root/docs/gestione-memory.md"
+  local secrets="$root/deploy/secrets/README.md"
+
+  require_text "$readme" "README" \
+    'mandatory stack is `frontend`, `core`, `qdrant`, `embedding`, and the one-shot `embedding-model-init`' \
+    '`qwen3-embedding:0.6b`' \
+    '`1024`' \
+    '`qdrant-data`' \
+    '`embedding-models`' \
+    '`--confirm-project`' || return 1
+  require_text "$agents" "AGENTS.md" \
+    'Run the local Docker stack with `./scripts/run-stack.sh` after creating `deploy/env/local.env`; it starts the base+local Compose' \
+    'Qdrant and Ollama are internal Compose services' \
+    'DWH and LLM remain external configuration endpoints.' || return 1
+  require_text "$project_state" "PROJECT_STATE.md" \
+    '## Internal Qdrant + Ollama semantic infrastructure' \
+    'Schema-v3 descriptors are operational; schema-v1/v2 descriptors remain `migration_required` until an explicit reviewed migration writes schema version 3.' \
+    'One workspace owns one Qdrant collection' || return 1
+
+  for manual in "$local_manual" "$server_manual"; do
+    require_text "$manual" "$(basename "$manual")" \
+      '`frontend`, `core`, `qdrant`, `embedding`, and the one-shot `embedding-model-init`' \
+      '`qwen3-embedding:0.6b`' \
+      '`1024`' \
+      '`migration_required`' \
+      'One workspace owns one Qdrant collection' || return 1
+  done
+  require_text "$local_manual" "local workspace manual" \
+    'CPU-first' \
+    'THOTH_ENABLE_EMBEDDING_GPU=1' \
+    'Qdrant is a derived but persistent index' || return 1
+  require_text "$server_manual" "server workspace manual" \
+    'Only the Git remote, DWH, LLM, and optional bastion endpoints stay external.' \
+    'Ollama model cache' \
+    'Qdrant backup/restore' || return 1
+
+  require_text "$compact_manual" "four-context install note" \
+    'Qdrant e Ollama embedding sono servizi interni obbligatori del progetto Compose. Restano esterni solo DWH e LLM.' \
+    'qwen3-embedding:0.6b' \
+    '1024 dimensioni' || return 1
+
+  require_text "$diagnostics" "workspace diagnostic protocol" \
+    'schema version 3' \
+    'One workspace owns one Qdrant collection.' \
+    '`semantic_index_incompatible`' || return 1
+  require_absent "$diagnostics" "workspace diagnostic protocol" \
+    'engine: pgvector' \
+    'provider: ollama_compatible' \
+    'THT_WS_<NAMESPACE>_VECTOR_TRANSPORT' \
+    'THT_WS_<NAMESPACE>_EMBEDDING_BASE_URL' || return 1
+
+  require_text "$memory" "memory guide" \
+    'Indice Qdrant' \
+    'Qdrant resta un indice derivato ma persistente' \
+    '`kind`' || return 1
+  require_absent "$memory" "memory guide" \
+    'Indice pgvector' \
+    'save-one costruisce un solo `VectorRecord` e lo invia all''indice pgvector.' || return 1
+
+  require_text "$secrets" "deploy secrets guide" \
+    '`THT_MODEL_API_KEY`, `THT_DWH_API_KEY`, `THT_CA`, and `THT_SSL_CA`' \
+    'Do not add vector or embedding endpoint credentials to the bundle.' || return 1
+  require_absent "$secrets" "deploy secrets guide" \
+    'PI_PROVIDER_API_KEY' || return 1
+}
+
 verify_local_guide() {
   local guide="$root/docs/install/local.md"
   [[ -f "$guide" ]] || {
@@ -1459,6 +1545,8 @@ NODE
 case "$mode" in
   --fixtures-only)
     [[ $# -eq 1 ]] || { echo "usage: $0 --fixtures-only" >&2; exit 2; }
+    verify_internal_semantic_infrastructure_docs
+    echo "internal semantic infrastructure documentation contract passed"
     verify_local_guide
     verify_windows_line_endings_guide
     verify_pi_management_guide
@@ -1476,11 +1564,13 @@ case "$mode" in
     [[ $# -eq 2 && "$profile" =~ ^(local|server)$ ]] \
       || { echo "usage: $0 --profile {local|server}" >&2; exit 2; }
     if [[ "$profile" == local ]]; then
+      verify_internal_semantic_infrastructure_docs
       verify_local_guide
       verify_windows_line_endings_guide
       verify_pi_management_guide
       verify_local_installation_example
     else
+      verify_internal_semantic_infrastructure_docs
       verify_server_guide
       verify_reverse_proxy_nginx_guide
       verify_reverse_proxy_caddy_guide