From 2215e8bb98d8592c39c44d81b8beba1d65eaae99 Mon Sep 17 00:00:00 2001
From: moonyue-w <300878504+moonyue-w@users.noreply.github.com>
Date: Mon, 26 Oct 2026 20:23:43 +0800
Subject: [PATCH] docs(forward): clarify Decision API beta status

---
 CHANGELOG.md                           | 4 ++++
 README.md                              | 4 +++-
 docs/api/reference.md                  | 4 ++++
 examples/forward/decisions.py          | 2 ++
 src/qca/forward/resources/decisions.py | 4 ++++
 5 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6c267f..20b871e 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 6058a82..d3cd372 100644
--- a/README.md
+++ b/README.md
@@ -609,7 +609,9 @@ credential = client.vaults.credentials.retrieve("credential-id", vault_id="vault
 memory = client.memory_stores.memories.retrieve("memory-id", memory_store_id="store-id")
 ```
 
-## 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 9dbc2e1..77b6ec1 100644
--- a/docs/api/reference.md
+++ b/docs/api/reference.md
@@ -3389,6 +3389,8 @@ class Decisions(SyncAPIResource)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/resources/decisions.py)
 
+The Decision API is in Beta. Its behavior may change in future updates.
+
 <a id="qca.forward.resources.decisions.Decisions.create"></a>
 
 #### create
@@ -3475,6 +3477,8 @@ class AsyncDecisions(AsyncAPIResource)
 
 [[view_source]](https://github.com/QoderAI/qoder-cloud-agents-sdk-python/blob/main/src/qca/forward/resources/decisions.py)
 
+The Decision API is in Beta. Its behavior may change in future updates.
+
 <a id="qca.forward.resources.decisions.AsyncDecisions.create"></a>
 
 #### create
diff --git a/examples/forward/decisions.py b/examples/forward/decisions.py
index 027b43b..81e5d2c 100644
--- a/examples/forward/decisions.py
+++ b/examples/forward/decisions.py
@@ -1,5 +1,7 @@
 """Create a Decision using shared PAT/SA configuration.
 
+The Decision API is in Beta. Its behavior may change in future updates.
+
 Run: python -m examples.forward.decisions --env .env.live
 Optionally set QODER_DECISION_SESSION_ID to evaluate an accessible Session.
 """
diff --git a/src/qca/forward/resources/decisions.py b/src/qca/forward/resources/decisions.py
index ce076d9..1a3f857 100644
--- a/src/qca/forward/resources/decisions.py
+++ b/src/qca/forward/resources/decisions.py
@@ -15,6 +15,8 @@
 
 
 class Decisions(SyncAPIResource):
+    """The Decision API is in Beta. Its behavior may change in future updates."""
+
     def create(
         self,
         *,
@@ -105,6 +107,8 @@ def list(
 
 
 class AsyncDecisions(AsyncAPIResource):
+    """The Decision API is in Beta. Its behavior may change in future updates."""
+
     async def create(
         self,
         *,