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

.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