diff --git a/.changeset/client-readme-retired-ai-methods.md b/.changeset/client-readme-retired-ai-methods.md
new file mode 100644
index 0000000000..0013cadf5e
--- /dev/null
+++ b/.changeset/client-readme-retired-ai-methods.md
@@ -0,0 +1,11 @@
+---
+"@objectstack/client": patch
+---
+
+The README's namespace tour documents the `ai` surface that exists, not the three methods v17 removed.
+
+`client.ai.nlq` / `.suggest` / `.insights` were deleted in 17.0.0 (#3718) — and no server in any repo ever mounted `/api/v1/ai/{nlq,suggest,insights}`, so they 404ed for the whole life of the namespace. The README's "AI Services" example still showed all three. Because `files` ships `README.md` inside the tarball, that example is the package's npm front page: a TypeScript reader copying it gets TS2339 on three properties that are not on `client.ai`, and a JavaScript reader gets a runtime `TypeError`.
+
+The block now shows the surface the client really exposes — `ai.chat` (with a read of `answer.content` / `answer.usage`), `ai.complete`, `ai.models`, `ai.conversations.list`, `ai.agents.chat`, `ai.pendingActions.list` — every call type-checked against the package's own published `dist/index.d.ts`. It also names the condition a reader will otherwise hit unexplained: the AI routes are served by `service-ai` (a Cloud/EE package), and an environment without it answers 501 rather than 404, with the remedy discovery reports under `services.ai`.
+
+No behaviour changes. `patch` rather than no changeset because the README is a published file of this package, so correcting it changes what `@objectstack/client` ships; the docs site's Client SDK page already carried this correction and is untouched here.
diff --git a/packages/client/README.md b/packages/client/README.md
index 742acff797..63c0e95c14 100644
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -259,10 +259,16 @@ await client.approvals.reject(requestId, 'Incomplete');
 await client.notifications.list({ read: false }); // unread only
 await client.notifications.markRead(['notif-1', 'notif-2']);
 
-// AI Services
-await client.ai.nlq({ query: 'Show me all active contacts' });
-await client.ai.suggest({ object: 'contact', field: 'industry' });
-await client.ai.insights({ object: 'sales', recordId: dealId });
+// AI Services — served by an AI service plugin (`service-ai`, a Cloud/EE
+// package). The `/ai` routes are mounted either way, so an environment without
+// it answers 501, not 404; discovery carries the same remedy under `services.ai`.
+const answer = await client.ai.chat({ messages: [{ role: 'user', content: 'How many open orders this quarter?' }] });
+console.log(answer.content, answer.usage?.totalTokens);
+await client.ai.complete({ prompt: 'Summarise this account in one line:' });
+await client.ai.models();                          // picker list — allowlist objects or bare ids, both live
+await client.ai.conversations.list({ limit: 20 });
+await client.ai.agents.chat('build', { messages: [{ role: 'user', content: 'Draft a follow-up' }] });
+await client.ai.pendingActions.list({ status: 'pending' });   // human-in-the-loop queue
 
 // Internationalization
 await client.i18n.getLocales();