docs(spec,client): stop documenting bare POST /ai/chat as agent-resolved (#10617)

* docs(spec,client): stop documenting bare POST /ai/chat as agent-resolved

Both docblocks asserted runtime behaviour that does not exist: the bare
chat route loads no agent and never reads context.appName. The default-agent
resolution chain is driven by the assistant chat route.

Refs #10510

* chore(changeset): patch note for the ai/chat doc correction

Refs #10510

---------

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

Author: Elon Musk

.changeset/ai-chat-not-agent-resolved.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": patch
+"@objectstack/client": patch
+---
+
+Stop documenting bare `POST /api/v1/ai/chat` as agent-resolved (#10510). Two
+shipped docblocks described a resolution step the route does not perform:
+`client.ai.agents` claimed `/ai/chat` "talks to the environment's default
+agent", and `App.defaultAgent` claimed that endpoint auto-resolves the app's
+agent from `context.appName`. The bare route loads no agent and never reads
+`context.appName`; the default-agent chain (explicit > `defaultAgent` of the
+named app > first active) is driven by the assistant chat endpoint,
+`POST /api/v1/ai/assistant/chat`, and `client.ai.agents.chat()` is the only SDK
+method that reaches an agent at all.
+
+Both sites read as a security-relevant scoping guarantee — an agent-resolved
+endpoint would have its tool offer scoped by that agent's skills (ADR-0063
+§1/§5) — so a reader auditing "which endpoints are surface-scoped?" from these
+declarations got the wrong answer at both. Documentation text only: no schema
+key, no parse behaviour and no runtime path changes.

packages/client/src/index.ts

@@ -4240,10 +4240,13 @@ export class ObjectStackClient {
     /**
      * Named agents.
      *
-     * `/ai/chat` talks to the environment's default agent; these talk to one
-     * you name. Both routes have been mounted since long before this namespace
-     * existed — `objectui` hand-built their URLs in five places because the SDK
-     * offered nothing to call (#3718).
+     * These are the only SDK methods that reach an agent. `POST /ai/chat`
+     * (`ai.chat` / `ai.chatStream`) is a raw chat plane that resolves no agent
+     * at all — it loads none, so nothing about that call is scoped by an
+     * agent's skills. Read it as agent-less, never as "the environment's
+     * default agent". Both routes have been mounted since long before this
+     * namespace existed — `objectui` hand-built their URLs in five places
+     * because the SDK offered nothing to call (#3718).
      */
     agents: {
       /**

packages/spec/src/ui/app.zod.ts

@@ -1500,9 +1500,15 @@ export const AppSchema = lazySchema(() => strictObject(
   /**
    * Default agent for this app's ambient chat surface.
    *
-   * When set, the ambient chat endpoint (`POST /api/v1/ai/chat` with
-   * `context.appName`) auto-resolves to this agent without the user
-   * having to pick from a list.
+   * When set, the assistant chat endpoint (`POST /api/v1/ai/assistant/chat`)
+   * resolves this agent for a call carrying `context.appName`, without the
+   * user having to pick from a list — that route is what drives the
+   * resolution chain (explicit agent > `defaultAgent` of the named app >
+   * first active agent).
+   *
+   * The bare `POST /api/v1/ai/chat` route is NOT part of that chain: it
+   * resolves no agent and never reads `context.appName`, so this key does not
+   * scope it. Do not read this key as a guarantee over that endpoint.
    *
    * ADR-0063 §1/§2 — this is a SURFACE-BINDING knob, not a custom-agent
    * slot: the resolvable values are the two platform agents (`ask` for a