docs: specify workspace diagnostic protocols

backend/test/workspaces-contracts.test.ts

@@ -1,4 +1,6 @@
 import { expect, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
 import { buildInstallationContract, renderWorkspaceDocs } from "../src/workspaces/contracts.js";
 import { type CanonicalWorkspace, parseWorkspaceYaml } from "../src/workspaces/schema.js";
@@ -170,6 +172,45 @@ llm_policy:
   })).vector_db).toMatchObject({ database: "vector_database", schema: "vectors" });
 });
 
+test("documents the rendered writer secret-file binding for writer workspaces", () => {
+  const writerVariable = "THT_WS_PSD_CLINICAL_VECTOR_WRITER_API_KEY_FILE";
+  const generated = renderWorkspaceDocs(parseWorkspaceYaml(`workspace:
+  schema_version: 2
+  id: psd-clinical
+  name: Policlinico San Donato
+  language: it
+dwh:
+  engine: postgres
+  database: warehouse
+  schema: datawarehouse
+  supported_transports: [postgres_direct]
+semantic_index:
+  vector_store:
+    engine: pgvector
+    database: vector_database
+    schema: vectors
+    collection: clinical_documents
+    dimensions: 768
+    distance: cosine
+    supported_transports: [rest_api]
+  vector_writer: {}
+  embedding:
+    provider: ollama_compatible
+    model: nomic-embed-text-v2-moe
+    dimensions: 768
+llm_policy:
+  allowed: [zai/glm-5.2]
+`));
+  const protocolPath = fileURLToPath(new URL("../../docs/workspace-diagnostic-protocol.md", import.meta.url));
+
+  expect(generated.markdown).toContain(`\`${writerVariable}\``);
+  expect(generated.envExample).toContain(`${writerVariable}=`);
+  expect(existsSync(protocolPath)).toBe(true);
+  if (existsSync(protocolPath)) {
+    expect(readFileSync(protocolPath, "utf8")).toContain(writerVariable);
+  }
+});
+
 function withTransports(
   dwhTransport: CanonicalWorkspace["dwh"]["supported_transports"][number],
   vectorTransport: CanonicalWorkspace["semantic_index"]["vector_store"]["supported_transports"][number],