docs(retrieval): mark evidenceText as deprecated and always empty

.changeset/deprecate-evidence-text.md

@@ -0,0 +1,5 @@
+---
+"@ontos-ai/knowhere-sdk": patch
+---
+
+Mark evidenceText as deprecated and always empty. Consume evidence instead.

README.md

@@ -311,8 +311,8 @@ const response = await client.retrieval.query({
 
 console.log(response.answerText); // LLM-generated answer
 console.log(response.referencedChunks); // cited evidence chunks
-console.log(response.evidence); // composed parts to consume (text/HTML and inline images)
-console.log(response.evidenceText); // text projection of those parts
+console.log(response.evidence); // grouped [E n] parts (text/HTML and inline images)
+console.log(response.evidenceText); // deprecated; always empty. Use evidence.
 console.log(response.stopReason); // agentic termination reason, when returned
 console.log(response.failureReason); // no-answer reason, when returned
 

src/knowledge/__tests__/knowledge.test.ts

@@ -1201,7 +1201,7 @@ function createClient(parseResult: ParseResult): {
     routerUsed: 'legacy',
     answerText: null,
     evidence: [{ type: 'text', text: 'Margin guidance improved.' }],
-    evidenceText: '[report.md / Revenue]\nMargin guidance improved.',
+    evidenceText: '',
     referencedChunks: [
       {
         documentId: 'doc-1',

src/resources/__tests__/retrieval-wire.test.ts

@@ -95,7 +95,7 @@ describe('Retrieval wire response', () => {
             { type: 'text', text: 'before' },
             { type: 'image', media_type: 'image/png', data: 'abc' },
           ],
-          evidence_text: 'beforedata:image/png;base64,abc',
+          evidence_text: '',
           results: [
             {
               content: '[images/a.png]',

src/resources/__tests__/retrieval.test.ts

@@ -200,7 +200,7 @@ describe('Retrieval Resource', () => {
       query: 'test',
       routerUsed: 'workflow_single_step',
       answerText: 'LLM-generated answer',
-      evidenceText: 'Rendered retrieval evidence',
+      evidenceText: '',
       stopReason: 'answer_done',
       failureReason: 'insufficient evidence',
       decisionTrace: [
@@ -242,7 +242,7 @@ describe('Retrieval Resource', () => {
     const referencedChunk: RetrievalReferencedChunk | undefined = response.referencedChunks[0];
 
     expect(typedResponse.answerText).toBe('LLM-generated answer');
-    expect(response.evidenceText).toBe('Rendered retrieval evidence');
+    expect(response.evidenceText).toBe('');
     expect(response.stopReason).toBe('answer_done');
     expect(response.failureReason).toBe('insufficient evidence');
     expect(response.referencedChunks).toHaveLength(1);

src/types/retrieval.ts

@@ -155,7 +155,7 @@ export interface RetrievalReferencedChunk {
  *
  * Downstream agents consume:
  * - `evidence`: composed parts (text/HTML and inline images)
- * - `evidenceText`: text projection of those parts
+ * - `evidenceText`: deprecated; always empty. Use `evidence`.
  * - `results`: raw path chunks for debug
  * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
  * - `referencedChunks`: structured chunk citations for follow-up queries
@@ -173,7 +173,7 @@ export interface RetrievalQueryResponse {
   answerText: string | null;
   /** Cited evidence chunks with asset URLs when available */
   referencedChunks: RetrievalReferencedChunk[];
-  /** Text projection of evidence. Tables stay as HTML; images are data URLs. */
+  /** Deprecated. Always empty. Use evidence. */
   evidenceText?: string | null;
   /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
   stopReason?: string | null;