From 3ff759ad66a0785e18c93a501e129033c00bf01a Mon Sep 17 00:00:00 2001
From: Ed_ <edwardgz@gmail.com>
Date: Thu, 2 Jul 2026 18:55:20 -0400
Subject: [PATCH] =?UTF-8?q?docs(api):=20fix=20backwards=20send=5Fresult=20?=
 =?UTF-8?q?claim=20=E2=80=94=20send()=20is=20canonical?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

product-guidelines.md claimed send_result() was canonical and send()
was removed. The reverse is true: send() is the live public API
returning Result[str, ErrorInfo]; send_result exists only as a local
var in _send_gemini_cli. Corrected the section and added a
reconciliation note. Also fixed guide_ai_client.md send() signature
to show -> Result[str] instead of -> str.
---
 conductor/product-guidelines.md | 23 +++++++++++++++++------
 docs/guide_ai_client.md         |  4 ++--
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md
index a4e953cd..57ea4e73 100644
--- a/conductor/product-guidelines.md
+++ b/conductor/product-guidelines.md
@@ -188,13 +188,24 @@ function. The audit script `scripts/audit_optional_in_3_files.py` enforces
 this rule by failing CI on new `Optional[X]` return types in the 3
 refactored files.
 
-### Public API: `ai_client.send_result()` (RESOLVED 2026-06-15)
+### Public API: `ai_client.send()` (current as of 2026-07-02)
 
-The public `ai_client.send_result()` is the canonical public API. It
-returns `Result[str, ErrorInfo]`. The legacy `ai_client.send()` was
-removed in the `public_api_migration_and_ui_polish_20260615` track on
-2026-06-15 (see `conductor/tracks/public_api_migration_and_ui_polish_20260615/spec.md`).
-All production call sites and tests now use `send_result()`.
+The public `ai_client.send()` is the canonical public API. It returns
+`Result[str, ErrorInfo]` (the data-oriented error type from
+`src/result_types.py`). Check `result.ok` for success; on failure,
+`result.errors` holds classified `ErrorInfo` instances. All provider
+calls go through `send()`, which routes to the provider-specific
+`_send_<vendor>()` helpers. The tests in `tests/test_ai_client_result.py`
+verify the `Result` contract.
+
+> **Note (corrected 2026-07-02):** a previous version of this section
+> claimed `send_result()` was the canonical API and `send()` was
+> removed. That was backwards against the current code — `send()` is
+> live and `send_result` does not exist as a public function (it
+> appears only as a local variable in `_send_gemini_cli`). The
+> migration may have been reverted or the prior claim was always wrong;
+> either way, the source of truth is `src/ai_client.py:send` and
+> `tests/test_ai_client_result.py`.
 
 </new_content>
 ## Testing Requirements
diff --git a/docs/guide_ai_client.md b/docs/guide_ai_client.md
index 9574bd6e..0559de92 100644
--- a/docs/guide_ai_client.md
+++ b/docs/guide_ai_client.md
@@ -106,10 +106,10 @@ def send(
     stream_callback: Optional[Callable] = None,
     patch_callback: Optional[Callable] = None,
     rag_engine: Optional[Any] = None,
-) -> str:
+) -> Result[str]:
 ```
 
-Returns the model's response as a string. All provider calls go through here.
+Returns the model's response as a `Result[str, ErrorInfo]` (the data-oriented error type from `src/result_types.py`). Check `result.ok` for success; on failure, `result.errors` holds `ErrorInfo` instances with classified `ErrorKind`. All provider calls go through here.
 
 **Parameters:**
 - `md_content` — the system prompt + context (markdown)