docs: specify workspace diagnostic protocols

docs/superpowers/specs/2026-08-03-git-workspace-registry-design.md

@@ -141,11 +141,34 @@ semantic_index:
       - pgvector_direct
       - rest_api
       - ssh_tunnel
+  vector_writer: {} # optional; enables a distinct, locally bound reversible diagnostic writer
   embedding:
     provider: ollama_compatible
     model: nomic-embed-text-v2-moe
     dimensions: 768
 
+diagnostics:
+  dwh_rest:
+    method: POST
+    path: /rpc/ping
+    auth: bearer
+    response: { database: database, schema: schema }
+  vector_rest:
+    metadata:
+      method: GET
+      path: /vector/metadata
+      auth: bearer
+      response: { collection: collection, dimensions: dimensions, distance: distance }
+    reversible_probe:
+      method: POST
+      path: /vector/diagnostic-probe
+      auth: bearer
+  embedding:
+    method: GET
+    path: /models
+    auth: none
+    response: { model: model, dimensions: dimensions }
+
 llm_policy:
   default: zai/glm-5.2
   allowed:
@@ -168,6 +191,11 @@ action that supplies the vector database/schema; it must never infer either valu
 The resulting descriptor is written as schema version 2 and then passes normal operational
 validation.
 
+The migration also preserves least privilege: `vector_writer` is optional and never inferred from
+the reader binding. A v2 descriptor without it is valid and operates reader-only. If it is
+declared, its local `VECTOR_WRITER_API_KEY_FILE` is distinct from the reader API-key file and is
+used only by the explicitly requested reversible writer diagnostic.
+
 ### 6.2 Semantic-index invariant
 
 `semantic_index` is atomic. The vector collection, vector dimensions, distance metric, embedding provider, embedding model, and embedding dimensions describe one index contract.
@@ -182,6 +210,21 @@ The following are validation errors:
 
 Changing collection, embedding model, dimensions, or metric is presented as replacing or migrating the semantic index, not as an individual user preference.
 
+### 6.3 Declared diagnostic protocol
+
+Diagnostics are declarative and strict. `dwh_rest` declares the DWH ping method, origin-relative
+path, authentication mode, and JSON fields that must equal the canonical DWH database/schema.
+`vector_rest.metadata` does the same for collection, dimensions, and distance. `embedding` declares
+the model/dimensions response fields. Only `GET` and `POST`, `none`/`bearer`/`x-api-key`
+authentication, origin-relative paths without a query or fragment, and identifier-shaped response
+field names are accepted.
+
+`vector_rest.reversible_probe`, when present, is POST-only. It is called with a generated
+diagnostic record create request and a matching remove request, with cleanup retried in `finally`.
+An upsert-only service cannot be declared as this probe. All ordinary diagnostics remain read-only.
+The complete request, response, timeout, reader-only fallback, SSH, and private-CA limitations are
+the operator contract in [Workspace diagnostic protocol](../../workspace-diagnostic-protocol.md).
+
 ## 7. Deterministic installation-variable naming
 
 The environment namespace is derived from the immutable workspace ID:
@@ -230,7 +273,20 @@ THT_WS_PSD_CLINICAL_EMBEDDING_TLS_CA_FILE=
 
 The embedding model and dimensions remain in the canonical workspace.
 
-### 7.4 SSH tunnel variables
+### 7.4 Optional vector-writer variable
+
+Only a descriptor declaring `semantic_index.vector_writer: {}` generates this local secret-file
+binding. It is never generated for a reader-only workspace:
+
+```dotenv
+THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE=
+```
+
+The generated workspace documentation and `.env.example` must render this exact `_FILE` variable
+when the optional writer exists. The path must be distinct from
+`THT_WS_PSD_CLINICAL_VECTOR_API_KEY_FILE`; neither file's content is rendered.
+
+### 7.5 SSH tunnel variables
 
 For any connector role `<ROLE>` that selects `ssh_tunnel`, ThothII requires:
 
@@ -260,6 +316,11 @@ Direct adapters connect to the configured host and port with the native protocol
 
 REST adapters use a base URL, an optional API-key file, TLS validation, and a documented capabilities endpoint. A REST adapter must expose enough metadata to validate schema or collection identity and semantic-index compatibility.
 
+The present diagnostic adapter cannot load a private CA from a REST `*_TLS_CA_FILE` binding. It
+therefore refuses that diagnostic rather than weakening certificate verification. Operators must
+use a runtime-trusted HTTPS chain, direct/SSH transport with native PostgreSQL CA handling, or a
+trusted TLS-termination boundary.
+
 ### 8.3 SSH tunnel
 
 SSH adapters verify the remote host against an explicit known-hosts file, open a temporary local tunnel, and pass the resulting endpoint to the corresponding direct adapter. Host-key checking cannot be disabled by the form.
@@ -308,6 +369,9 @@ Transport selection is installation-specific because a production server may con
 
 A vector write probe is an explicit action. It writes a uniquely named temporary record in a diagnostic namespace or transaction and removes it before returning. It is not part of ordinary save or publish.
 
+When no writer descriptor or distinct local writer file is present, the same workspace remains
+reader-only and the write probe is omitted; no reader credential is repurposed for writing.
+
 ## 10. Persistent server and local layout
 
 Both production and local Docker deployments use:
@@ -450,6 +514,8 @@ Save draft may retain incomplete local form state in the browser. Publish requir
 - SSH host verification and tunnel opening succeed.
 - Vector collection, dimensions, metric, and read capability match.
 - Embedding endpoint exposes the declared model and returns the expected dimensions for a controlled probe.
+- A requested writer probe has a declared reversible POST operation, distinct writer credential,
+  and successful bounded cleanup; otherwise it is omitted without weakening reader validation.
 
 A portable workspace can be valid but not activatable on a particular installation. Publish is allowed in that state; starting a new session on that installation is not.