docs(client): the README's AI example shows the surface that exists (#16212)

* docs(client): the README's AI example shows the surface that exists

`client.ai.nlq` / `.suggest` / `.insights` were removed in v17 (#3718), and
no server in any repo ever mounted `/api/v1/ai/{nlq,suggest,insights}` — every
call 404ed for the whole life of the namespace. The `@objectstack/client`
README's namespace tour still showed all three, and `files` ships `README.md`
inside the tarball, so that example is the package's npm front page: a
TypeScript reader copying it gets TS2339 and a JavaScript reader a runtime
`TypeError`.

Replaced with the live `ai` surface — `chat` (reading `answer.content` /
`answer.usage`), `complete`, `models`, `conversations.list`, `agents.chat`,
`pendingActions.list` — each call type-checked against this package's own
published `dist/index.d.ts`, with the removed three kept as a control that
still fails with TS2339 there. The comment also names the condition a reader
would otherwise hit unexplained: `/ai` is served by `service-ai` (Cloud/EE),
and an environment without it answers 501, not 404, carrying the remedy
discovery reports under `services.ai`.

The docs site's Client SDK page already carried this correction; it is
untouched here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

* docs(client): drop the ADR-0028 citation from the models example

ADR-0028 in this repository is Metadata Naming & Namespace Isolation
(Deferred) — it says nothing about a model allowlist or plan tiers, and no
ADR in docs/adr/ covers one. The citation was inherited verbatim from the
docblock chain rather than checked, which is the same failure this card
exists to correct.

"plan-filtered" went with it: `AiModelsResponseSchema` declares `models` as
a union of bare id strings and `{ id, label, default }` objects, and states
that both shapes are live — objects when the service exposes the allowlist,
bare ids when it falls back to the adapter's `listModels()`. Both are pinned
accepted in `protocol.test.ts`. The comment now says only what the schema
asserts unconditionally.

Comment text only; no code, no other line, no changeset change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

.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.

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();