From ca24440b4a08b75ac30a9700c6eecf9c36b8a20d Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Mon, 26 Oct 2026 20:23:42 +0800
Subject: [PATCH] docs(forward): clarify Decision API beta status

---
 CHANGELOG.md                       | 4 ++++
 README.md                          | 6 ++++--
 docs/api/reference.md              | 2 +-
 examples/forward/decisions/main.go | 1 +
 forward/decision.go                | 1 +
 5 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d95606..ee1db1f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,10 @@ existing `0.1.0` release; earlier development prereleases are not listed.
 
 ## [Unreleased]
 
+### Changed
+
+- Clarify that the Forward Decision API is in Beta and its behavior may change in future updates.
+
 ## [0.10.0]
 
 ### Added
diff --git a/README.md b/README.md
index 2222ddc..6eb6567 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ The SDK ships two clients that share authentication, transport, retries, error h
 - [System prompts and tools](#system-prompts-and-tools)
 - [Streaming](#streaming)
 - [Realtime Beta](#realtime-beta)
-- [Forward Decisions](#forward-decisions)
+- [Forward Decisions (Beta)](#forward-decisions-beta)
 - [Request fields](#request-fields)
 - [Response objects](#response-objects)
 - [Error handling](#error-handling)
@@ -659,7 +659,9 @@ For Session, Schedule, Batch, Deployment and Dream, the response to a create or
 
 Server-side windows and local deadlines are independent: a Batch `completion_window: "24h"` is submitted to the server, while the examples' `-timeout 5m` is only how long the local program waits. A Batch sitting in `queued` may not have started, and waiting longer does not change how the server schedules it. The examples cancel the work they created when they time out, so that run's output cannot be used to judge later execution.
 
-## Forward Decisions
+## Forward Decisions (Beta)
+
+The Decision API is in Beta. Its behavior may change in future updates.
 
 Evaluate a nonempty `state` object or an accessible `session_id` (exactly one)
 with 1–32 choice or score questions. Choice values are strings or booleans;
diff --git a/docs/api/reference.md b/docs/api/reference.md
index 42252b1..e35e38c 100644
--- a/docs/api/reference.md
+++ b/docs/api/reference.md
@@ -2886,7 +2886,7 @@ func (r *DecisionQuestionParam) UnmarshalJSON(data []byte) error
 <a name="DecisionService"></a>
 ## type [DecisionService](<https://github.com/QoderAI/qoder-cloud-agents-sdk-go/blob/main/forward/decision.go>)
 
-DecisionService evaluates explicit state or an accessible Session's recent history.
+DecisionService evaluates explicit state or an accessible Session's recent history. The Decision API is in Beta. Its behavior may change in future updates.
 
 ```go
 type DecisionService struct {
diff --git a/examples/forward/decisions/main.go b/examples/forward/decisions/main.go
index 58196e5..f1e269a 100644
--- a/examples/forward/decisions/main.go
+++ b/examples/forward/decisions/main.go
@@ -1,4 +1,5 @@
 // Evaluate sample state, or set QODER_DECISION_SESSION_ID to evaluate a Session.
+// The Decision API is in Beta. Its behavior may change in future updates.
 // Run: go run ./examples/forward/decisions -env .env.live
 package main
 
diff --git a/forward/decision.go b/forward/decision.go
index 4b79584..7c7cb4f 100644
--- a/forward/decision.go
+++ b/forward/decision.go
@@ -18,6 +18,7 @@ import (
 )
 
 // DecisionService evaluates explicit state or an accessible Session's recent history.
+// The Decision API is in Beta. Its behavior may change in future updates.
 type DecisionService struct {
 	Options []option.RequestOption
 }